close
Rstest
  • 简体中文

      • 命令行工具

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

      rstest -h

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

      npx rstest -h

      输出如下：

      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 测试。

      $ 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)

      Watch 模式

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

      $ npx rstest --watch

      rstest run

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

      运行相关测试

      Added in v0.10.0

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

      npx rstest run --related src/button.ts

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

      npx rstest run --findRelatedTests src/button.ts

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

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

      运行变更相关测试

      Added in v0.10.0

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

      npx rstest run --changed

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

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

      当变更文件命中 forceRerunTriggers 时，Rstest 会运行完整测试套件，而不是只运行相关测试。

      开启覆盖率且未配置 coverage.changed 时，--changed 也会将覆盖率报告限制在变更的源文件范围内。如果变更文件命中 forceRerunTriggers，Rstest 会运行完整测试套件，并生成完整覆盖率报告，除非显式启用了 coverage.changed。

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

      npx rstest list --changed --filesOnly

      --changed 不能和位置参数、--related / --findRelatedTests 一起使用，因为它已经从 Git 状态提供了源码文件过滤条件。

      运行分片

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

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

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

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

      rstest watch

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

      rstest list

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

      $ 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 过滤指定的测试名称。

      $ npx rstest list -t='test a'

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

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

      $ npx rstest list --filesOnly

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

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

      $ npx rstest list --json

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

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

      $ 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 选项来打印测试的位置信息：

      $ 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 在列表输出后追加一段简要统计：

      $ 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

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

      工作流程

      1. 使用 blob 报告器运行每个分片以生成 blob 报告文件：
      # 在 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
      1. 将所有 .rstest-reports/ 目录收集到同一位置，然后合并：
      npx rstest merge-reports

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

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

      合并命令将：

      • 合并所有分片的测试结果
      • 使用配置的报告器（如 default、junit）输出合并后的数据
      • 合并并生成覆盖率报告（如果启用了覆盖率）

      使用 --cleanup 在合并完成后删除 blob 报告目录：

      npx rstest merge-reports --cleanup

      rstest init

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

      npx rstest init

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

      npx rstest init browser

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

      npx rstest init browser --yes

      CLI 选项

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

      测试命令

      rstest、rstest run 和 rstest watch 共享同一组测试运行参数：

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

      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>指定配置文件路径（相对或绝对路径），详见 指定配置文件
      --config-loader <loader>指定配置加载器 （auto | jiti | native），详见 Rsbuild - 指定加载方式
      -r, --root <root>指定项目根目录，详见 root
      --coverage合并完成后生成覆盖率报告，详见 coverage
      --reporters <name>指定在合并结果上运行的一个或多个报告器，详见 reporters
      --cleanup合并完成后删除 blob 报告目录
      -h, --help显示帮助信息

      rstest init

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

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

      布尔选项取反

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

      # 以下两种写法等价：
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 时，你可以使用键盘快捷键来执行各种便捷操作。

      所有快捷键：

        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（交互模式）时可用。