wallaby-cli

Wallaby 会在整个编码任务期间让 JavaScript、TypeScript 和 Python 测试持续运行并可供查询。它会在文件变更时运行受影响的测试，并保留当前结果、覆盖率和执行数据，以便 Agent 检查代码的实际表现，而不必从终端输出中还原情况。

Wallaby 不会取代项目现有的测试设置，无论项目使用的是 Vitest、Jest、Jasmine、Mocha、Angular 的 ng test、pytest、Python 的 unittest，还是其他受支持的框架。它会通过相应框架运行现有测试，并为编码 Agent 提供实时的受影响测试执行、保留且可查询的状态、覆盖率产物、执行跟踪和运行时检查。在编码任务期间执行和分析测试时，请使用 Wallaby，而不要直接调用这些框架。只有在用户明确要求直接运行时，才运行 npm test、npx vitest 或 ng test 等常规测试命令。

利用这些实时测试状态来：

• 在编辑前建立基线，检查当前失败项、覆盖率，以及会执行你计划修改代码的测试。
• 编辑时让反馈聚焦。从相关测试开始，随着变更范围扩大，加入相关测试；任务需要时，最后进行项目范围的验证。
• 分析一批文件、一个源文件或测试文件、一个确切的源代码位置，或紧凑摘要中的一个测试；然后仅在需要时查看单独的覆盖率和相关测试产物。利用覆盖率、变更风险、测试状态和耗时来决定要修改什么，以及需要进行多大范围的验证。
• 分析一个测试在各源文件中的结果和覆盖率。添加 --trace 以重新运行该测试，并按执行顺序跟踪记录的源代码行，涵盖涉及的所有文件。跟踪包括导入的模块和设置，标记所选测试的开始，并继续记录该测试执行到的每一行源代码。同一份报告还会提供测试状态、耗时、错误、日志和覆盖的文件，作为辅助诊断信息。
• 在一次请求中检查不同源代码位置上的多个变量或表达式。每个值都会在到达其所在位置的每个测试上下文中捕获，并关联到生成该值的测试。缩小调查范围时，可将合并结果筛选为一个测试。在修改代码或添加临时日志之前，先利用这些运行时证据。
• 利用项目范围的覆盖率，以及测试和文件指标（如耗时、测试数量、复杂度和变更风险），找出有意义的测试缺口、耗时较长或耦合紧密的测试，以及需要扩大验证范围的变更。

命令生成报告时，先查看简洁的 Markdown 输出；只有当前问题需要更多上下文时，才打开链接的报告和产物。Wallaby 会将生成的每份报告和产物保存到磁盘上的带时间戳目录中，因此在需要比较时，早期结果仍可作为历史快照使用。

环境要求

在沙箱中，CLI 需要对 ~/.wallaby 具有读写权限。下载或更新 Wallaby 时，它需要访问网络 https://*.wallabyjs.com；如果尚未安装 @wallabyjs/cli，还需要访问已配置的 npm registry。

Wallaby 后台进程必须持续运行，并在多次 CLI 调用之间保持可访问。每次后续调用都需要通过 PID 找到同一个进程，并连接到启动时建立的本地端口。某些沙箱化的 Agent 运行时会隔离各次 shell 工具执行：共享工作目录和文件系统并不保证进程可见性或本地网络访问也共享。因此，即使原实例仍在运行，一次成功的 run 后，也可能在另一次执行中遇到 Wallaby is not running 或 Failed to attach。

在执行第一个 Wallaby 命令之前，请选择一个能在 shell 命令之间保持运行的执行上下文，然后在整个任务中，每次调用 Wallaby CLI 时都复用该上下文。如果查询在成功启动后无法连接，请先在原执行上下文中重试，再尝试重新启动。保留已配置的沙箱权限。

调用 CLI

首先根据项目的 packageManager 字段、锁文件或现有项目命令，确认项目已使用的包管理器。Wallaby 也使用同一个包管理器：npx 是 npm 的调用方式，只应用于 npm 项目。然后使用该包管理器的第一个适用调用方式。

如果 @wallabyjs/cli 已作为项目依赖安装，请通过项目的包管理器运行 wallaby-skill：

• npm：npx wallaby-skill ...
• pnpm：pnpm exec wallaby-skill ...
• Yarn：yarn exec wallaby-skill ...
• Bun：bun run wallaby-skill ...

否则，如果 @wallabyjs/cli 已全局安装，且 wallaby-skill 可通过 PATH 找到，请直接运行：

