> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 命令行工具

Rstest 提供了一个轻量级的命令行工具，包含 [rstest watch](#rstest-watch) 和 [rstest run](#rstest-run) 等命令。

## rstest -h

`rstest -h` 可帮助你查看所有可用的 CLI 命令及选项：

```bash
npx rstest -h
```

输出如下：

```bash
Usage:
  $ rstest [...filters]

Commands:
  [...filters]              run tests
  run [...filters]          run tests without watch mode
  watch [...filters]        run tests in watch mode
  list [...filters]         lists all test files that Rstest will run
  merge-reports [path]      Merge blob reports from multiple shards into a unified report
  init [project]            Initialize rstest configuration

Options:
  -h, --help                Display this message
  -v, --version             Display version number
```

可以通过 `npx rstest <command> -h` 查看命令专属参数。例如，`npx rstest init -h` 只会显示初始化相关参数，而 `npx rstest merge-reports -h` 只会显示合并报告相关参数。

## rstest \[...filters]

直接运行 `rstest` 命令将会在当前目录执行 Rstest 测试。

```bash
$ npx rstest

✓ test/index.test.ts (2 tests) 1ms

  Test Files 1 passed (1)
       Tests 2 passed (2)
    Duration 189 ms (build 22 ms, tests 167 ms)
```

用成对的单引号或双引号包裹 filter，可精确匹配绝对路径或相对于 root 的路径；shell 会去掉一层引号，因此需要两层：

```bash
rstest run '"src/foo.test.ts"'
```

### Watch 模式

如果你希望在文件更改时自动重新运行测试，可以使用 `--watch` 或 `rstest watch` 命令：

```bash
$ npx rstest --watch
```

## rstest run

`rstest run` 将会执行单次测试，该命令适用于 CI 环境或不需要一边修改一边执行测试的场景。

### 运行相关测试


[Added in v0.10.0](https://github.com/web-infra-dev/rstest/releases/tag/v0.10.0)

当你希望把命令行位置参数视为源码文件，并只运行依赖这些源码的测试时，可以使用 `--related`：

```bash
npx rstest run --related src/button.ts
```

Rstest 会基于构建得到的 module graph 解析相关测试，因此同一套过滤逻辑同时适用于 Node mode 和 Browser Mode。你也可以使用兼容 Jest 的别名：

```bash
npx rstest run --findRelatedTests src/button.ts
```

如果你只想查看受影响的测试文件，可以配合 `rstest list` 使用：

```bash
npx rstest list --related src/button.ts --filesOnly
```

`--related` 和 `--findRelatedTests` 不支持在 watch 模式下使用，watch 模式本身已经会重跑受文件变更影响的测试。

### 运行变更相关测试


[Added in v0.10.0](https://github.com/web-infra-dev/rstest/releases/tag/v0.10.0)

使用 `--changed` 可以从当前 Git 仓库收集变更文件，并运行这些文件相关的测试。默认会包含 unstaged、staged 和 untracked 文件，适合在本地提交前快速验证：

```bash
npx rstest run --changed
```

你也可以传入 commit 或 branch。Rstest 会包含该 ref 与 `HEAD` 之间的变更文件，以及本地 staged、unstaged 和 untracked 文件：

```bash
npx rstest run --changed=HEAD~1
npx rstest run --changed=origin/main
```

当变更文件命中 [`forceRerunTriggers`](/zh/config/test/force-rerun-triggers.md) 时，Rstest 会运行完整测试套件，而不是只运行相关测试。

开启覆盖率且未配置 [`coverage.changed`](/zh/config/test/coverage.md#changed) 时，`--changed` 也会将覆盖率报告限制在变更的源文件范围内。如果变更文件命中 [`forceRerunTriggers`](/zh/config/test/force-rerun-triggers.md)，Rstest 会运行完整测试套件，并生成完整覆盖率报告，除非显式启用了 `coverage.changed`。

如果只想预览将要执行哪些测试，可以配合 `rstest list` 使用：

```bash
npx rstest list --changed --filesOnly
```

`--changed` 不能和位置参数、`--related` / `--findRelatedTests` 一起使用，因为它已经从 Git 状态提供了源码文件过滤条件。它同样不支持在 watch 模式下使用。

### 运行分片 \{#sharding-tests}

使用 `--shard <index>/<count>` 将测试文件拆分为多个分片并行运行。`count` 表示总的分片数量，`index`（从 1 开始）表示要运行的分片。

```bash
# 将测试分成 3 个分片，运行第 1 个分片
npx rstest run --shard 1/3
```

这在 CI/CD 中尤其有用 —— 将测试套件拆分到多个 job 以减少整体测试时间，然后用 [`rstest merge-reports`](#rstest-merge-reports) 合并各分片的报告。

测试文件会按其路径排序，以确保在不同运行中分片结果一致；分片发生在测试文件扫描阶段，早于构建过程，以优化性能。请确保 `count` 和 `index` 的值有效（`1 <= index <= count`）。

## rstest watch

`rstest watch` 将会启动监听模式并执行测试，当测试或依赖文件修改时，将重新执行关联的测试文件。

## rstest list

`rstest list` 将会打印所有匹配条件的测试列表。默认情况下，它将打印所有匹配条件的测试名称。

```bash
$ npx rstest list

# 输出如下：
a.test.ts > test a > test a-1
a.test.ts > test a-2
b.test.ts > test b > test b-1
b.test.ts > test b-2
```

`rstest list` 命令继承所有 `rstest` 过滤选项，你可以直接过滤文件或使用 `-t` 过滤指定的测试名称。

```bash
$ npx rstest list -t='test a'

# 输出如下：
a.test.ts > test a > test a-1
a.test.ts > test a-2
```

你可以使用 `--filesOnly` 使其仅打印测试文件：

```bash
$ npx rstest list --filesOnly

# 输出如下：
a.test.ts
b.test.ts
```

你可以使用 `--json` 使其以 JSON 格式打印测试或将结果保存到单独的文件中：

```bash
$ npx rstest list --json

$ npx rstest list --json=./output.json
```

您可以使用 `--includeSuites` 选项，在打印测试用例的同时输出测试套件信息：

```bash
$ npx rstest list

# 输出如下：
a.test.ts > test a
a.test.ts > test a > test a-1
a.test.ts > test a-2
b.test.ts > test b
b.test.ts > test b > test b-1
b.test.ts > test b-2
```

您可以使用 `--printLocation` 选项来打印测试的位置信息：

```bash
$ npx rstest list

# 输出如下：
a.test.ts:4:5 > test a > test a-1
a.test.ts:9:3 > test a-2
b.test.ts:4:5 > test b > test b-1
b.test.ts:9:3 > test b-2
```

你可以使用 `--summary` 在列表输出后追加一段简要统计：

```bash
$ npx rstest list --summary

# 输出如下：
a.test.ts > test a > test a-1
a.test.ts > test a-2
b.test.ts > test b > test b-1
b.test.ts > test b-2
c.test.ts > test c it each 0
c.test.ts > test c it for 0
c.test.ts > test c it runIf
c.test.ts > test c it skipIf

 Test Files 3 matched
      Tests 8 matched
```

当与 `--json` 一起使用时，`--summary` 会把 JSON 输出从数组切换为包含 `items` 和 `summary` 字段的对象。

## rstest merge-reports


[Added in v0.9.3](https://github.com/web-infra-dev/rstest/releases/tag/v0.9.3)

`rstest merge-reports` 将多个测试分片生成的 blob 报告合并为一个统一的报告。当使用 [`--shard`](#sharding-tests) 在多台 CI 机器上并行运行测试时，这非常有用。

### 工作流程

1. 使用 `blob` 报告器运行每个分片以生成 blob 报告文件：

```bash
# 在 CI 机器 1 上
npx rstest run --shard 1/3 --reporters=blob

# 在 CI 机器 2 上
npx rstest run --shard 2/3 --reporters=blob

# 在 CI 机器 3 上
npx rstest run --shard 3/3 --reporters=blob
```

2. 将所有 `.rstest-reports/` 目录收集到同一位置，然后合并：

```bash
npx rstest merge-reports
```

默认情况下，blob 报告从项目根目录的 `.rstest-reports/` 读取。你可以指定自定义路径：

```bash
npx rstest merge-reports ./custom-reports-dir
```

合并命令将：

- 合并所有 blob 中的测试结果
- 使用配置的报告器（如 `default`、`junit`）输出合并后的数据
- 合并所有生成 blob 的运行实际采集的覆盖率（如果启用了覆盖率）
- 统一应用一次 `coverage.include`，补齐这些运行都未测试的文件
- 基于统一结果生成覆盖率报告并检查阈值

支持延迟最终处理的 coverage provider 会让使用 blob 报告器的运行有意跳过覆盖率报告生成和阈值检查。未使用 blob 报告器的运行会正常完成覆盖率最终处理，包括分片运行。旧版 provider 保持原有的单次运行最终处理行为。请通过配置或 `--coverage` 参数为 `merge-reports` 启用覆盖率，让合并 job 完成覆盖率最终处理。合并命令支持与 `rstest run` 相同的 `--coverage.*` 参数。只传给生成 blob 的运行的覆盖率参数不会写入 blob，因此请在配置文件中定义 `coverage.include`、`coverage.reporters` 和 `coverage.reportsDirectory` 等最终处理参数，或在执行 `merge-reports` 时再次传入。

使用 `--cleanup` 在合并完成后删除 blob 报告输入。目录为空时也会一并删除。如果 `coverage.reportsDirectory` 是 blob 目录或其子目录，则会保留生成的覆盖率报告及其所在目录：

```bash
npx rstest merge-reports --cleanup
```

## rstest init

`rstest init` 用于为支持的项目类型生成初始配置。

```bash
npx rstest init
```

当前可用的初始化目标是 `browser`：

```bash
npx rstest init browser
```

使用 `--yes` 可以跳过交互式提问，直接应用默认配置：

```bash
npx rstest init browser --yes
```

## CLI 选项

Rstest CLI 参数是按命令注册的，并不是所有命令共享同一套参数。

### 测试命令

`rstest`、`rstest run` 和 `rstest watch` 共享同一组测试运行参数，其中 `--related`、`--findRelatedTests`、`--changed` 和 `--shard` 在 watch 模式下会被拒绝：

| 参数                                  | 说明                                                                                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `--bail [number]`                   | 指定个数的测试失败后停止运行，详见 [bail](/zh/config/test/bail.md)                                                                                     |
| `--browser, --browser.enabled`      | 在浏览器模式下运行测试，详见 [browser](/zh/config/test/browser.md)                                                                                  |
| `--browser.headless`                | 在无头模式下运行浏览器（CI 环境默认：`true`），详见 [browser](/zh/config/test/browser.md)                                                                  |
| `--browser.name <name>`             | 使用的浏览器：`chromium`、`firefox`、`webkit`（默认：`chromium`），详见 [browser](/zh/config/test/browser.md)                                          |
| `--browser.port <port>`             | 浏览器模式开发服务器的端口，详见 [browser](/zh/config/test/browser.md)                                                                                |
| `--browser.strictPort`              | 如果指定端口已被占用则退出，详见 [browser](/zh/config/test/browser.md)                                                                                |
| `--changed [commit]`                | 运行当前 Git 仓库中变更文件相关的测试，也可以指定从某个 commit 以来的变更                                                                                           |
| `--clearMocks`                      | 每个测试前自动清除 mock 调用、实例、上下文和结果，详见 [clearMocks](/zh/config/test/clear-mocks.md)                                                           |
| `-c, --config <config>`             | 指定配置文件路径（相对或绝对路径），详见 [指定配置文件](/zh/guide/basic/configure-rstest.md#指定配置文件)                                                             |
| `--config-loader <loader>`          | 指定配置加载器 （`auto` \| `jiti` \| `native`），详见 [Rsbuild - 指定加载方式](https://rsbuild.rs/guide/configuration/rsbuild#specify-config-loader)    |
| `--coverage`                        | 启用代码覆盖率收集，详见 [coverage](/zh/config/test/coverage.md)                                                                                  |
| `--coverage.allowExternal`          | 收集项目根目录之外文件的覆盖率，详见 [coverage.allowExternal](/zh/config/test/coverage.md#allowexternal)                                                |
| `--coverage.changed [commit]`       | 只收集当前 Git 仓库中变更文件的覆盖率，也可以指定从某个 commit 以来的变更                                                                                           |
| `--coverage.clean`                  | 测试前清理覆盖率目录，详见 [coverage.clean](/zh/config/test/coverage.md#clean)                                                                     |
| `--coverage.enabled`                | 启用代码覆盖率收集，详见 [coverage.enabled](/zh/config/test/coverage.md#enabled)                                                                  |
| `--coverage.exclude <pattern>`      | 指定需要排除覆盖率收集的文件，详见 [coverage.exclude](/zh/config/test/coverage.md#exclude)                                                             |
| `--coverage.include <pattern>`      | 指定需要收集覆盖率的文件，详见 [coverage.include](/zh/config/test/coverage.md#include)                                                               |
| `--coverage.provider <provider>`    | 选择覆盖率 provider（`istanbul` \| `v8`），详见 [coverage.provider](/zh/config/test/coverage.md#provider)                                       |
| `--coverage.reporters <reporter>`   | 指定一个或多个覆盖率报告器，详见 [coverage.reporters](/zh/config/test/coverage.md#reporters)                                                          |
| `--coverage.reportOnFailure`        | 测试失败时仍生成覆盖率报告，详见 [coverage.reportOnFailure](/zh/config/test/coverage.md#reportonfailure)                                              |
| `--coverage.reportsDirectory <dir>` | 指定覆盖率报告目录，详见 [coverage.reportsDirectory](/zh/config/test/coverage.md#reportsdirectory)                                                |
| `--dev.writeToDisk`                 | 将测试临时文件写入磁盘，详见 [dev.writeToDisk](/zh/config/build/dev.md#devwritetodisk)                                                              |
| `--detectAsyncLeaks`                | 检测测试结束后仍然存活的异步资源，详见 [detectAsyncLeaks](/zh/config/test/detect-async-leaks.md)                                                         |
| `--disableConsoleIntercept`         | 禁用 console 拦截，详见 [disableConsoleIntercept](/zh/config/test/disable-console-intercept.md)                                              |
| `--exclude <exclude>`               | 排除指定文件，详见 [exclude](/zh/config/test/exclude.md)                                                                                       |
| `--findRelatedTests`                | `--related` 的 Jest 兼容别名                                                                                                               |
| `--globals`                         | 提供全局 API，详见 [globals](/zh/config/test/globals.md)                                                                                     |
| `-h, --help`                        | 显示帮助信息                                                                                                                                |
| `--hideSkippedTestFiles`            | 不展示跳过测试文件的日志，详见 [hideSkippedTestFiles](/zh/config/test/hide-skipped-test-files.md)                                                    |
| `--hideSkippedTests`                | 不展示跳过测试的日志，详见 [hideSkippedTests](/zh/config/test/hide-skipped-tests.md)                                                               |
| `--hookTimeout <value>`             | 设置单个测试 hook 的超时时间（毫秒），详见 [hookTimeout](/zh/config/test/hook-timeout.md)                                                               |
| `--include <include>`               | 指定测试文件匹配模式，详见 [include](/zh/config/test/include.md)                                                                                   |
| `--includeTaskLocation`             | 收集测试和 suite 的位置信息，详见 [includeTaskLocation](/zh/config/test/include-task-location.md)                                                  |
| `--isolate`                         | 在隔离环境中运行测试，详见 [isolate](/zh/config/test/isolate.md)                                                                                   |
| `--logHeapUsage`                    | 打印每个测试的堆内存使用情况，详见 [logHeapUsage](/zh/config/test/log-heap-usage.md)                                                                   |
| `--maxConcurrency <value>`          | 最大并发测试数，详见 [maxConcurrency](/zh/config/test/max-concurrency.md)                                                                       |
| `-f, --onlyFailures`                | 仅重新运行上一次运行中失败的测试文件，详见 [onlyFailures](/zh/config/test/only-failures.md)                                                                |
| `--output.cleanDistPath`            | 测试开始前清理测试临时文件，详见 [output.cleanDistPath](/zh/config/build/output.md#outputcleandistpath)                                               |
| `--output.emitAssets`               | 输出导入的静态资源，详见 [output.emitAssets](/zh/config/build/output.md#outputemitassets)                                                         |
| `--output.module`                   | 以 ES module 格式输出 JavaScript 文件，详见 [output.module](/zh/config/build/output.md#outputmodule)                                            |
| `--passWithNoTests`                 | 当未找到测试文件时允许测试通过，详见 [passWithNoTests](/zh/config/test/pass-with-no-tests.md)                                                           |
| `--pool <type>`                     | `--pool.type` 的 shorthand，详见 [pool](/zh/config/test/pool.md)                                                                          |
| `--pool.execArgv <arg>`             | 传给 worker 进程的额外 Node.js execArgv（可重复传入），详见 [pool](/zh/config/test/pool.md)                                                            |
| `--pool.maxWorkers <value>`         | 最大 worker 数量或百分比，详见 [pool](/zh/config/test/pool.md)                                                                                   |
| `--pool.memoryLimit <limit>`        | worker 回收阈值：`forks` 在 `isolate: false` 时按 RSS 判断，VM pools 按 V8 堆用量判断，详见 [pool](/zh/config/test/pool.md#poolmemorylimit)               |
| `--pool.type <type>`                | 指定测试线程池类型，详见 [pool](/zh/config/test/pool.md)                                                                                          |
| `--printConsoleTrace`               | 调用 console 方法时打印调用栈，详见 [printConsoleTrace](/zh/config/test/print-console-trace.md)                                                    |
| `--project <name>`                  | 仅运行指定项目的测试，详见 [根据项目名称过滤](/zh/guide/basic/test-filter.md#根据项目名称过滤)                                                                     |
| `--related`                         | 将位置参数视为源码文件路径，只运行相关测试                                                                                                                 |
| `--reporters, --reporter <name>`    | 指定一个或多个测试报告器，详见 [reporters](/zh/config/test/reporters.md)                                                                             |
| `--resetMocks`                      | 每个测试前自动重置 mock 状态，详见 [resetMocks](/zh/config/test/reset-mocks.md)                                                                     |
| `--restoreMocks`                    | 每个测试前自动恢复 mock 状态和实现，详见 [restoreMocks](/zh/config/test/restore-mocks.md)                                                              |
| `--retry <retry>`                   | 测试失败时重试次数，详见 [retry](/zh/config/test/retry.md)                                                                                        |
| `-r, --root <root>`                 | 指定项目根目录，详见 [root](/zh/config/test/root.md)                                                                                            |
| `--shard <index/count>`             | 将测试拆分为多个分片运行，详见 [测试分片](#sharding-tests)                                                                                               |
| `--silent [value]`                  | 静默被拦截的测试 console 输出，或用 `passed-only` 仅保留失败任务日志，详见 [silent](/zh/config/test/silent.md)                                                 |
| `--slowTestThreshold <value>`       | 设置测试或套件被视为慢的阈值（毫秒），详见 [slowTestThreshold](/zh/config/test/slow-test-threshold.md)                                                     |
| `--source.tsconfigPath <path>`      | 指定 tsconfig.json 文件路径，详见 [source.tsconfigPath](/zh/config/build/source.md#sourcetsconfigpath)                                         |
| `--testEnvironment <name>`          | 指定测试环境，详见 [testEnvironment](/zh/config/test/test-environment.md)                                                                      |
| `-t, --testNamePattern <value>`     | 仅运行名称匹配正则的测试，详见 [testNamePattern](/zh/config/test/test-name-pattern.md)                                                               |
| `--testTimeout <value>`             | 设置单个测试的超时时间（毫秒），详见 [testTimeout](/zh/config/test/test-timeout.md)                                                                     |
| `--trace`                           | 导出 Perfetto 兼容的性能 trace JSON 文件，并附带一份按耗时排序的 markdown 摘要（打印到终端并写入 trace 同目录），详见 [使用 --trace](/zh/guide/debug/profiling.md#using-trace) |
| `--unstubEnvs`                      | 每个测试前恢复被 `rs.stubEnv` 修改的 `process.env`，详见 [unstubEnvs](/zh/config/test/unstub-envs.md)                                               |
| `--unstubGlobals`                   | 每个测试前恢复被 `rs.stubGlobal` 修改的全局变量，详见 [unstubGlobals](/zh/config/test/unstub-globals.md)                                                |
| `-u, --update`                      | 更新快照文件，详见 [update](/zh/config/test/update.md)                                                                                         |

`rstest` 默认命令还额外支持 `-w, --watch`，可直接切换到 watch 模式。

### rstest list

`rstest list` 支持上面测试命令的过滤和配置参数，并额外提供：

| 参数                      | 说明                |
| ----------------------- | ----------------- |
| `--filesOnly`           | 仅输出匹配到的测试文件       |
| `--json [boolean/path]` | 以 JSON 输出，或写入文件   |
| `--includeSuites`       | 在输出中包含 suite      |
| `--printLocation`       | 输出测试和 suite 的位置信息 |
| `--summary`             | 在列表后输出简要统计        |

### rstest merge-reports

`rstest merge-reports` 只注册一组更小的参数集合：

| 参数                         | 说明                                                                                                                                 |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `-c, --config <config>`    | 指定配置文件路径（相对或绝对路径），详见 [指定配置文件](/zh/guide/basic/configure-rstest.md#指定配置文件)                                                          |
| `--config-loader <loader>` | 指定配置加载器 （`auto` \| `jiti` \| `native`），详见 [Rsbuild - 指定加载方式](https://rsbuild.rs/guide/configuration/rsbuild#specify-config-loader) |
| `-r, --root <root>`        | 指定项目根目录，详见 [root](/zh/config/test/root.md)                                                                                         |
| `--coverage`               | 合并完成后生成覆盖率报告，详见 [coverage](/zh/config/test/coverage.md)                                                                            |
| `--reporters <name>`       | 指定在合并结果上运行的一个或多个报告器，详见 [reporters](/zh/config/test/reporters.md)                                                                   |
| `--cleanup`                | 合并完成后删除 blob 报告输入                                                                                                                  |
| `-h, --help`               | 显示帮助信息                                                                                                                             |

### rstest init

`rstest init` 只接受初始化相关参数：

| 参数           | 说明            |
| ------------ | ------------- |
| `--yes`      | 使用默认选项并跳过交互界面 |
| `-h, --help` | 显示帮助信息        |

### 布尔选项取反

对于布尔类型的选项，你可以使用 `--no-<option>` 前缀来将其设置为 `false`。例如：

```bash
# 以下两种写法等价：
npx rstest --isolate false
npx rstest --no-isolate

# 更多示例：
npx rstest --no-coverage      # 禁用覆盖率
npx rstest --no-globals        # 禁用全局 API
npx rstest --no-clearMocks     # 禁用自动清除 mock
```

## CLI 快捷键

在 watch 模式下运行 Rstest 时，你可以使用键盘快捷键来执行各种便捷操作。

所有快捷键：

```bash
  Shortcuts:
  f  rerun failed tests
  a  rerun all tests
  u  update snapshot
  t  filter by a test name regex pattern
  p  filter by a filename regex pattern
  q  quit process
  c  clear screen
  h  show shortcuts help
```

:::note
CLI 快捷键仅在 watch 模式下运行 Rstest（`rstest watch` 或 `rstest --watch`）且终端支持 TTY（交互模式）时可用。
:::