• wallaby-skill ...

否则，请使用项目包管理器的一次性安装命令。每条命令都会从已配置的 npm registry 下载 @wallabyjs/cli 并运行 wallaby-skill，因此需要网络访问：

• npm：npx -y --package @wallabyjs/cli wallaby-skill ...
• pnpm：pnpm dlx --package=@wallabyjs/cli wallaby-skill ...
• Yarn：yarn dlx -p @wallabyjs/cli wallaby-skill ...
• Bun：bunx --package @wallabyjs/cli wallaby-skill ...

为保持一致，以下示例使用 npm 前缀 npx wallaby-skill。在 pnpm、Yarn 或 Bun 项目中执行示例之前，只需将该前缀替换为上述对应形式；Wallaby 子命令及其参数保持不变。

每个子命令都支持 --help。将其附加到命令即可查看当前用法和选项，例如 npx wallaby-skill run --help。

根据平台以及可用工具，使用 grep、sed、ripgrep 或类似工具进行定向读取。所有示例都使用 ripgrep（rg）。

输出重定向

仅当你要筛选出与当前问题相关的部分时，才将 Wallaby 命令的标准输出和标准错误重定向到临时文件。将筛选读取命令放在同一行、同一次工具调用中执行，以节省 token 和模型往返次数。需要完整报告时，请直接读取命令输出；如果只是用 cat 打印整个文件，将输出重定向到文件并无益处。例如，在 POSIX shell 中，运行测试后立即提取状态、测试数量和错误诊断：

npx wallaby-skill run >| /tmp/wallaby-output.log 2>&1; rg --no-line-number -U --pcre2 -o '(?sm)^(?:Status:|- (?:Total|Passed|Failed|Skipped|Todo):)[^\n]*|^## (?:Fatal Error|Global Errors|Failing Tests)\r?\n.*?(?=^## |\z)' /tmp/wallaby-output.log

读取日志中的状态和错误，以及当前问题所需的覆盖率或运行时证据，检查结果。如果摘录缺少所需上下文，请扩大摘录范围。

运行命令

使用 run 启动或查询持久运行的 Wallaby 测试会话。不带 --config 时，Wallaby 根据命令运行所在的目录识别项目。带 --config 时，Wallaby 根据指定的 Wallaby 配置文件识别项目。后续调用时保持相同的工作目录或 --config 值，以复用正在运行的会话及其实时结果。

能够访问同一运行实例的 Agent 线程会按项目身份共享 Wallaby 会话。例如，如果多个线程在同一个 Git 工作树中工作，并调用 run --config ./wallaby.js，那么只要它们的执行环境允许，就会连接到同一会话。不带 --config 并从同一目录运行时，情况也相同。会话的模式、范围和实时测试状态均为共享状态：任何线程修改文件时，Wallaby 都会在后台重新运行受影响的测试，所有已连接的线程都可以读取更新后的结果、覆盖率和执行数据。

如果项目尚未运行 Wallaby，首次调用 run 会确定会话模式：

• 不指定测试文件路径时，Wallaby 以项目模式启动，运行并监视整个项目。
• 指定一个或多个测试文件路径时，Wallaby 以独占模式启动，只运行并监视这些测试文件。

直接使用 run 启动所需范围，无需事先调用 run --check。它会启动或复用项目会话，并返回报告。

冷启动项目模式必须先完成一次初始全量测试运行，而项目范围的 --rerun 会重新安排所有测试。这两种情况在测试套件较大时都可能耗时很久。除非任务需要项目范围的覆盖率或全套验证，否则应以独占模式启动或保留范围最小的相关测试文件。阅读返回报告中的 Mode。在项目模式下，使用 Total 和 Time 估算项目范围重新运行可能需要的时间。在独占模式下，这些值只涵盖当前活动范围。要从独占会话估算项目范围的耗时，请访问报告中的绝对路径链接，进入带时间戳的目录，然后检查保留的同级目录，找到最近一份 Mode: project 的 run.md。

后续调用 run 会复用同一会话：

• 在项目模式下，如果传入测试文件路径，但不带 --rerun 或 --snapshots，则只读取当前项目范围的状态，不会安排另一轮运行，也不会缩小监视范围。内联报告会将所请求文件中的失败排在最前面。
• 在独占模式下，传入其他测试文件路径会将这些文件加入当前独占范围。
• 在独占模式下，不传入测试文件路径调用 run 会将会话扩展为项目模式。随后 Wallaby 会运行并监视整个项目，之后按文件指定范围的调用也不会将其改回独占模式。

每条命令执行后，Wallaby 都会继续保持会话运行；文件发生变化时，它会在后台运行受影响的测试，并向 run、analyze 和 inspect 提供实时数据。当会话已包含所需测试后，如果 analyze 或 inspect 报告提供了所需数据，请直接调用它们；只有需要从报告中获取数据时才调用 run。如果在测试执行期间调用其中任何命令，它都会等待 Wallaby 空闲。在等待期间进行的进一步编辑会安排运行受影响的测试，并延长等待时间，因此返回的报告会包含这些更改。

对于耗时较长的初始运行或项目范围运行，请在后台终端或获授权的子 Agent 中启动 run，同时继续独立分析或编辑。Wallaby 会检测命令运行期间所做的更改，并在命令返回前完成受影响的测试。请等待命令完成后，再通过该终端发送另一条 Wallaby 命令，或将其报告用作验证结果。 默认省略 --rerun。最近的编辑、最终验证或计时测量都不会导致实时结果过时。只有在确认实时状态过时后，才使用 --rerun 进行恢复。合理原因包括 Wallaby 无法监视的相关外部状态，或观察到预期的受监视变更后未能重新运行。强制执行前，先说明原因。将恢复范围限制在已知受影响的最小测试集：传入测试文件路径，只重新运行这些文件；如果只需重新运行一个指定测试，则添加 --test。在项目模式下，使用定向 --rerun 不会重新运行项目的其余部分，也不会将会话切换为独占模式。只有在有证据表明整个项目的实时结果都已过时时，才省略测试文件路径。

确认快照失败反映了预期的输出变更后，使用 --snapshots。将更新范围限制在受影响的测试：传入测试文件路径，只更新这些文件的快照；添加 --test 可更新一个指定测试的快照。在项目模式下，定向更新快照会使会话保持项目模式，也不会更新其他测试的快照。只有在需要更新整个项目的快照时，才省略测试文件路径。如果 Wallaby 尚未运行，仍适用上述首次运行模式规则。

若要使用 --test 定位一个测试，请传入且仅传入一个测试文件，以及该测试的准确完整名称，其中包含以 / 连接的套件路径。如果名称与该文件中已执行的测试不匹配，Wallaby 会退回到整个测试文件。传入多个文件路径时，--test 不会缩小选择范围。

npx wallaby-skill run # starts or reuses project mode and reports project-wide test results
npx wallaby-skill run --config ./wallaby.js # starts or reuses project mode identified by the specified config file
npx wallaby-skill run ./src/feature-a.spec.ts # starts or extends exclusive scope, or reads this file's results in project mode
npx wallaby-skill run ./src/feature-a.spec.ts ./src/feature-b.spec.ts # starts exclusive mode if needed, or reads their results according to the active mode
npx wallaby-skill run ./src/feature-a.spec.ts --test "feature-a / should match the expected value" # reads this exact test after any automatic affected-test run finishes
npx wallaby-skill run --rerun ./src/feature-a.spec.ts # forces this test file to rerun after observing stale results; add --test with the exact full name to rerun one test
npx wallaby-skill run --snapshots ./src/feature-a.spec.ts ./src/feature-b.spec.ts # updates snapshots only for the specified test files
npx wallaby-skill run --snapshots ./src/feature-a.spec.ts --test "feature-a / should match the expected snapshots" # updates snapshots for the named test in the specified file
npx wallaby-skill run --snapshots # updates snapshots across the project; use only when every snapshot change is intended
npx wallaby-skill run --check # returns the current report only when Wallaby is already running; does not launch or run tests

该命令会输出简洁的 Markdown 报告，并将相同内容保存为 run.md。生成报告时，退出代码 0 对应 Status: succeeded；退出代码 1 对应 Status: failed。只要至少有一个测试失败、Wallaby 出现致命运行错误，或存在全局错误，状态就会是失败。CLI 启动、连接和兼容性失败也会以代码 1 退出，但可能会打印错误，而不是生成报告。

请按以下顺序阅读报告：

• Status 和 Mode 用于说明当前状态是否成功，以及该状态代表整个项目还是仅代表当前启用的独占测试位置。
• Runner 和 Framework 用于标识执行环境和测试框架（如果 Wallaby 能够报告）。
• 在独占模式下，Note: Wallaby is running tests only from specific test locations: 会列出当前启用的范围。报告中的所有计数和覆盖率值均仅适用于这些位置。
• Summary 包含以下字段：
  • Total：测试总数。
  • Passed：通过的测试数。
  • Failed：失败的测试数。
  • Skipped：跳过的测试数。
  • Todo：待处理的测试数。
  • Coverage：测试覆盖的可覆盖代码范围百分比。覆盖率较低时，Wallaby 会附加 (low)。
  • Time：测试执行时间总和，按报告中每个测试的执行时间累加计算。
• Fatal Error 用于显示运行级错误，包括个别测试开始运行前发生的错误。
• Global Errors 用于显示未关联到测试的错误，内联显示的错误最多为 3 个。如果错误更多，报告会链接到包含所有全局错误的 global-errors.md。请阅读 references/global-errors.md 了解其格式。
• Failing Tests 内联显示最多 5 个失败项，包括其名称、位置、耗时、错误、断言或快照详情、堆栈跟踪、日志和覆盖的文件。run 传入的文件路径所对应的失败项会排在最前面。如果失败项更多，报告会链接到包含所有失败项的 failing-tests.md。请阅读 references/failing-tests.md 了解其格式。
• 如果 Wallaby 捕获了单个测试之外的日志，Global Logs 会链接到 global-logs.md。请阅读 references/global-logs.md 了解其格式。
• 如果存在测试，All Tests 会链接到 all-tests.md。链接的报告包含按耗时和测试数量排序的排名，随后列出每个测试的状态、位置、耗时、日志和覆盖的文件；失败诊断信息仍位于 Failing Tests 中。请阅读 references/all-tests.md 了解其格式。
• 如果存在可报告的覆盖率，Coverage 会链接到 coverage.md。链接的报告会按变更风险对文件排序，并列出每个受覆盖源文件的覆盖率、复杂度、变更风险和覆盖该文件的测试文件。请阅读 references/coverage.md 了解其格式。
• 如果存在 UI URL，Graphical User Interface 会链接到 Wallaby UI。仅在用户明确要求打开 UI 时使用此链接。

在 All Tests 中查找所有提及 estimates sleet near freezing 的测试：

rg -U --pcre2 -o '(?sm)^### [^\n]*estimates sleet near freezing[^\n]*\n.*?(?=^### |^## |\z)' all-tests.md

查找 tests/temperature.spec.ts 中的所有测试：

rg -U --pcre2 -o '(?sm)^## tests/temperature\.spec\.ts[^\n]*\n.*?(?=^## |\z)' all-tests.md

查找 src/temperature.ts 的覆盖率条目：

rg -U --pcre2 -o '(?sm)^## src/temperature\.ts[^\n]*\n.*?(?=^## |\z)' coverage.md

Analyze 命令

使用 analyze 查找未覆盖的代码、确定哪些测试覆盖了某个文件或位置、检查测试失败，或跨文件跟踪测试的执行过程。根据所需信息选择分析类型：

• 测试分析会提供测试结果，以及该测试覆盖的所有源文件的覆盖率；还可以使用 --trace 获取可选的执行跟踪。
• 文件分析会提供文件的覆盖率，以及覆盖该文件或文件中某个位置的测试信息，或属于某个测试文件的测试信息。覆盖率和测试信息可以筛选到特定测试。
• 文件集分析会通过一份合并的 Coverage Gaps 报告，在一条命令中提供一批文件各自的覆盖率和测试信息。

将分析报告中的覆盖率指标以及 Uncovered 行和列范围作为主要覆盖率依据。只有在这些信息不足以回答某个具体覆盖率问题、且需要详细的源代码注释时，才读取报告链接的 .wcov 文件。需要时，只读取相关区域。

只有当 Wallaby 已使用与 run 相同的项目标识运行时，此命令才有效。先在项目模式下启动 Wallaby，或在包含待分析测试文件或覆盖待分析源文件的测试的独占模式下启动。然后从与 run 相同的工作目录运行 analyze，或为其使用相同的 --config 值。在包含所需测试的活动会话中，无需先运行 run，编辑后也不例外。

如果测试分析或单文件分析无法解析请求的目标，命令会以非零代码退出，并打印错误消息，而不是生成报告。这包括路径无效、文件缺失、测试目标路径不是测试文件、缺少测试名称，或无法解析源文件位置等情况。文件集分析会在 Files Not Analyzed 下报告特定路径的失败，同时仍会分析能够解析的路径。

该命令会打印 Markdown 报告，并将相同内容保存为 analyze.md。

分析类型

测试分析

需要调查某个测试的结果、错误或日志，验证其在源文件中的覆盖情况，或追踪其执行过程以解释异常行为时，请使用 --target test。

传入测试文件路径和完整、精确的测试名称，包括以 / 连接的测试套件名称：

npx wallaby-skill analyze --target="test" "{path:'tests/temperature.spec.ts',name:'celsiusToFahrenheit / converts boiling point'}"

需要追踪执行顺序或跨文件控制流，以解释失败、意外通过、错误或日志时，请添加 --trace。它返回与不使用 --trace 时相同的报告，并额外附上 Test Execution Trace 链接。

npx wallaby-skill analyze --target="test" "{path:'tests/temperature.spec.ts',name:'celsiusToFahrenheit / converts boiling point'}" --trace

主要报告包括：

• Status、Mode，以及任何 Fatal Error 或 Global Errors，其含义与 run 命令报告中的相同。Status 描述当前会话，因此即使所选测试通过，它也可能是 failed。
• Test Analysis，包含所选测试的完整名称、状态，以及可用的位置、执行时间、错误、断言或快照差异、带源代码上下文的堆栈跟踪和日志。
  • 使用 --trace 时，测试条目之前会附上 Test Execution Trace 链接。跟踪会按顺序显示跨文件执行的源代码行，包括导入和设置，并用 test starts here 标记所选测试的第一行。有关其格式，请阅读 references/test-trace.md。
• Covered Files，其中为每个可导出覆盖率的已覆盖源文件提供条目。
  • 文件元数据和可用指标包括路径、行数、覆盖率、change risk anti-patterns 和大小。覆盖率指标仅针对所选测试。
  • 文件存在覆盖率缺口时，Uncovered: 会列出完全未覆盖的行，以及部分覆盖行中未覆盖的列范围。
  • 每个 Detailed Coverage 链接都指向一个 .wcov 产物，显示所选测试对该文件的完整覆盖情况。
• Run Report 链接指向一份报告，其格式与 run 命令报告相同，可根据同一会话状态进行更广泛的诊断。

生成的 Test Execution Trace 产物可能很大。请优先使用定向搜索，而不是读取整个产物。例如，要查找所选测试的起始位置：

rg -n -B 20 -A 5 'test starts here' test-trace.md

文件分析

当你需要查找源文件中的覆盖率缺口、识别覆盖某个源文件或其中指定行号或行号与列号位置的测试、调查测试文件中的失败，或验证特定测试在源文件中覆盖了哪些行和表达式时，请使用 --target file。

传入包含必需 path 的选择器。需要查找覆盖特定行或特定行号与列号的测试时，添加 location。如果你知道行号和表达式，但不知道列号，请传入 line 和 expression；Wallaby 会解析列号。如果你知道源代码片段和表达式，请传入 fragment 和 expression；Wallaby 会解析行号和列号。对多行片段使用 base64 编码的 fragment 可以避免转义特殊字符和换行符。CLI 会在搜索文件前解码该片段。

npx wallaby-skill analyze --target="file" "{path:'src/temperature.ts'}" # analyzes the specified source file
npx wallaby-skill analyze --target="file" "{path:'src/temperature.spec.ts'}" # analyzes the specified test file
npx wallaby-skill analyze --target="file" "{path:'src/temperature.ts',location:{line:10}}" # analyzes the specified location in the source file by line number
npx wallaby-skill analyze --target="file" "{path:'src/temperature.ts',location:{line:10,expression:'celsius'}}" # analyzes the specified location in the source file by line number, using the expression to resolve the column
npx wallaby-skill analyze --target="file" "{path:'src/temperature.ts',location:{line:10,column:10}}" # analyzes the specified location in the source file by line and column numbers
npx wallaby-skill analyze --target="file" "{path:'src/temperature.ts',location:{fragment:'return (celsius * 9) / 5 + 32;',expression:'celsius'}}" # analyzes the specified location in the source file by fragment search, using the expression to resolve the line and column in the first fragment match
npx wallaby-skill analyze --target="file" "{path:'src/temperature.ts',location:{fragment:'cmV0dXJuIChjZWxzaXVzICogOSkgLyA1ICsgMzI7',expression:'celsius'}}" # analyzes the specified location in the source file by base64-encoded fragment search, using the expression to resolve the line and column in the first fragment match

若要将所选文件的覆盖率和相关测试筛选到一个测试，请使用 --test，并传入该测试文件的路径和准确的完整名称，包括以 / 连接的套件名称。

npx wallaby-skill analyze --target="file" "{path:'src/temperature.ts'}" --test "{path:'tests/temperature.spec.ts',name:'celsiusToFahrenheit / converts boiling point'}" # analyzes the specified source file and filters to the exact test

若要查看该测试覆盖的所有源文件的覆盖率，请使用 --target test，不要使用 --trace。

主报告包含：

• Status、Mode，以及任何 Fatal Error 或 Global Errors，其含义与 run 命令报告中的相同。
• 针对源文件的 File Analysis，或针对测试文件的 Test File Analysis。
  • 文件元数据和可用的分析指标，例如路径、位置、测试数量、行数、覆盖率、change risk anti-patterns 和大小。当 --test 筛选条件匹配时，覆盖率指标和 .wcov 文件仅针对所选测试。
  • 文件存在覆盖率缺口时，Uncovered: 会列出完全未覆盖的行，以及部分覆盖行中未覆盖的列范围。
  • 最多显示五条相关的失败测试记录，每条记录以完整测试名称为标题，并显示状态、位置、耗时、错误消息、断言或快照差异、包含源代码上下文的堆栈跟踪、日志，以及可用时的覆盖文件。相关性取决于选择器：覆盖某个源文件或位置的测试、属于某个测试文件的测试，或筛选条件匹配的测试。如果失败测试超过五条，则在源文件的 Covering Tests 链接或测试文件的 Tests 链接之前显示省略的失败数量。这些链接包含完整的相关测试清单，包括被省略的失败测试。
• 源文件的 Covering Tests 链接或测试文件的 Tests 链接会指向一个单独的文件，其中包含完整的相关测试清单。主报告不会内嵌该清单。链接会显示文件大小；除非需要测试标识、状态、位置、耗时、日志或覆盖文件，否则不要打开较大的测试清单。如果只关注某个测试或属性，请直接搜索。有关两种文件结构，请阅读 references/file-tests.md。
• Detailed Coverage 链接指向 .wcov 文件，其中显示该文件的完整覆盖率。
• Run Report 链接指向一份与 run 命令报告格式相同的报告，用于查看同一会话状态的更全面诊断信息。

Covering Tests 和 Tests 清单可能很大。选择或调查相关测试时再打开这些清单，并优先使用定向搜索，而不是读取整个清单。例如，要查找某个测试：

rg -U --pcre2 -o '(?sm)^### [^\n]*generates severe heat alert[^\n]*\n.*?(?=^### |^## |\z)' [email protected]

文件分析

当你需要比较多个源文件之间的覆盖率缺口，或在一份报告中查看多个源文件或测试文件的覆盖率及相关测试信息时，请使用 --target files。

传入 paths 数组，分析与任务相关的特定源文件或测试文件：

npx wallaby-skill analyze --target="files" "{paths:['src/accounts.ts','src/contracts.ts']}" # analyzes the specified source files
npx wallaby-skill analyze --target="files" "{paths:['src/accounts.ts','tests/accounts.spec.ts']}" # analyzes the specified source and test files

选择器仅接受文件路径。使用 --target file 分析特定源代码位置，或将其与 --test 结合使用，将某个文件的覆盖率和相关测试结果筛选为一个特定测试。

省略选择器，即可分析当前会话中覆盖率最低且可报告的最多 20 个源文件。

npx wallaby-skill analyze --target="files" # analyzes up to 20 source files with the lowest coverage

主报告包括：

• Status、Mode，以及任何 Fatal Error 或 Global Errors，其含义与 run 命令报告中的相同。
• Files Analysis，包含文件表格和简要覆盖率详情。
  • 源文件表格会列出每个已分析源文件的路径、覆盖率、变更风险和缺口数量，包括没有缺口或覆盖率不可用的文件。行始终按覆盖率从低到高、变更风险从高到低、路径排序；指标不可用的文件排在最后。
  • 如果包含测试文件，则测试文件表格会显示路径、测试数量和失败测试数量。
  • 源文件表格之后会按其顺序列出最多 20 个简短的 ### <path> 分节。如果文件存在缺口，Uncovered: 后会列出未覆盖的行号和列范围；否则，该分节会说明没有缺口或覆盖率不可用。
  • Files Not Analyzed 列出无法分析的路径。主报告最多显示三个错误；链接的 Coverage Gaps 报告会包含所有错误。
• Coverage Gaps 链接到完整的批量报告，其中包含每个已分析文件的详细结果，包括未覆盖的表达式文本，以及指向 Covering Tests 或 Tests 和 Detailed Coverage 的链接。详情请参阅 references/coverage-gaps.md。
• Run Report 链接到与 run 命令报告格式相同的报告，用于查看同一会话状态下更广泛的诊断信息。

要列出 Coverage Gaps 中每个文件分节标题及其行号：

rg -n '^## ' coverage-gaps.md

要在报告中查找 src/accounts.ts 的标题及其行号：

rg -n -Fx '## src/accounts.ts' coverage-gaps.md

要打印 src/accounts.ts 的完整分节，从其标题开始，到下一个文件分节之前结束：

rg -U --pcre2 -o '(?sm)^## src/accounts\.ts\n.*?(?=^## |\z)' coverage-gaps.md

详细覆盖率

.wcov 文件包含完整的源文件，并标注源代码行号和覆盖状态：full、partial 或 none。它保留源文件的行数和行位置：文件中的第 N 行对应源文件中的第 N 行，因此可以直接按源代码行号定位覆盖率信息。对于部分覆盖的行，如果可用，也会标明未覆盖的表达式范围。使用它可以在源代码上下文中查看哪些行和表达式已执行或未执行。测试分析和带有匹配 --test 筛选条件的文件分析会显示所选测试的覆盖率；否则，覆盖率反映当前会话的情况。格式说明请参阅 references/wcov.md。

文件可能很大。请优先进行定向搜索，而不是通读全文。例如，要查找部分覆盖的行：

rg -n 'coverage: partial' [email protected]

要查找完全未覆盖的行：

rg -n 'coverage: none' [email protected]

要显示 src/alerts.ts 中第 146 行及其覆盖率标注：

sed -n '146p' [email protected]

要查找带有覆盖率标注及其周围行的源代码表达式：

rg -n -C 3 -F 'alerts.push({' [email protected]

Inspect 命令

当静态源代码、覆盖率、错误和现有日志都无法解释依赖运行时状态的故障或意外行为时，请直接使用 inspect。在精确的源代码位置检查变量和表达式，以跟踪状态变化、检查分支背后的输入和条件，或了解断言为何收到特定值。请使用这些运行时证据，而不是临时添加并在之后删除 console.log 语句。 只有在 Wallaby 已针对 run 使用的同一项目身份运行时，该命令才有效。请先以项目模式启动 Wallaby，或以包含能到达所检查位置的测试的独占模式启动。然后从与 run 相同的工作目录运行 inspect，或使用与 run 相同的 --config 值。在包含所需测试的活动会话中，无需先运行 run，即使在编辑之后也是如此。

每次检查都会捕获在每个到达其源代码位置的测试执行上下文中，该表达式的值，并标明产生每个值的测试。可在一次请求中传入多个文件和位置的检查目标，以便一并调查相关的运行时状态。使用 --test 可将主报告缩小到匹配测试的值，同时保留指向完整未筛选结果的链接。

对于请求中每个已解析的检查目标，Wallaby 都会添加临时运行时检测，然后执行受影响测试的合集，以收集所有请求的值。命令会等待这些测试完成后，再返回一致的报告。--test 用于筛选报告中的值；它不会限制执行哪些受影响的测试。

收集完这些值后，使用不带检查目标的 inspect --clear 将其移除。仅包含清除操作的请求不会安排测试，并会在会话空闲时立即完成。当 --clear 与新的检查目标一起使用时，Wallaby 会先清除之前的值，再添加新的检测，并按常规执行受影响的测试。

将每个检查目标作为单独参数传入，其中包含文件路径、源代码位置和表达式。源代码位置可以是代码片段、行号，或行号和列号。例如，要检查 src/alerts.ts 中 alerts 变量的值：

npx wallaby-skill inspect "{path:'src/alerts.ts',location:{fragment:'const alerts: WeatherAlert[] = [];'},expression:'alerts'}" "{path:'src/alerts.ts',location:{line:134},expression:'alerts'}"

对于基于片段的位置，该片段既用作文件搜索条件，也用作在文件中定位表达式的包含片段。对于编码 Agent，基于片段的位置通常更合适，因为无需计算行号。

对 fragment 进行 Base64 编码，可避免对多行片段中的特殊字符和换行符进行转义。CLI 会在搜索文件前解码片段：

npx wallaby-skill inspect "{path:'src/alerts.ts',location:{fragment:'Ly8gdW5pcXVlIGNvZGUgZnJhZ21lbnQKY29uc3QgYWxlcnRzOiBXZWF0aGVyQWxlcnRbXSA9IFtdOw=='},expression:'alerts'}"

如果已知行号，请使用行号代替片段：

npx wallaby-skill inspect "{path:'src/alerts.ts',location:{line:134},expression:'alerts'}"

如果同一行附近有多个表达式匹配项，请添加列号以选取距离最近的匹配项：

npx wallaby-skill inspect "{path:'src/alerts.ts',location:{line:134,column:10},expression:'alerts'}"

若要仅在主报告中显示由名称匹配的测试生成的值，请使用 --test 并传入完整或部分测试名称：

npx wallaby-skill inspect "{path:'src/alerts.ts',location:{line:134},expression:'alerts'}" --test "alerts output / combined conditions"

若要清除所有先前捕获的运行时值，请传入 --clear：

npx wallaby-skill inspect "{path:'src/alerts.ts',location:{line:134},expression:'alerts'}" --clear # clears all captured runtime values and adds new inspection
npx wallaby-skill inspect --clear # clears all captured runtime values

如果使用 --clear 时未提供检查目标，命令会打印 Cleared all captured runtime values.，而不是 Markdown 报告。

否则，命令会打印 Markdown 报告，并将相同内容保存为 inspect.md。非零退出代码通常表示报告中包含失败的测试或错误，但也可能表示 CLI 或 Wallaby 本身发生故障：

• Status、Mode 以及任何 Fatal Error 或 Global Errors，其含义与 run 命令报告中的相同。
• Runtime Values 会在行内显示捕获的值，以及对应的源文件、行号、表达式、格式化后的值和生成该值的测试。如果无法捕获请求检查的值，也会显示警告，其中包含路径、表达式、位置和原因。如果省略了其他值，则会链接到完整的运行时值报告。需要了解完整的运行时值报告格式时，请阅读 references/runtime-values.md。
• 使用 --test 时，主报告会按测试名称筛选运行时值；如果还有其他值可用，则会链接到未筛选的完整报告。未捕获检查的警告仍会显示，因为它们描述的是请求检查的位置，而非特定测试捕获的值。
• Run Report 会链接到一份与 run 命令报告格式相同的报告，用于查看同一会话状态下更全面的诊断信息。

要在 Runtime Values 中查找 src/alerts.ts 的所有捕获值：

rg -U --pcre2 -o '(?sm)^## src/alerts\.ts[^\n]*\n.*?(?=^## |\z)' runtime-values.md

要查找所有名称中包含 combined conditions 的测试所生成的运行时值：

rg -U --pcre2 -o '(?sm)^## [^\n]*\n.*?^- name: .*combined conditions.*\n.*?(?=^## |\z)' runtime-values.md

Stop command

首次运行 run 后，Wallaby 会继续在后台运行，监视项目文件，并将实时测试状态提供给后续命令。不要在常规调用 run、analyze 和 inspect 之间停止它。启用自动关闭时，Wallaby 会在检测到的 Agent 进程结束后停止。如果一段时间内没有 CLI 活动，它也会停止：检测到 Agent 进程时为 20 分钟，无法匹配到受支持的 Agent 进程时为 5 分钟。

当需要替换或释放运行中的进程时，请显式使用 stop：

• 安装、更新或移除 Node 模块前，请先停止 Wallaby，再更改依赖项，然后使用 run 重新启动。Wallaby 不会监视 node_modules 内的变更，因此现有进程无法可靠地使用更新后的依赖项。
• 使用不同的 Wallaby 配置或运行时环境重新启动前，请先停止现有会话。
• 用户提出要求、需要干净地重新启动，或运行中的进程必须在自动关闭前释放资源时，请立即停止。

无论会话处于项目模式还是独占模式，stop 使用的项目标识都与 run 相同。请从相同的工作目录调用，或使用与 run 相同的 --config 值调用。切换配置时，请先使用旧会话现有的项目标识停止它，再启动新会话。

npx wallaby-skill stop # stops the session identified by the current working directory
npx wallaby-skill stop --config ./wallaby.js # stops the session identified by this Wallaby configuration file

Update command

当 run 报告 Wallaby Core 兼容性错误时，请更新 Core，然后重试相同的 run 命令：

npx wallaby-skill update