> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # CLI Rstest comes with a lightweight CLI that includes commands such as [rstest watch](#rstest-watch) and [rstest run](#rstest-run). ## rstest -h `rstest -h` can help you view all available CLI commands and options: ```bash npx rstest -h ``` The output is shown below: ```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 ``` Use `npx rstest -h` to see command-specific options. For example, `npx rstest init -h` only shows initialization options, while `npx rstest merge-reports -h` only shows merge-related options. ## rstest \[...filters] Running `rstest` directly will enable the Rstest test in the current directory. ```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) ``` Wrap a filter in matching single or double quotes to match an exact absolute or root-relative path; the shell removes one layer of quotes, so use two layers: ```bash rstest run '"src/foo.test.ts"' ``` ### Watch mode If you want to automatically rerun the test when the file changes, you can use the `--watch` flag or `rstest watch` command: ```bash $ npx rstest --watch ``` ## rstest run `rstest run` will perform a single run, and the command is suitable for CI environments or scenarios where tests are not required to be performed while modifying. ### Run related tests [Added in v0.10.0](https://github.com/web-infra-dev/rstest/releases/tag/v0.10.0) Use `--related` when you want Rstest to treat positional arguments as source files and only run the tests that depend on those files. ```bash npx rstest run --related src/button.ts ``` Rstest resolves related tests from the build module graph, so the same filter works for Node mode and Browser Mode projects. You can also use the Jest-compatible alias: ```bash npx rstest run --findRelatedTests src/button.ts ``` If you only want to inspect the affected test files, combine it with `rstest list`: ```bash npx rstest list --related src/button.ts --filesOnly ``` `--related` and `--findRelatedTests` are not supported in watch mode, which already reruns the tests affected by your file changes. ### Run changed tests [Added in v0.10.0](https://github.com/web-infra-dev/rstest/releases/tag/v0.10.0) Use `--changed` to collect changed files from the current Git repository and run the tests related to those files. By default, it includes unstaged, staged, and untracked files, which is useful for local development before committing: ```bash npx rstest run --changed ``` You can also pass a commit or branch. Rstest will include files changed between that ref and `HEAD`, plus local staged, unstaged, and untracked files: ```bash npx rstest run --changed=HEAD~1 npx rstest run --changed=origin/main ``` When a changed file matches [`forceRerunTriggers`](/config/test/force-rerun-triggers.md), Rstest runs the whole test suite instead of only related tests. When coverage is enabled and [`coverage.changed`](/config/test/coverage.md#changed) is not configured, `--changed` also limits coverage reports to changed source files. If a changed file matches [`forceRerunTriggers`](/config/test/force-rerun-triggers.md), Rstest runs the whole test suite and reports full coverage unless `coverage.changed` is explicitly enabled. Use `rstest list` to preview which tests would run without executing them: ```bash npx rstest list --changed --filesOnly ``` `--changed` cannot be combined with positional filters or `--related` / `--findRelatedTests`, because it already provides the source-file filter from Git state. It is not supported in watch mode either. ### Run a shard \{#sharding-tests} Use `--shard /` to split test files into several shards for parallel execution. `count` is the total number of shards and `index` (1-based) is the shard to run. ```bash # Split tests into 3 shards, run the 1st shard npx rstest run --shard 1/3 ``` This is especially useful in CI/CD, where you split the suite across jobs to reduce overall test time, then merge the per-shard reports with [`rstest merge-reports`](#rstest-merge-reports). Test files are sorted by their path so sharding stays consistent across runs, and sharding happens during the test-file scanning phase, before the build, to optimize performance. Make sure the `count` and `index` values are valid (`1 <= index <= count`). ## rstest watch `rstest watch` will start listening mode and execute tests, and when the test or dependent file modifications, the associated test file will be re-execute. ## rstest list `rstest list` will print a test list of all matching conditions. By default, it prints the test names of all matching tests. ```bash $ npx rstest list # the output is shown below: 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 ``` The `rstest list` command inherits all `rstest` filtering options, you can filter files directly or use `-t` to filter the specified test name. ```bash $ npx rstest list -t='test a' # the output is shown below: a.test.ts > test a > test a-1 a.test.ts > test a-2 ``` You can use `--filesOnly` to make it print the test files only: ```bash $ npx rstest list --filesOnly # the output is shown below: a.test.ts b.test.ts ``` You can use `--json` to make it print tests in JSON format in terminal or save the results to a separate file: ```bash $ npx rstest list --json $ npx rstest list --json=./output.json ``` You can use `--includeSuites` to print test suites along side test cases: ```bash $ npx rstest list # the output is shown below: 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 ``` You can use `--printLocation` to print location of tests: ```bash $ npx rstest list # the output is shown below: 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 ``` You can use `--summary` to append a compact summary after the list output: ```bash $ npx rstest list --summary # the output is shown below: 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 ``` When used with `--json`, `--summary` changes the JSON output shape from an array to an object with `items` and `summary` fields. ## rstest merge-reports [Added in v0.9.3](https://github.com/web-infra-dev/rstest/releases/tag/v0.9.3) `rstest merge-reports` merges blob reports generated by multiple test shards into a single unified report. This is useful when running tests in parallel across multiple CI machines using [`--shard`](#sharding-tests). ### Workflow 1. Run each shard with the `blob` reporter to generate blob report files: ```bash # On CI machine 1 npx rstest run --shard 1/3 --reporters=blob # On CI machine 2 npx rstest run --shard 2/3 --reporters=blob # On CI machine 3 npx rstest run --shard 3/3 --reporters=blob ``` 2. Collect all `.rstest-reports/` directories into a single location, then merge: ```bash npx rstest merge-reports ``` By default, blob reports are read from `.rstest-reports/` in the project root. You can specify a custom path: ```bash npx rstest merge-reports ./custom-reports-dir ``` The merge command will: - Combine test results from all blobs - Run configured reporters (e.g., `default`, `junit`) with the merged data - Merge the coverage collected by all blob-producing runs (if coverage is enabled) - Apply `coverage.include` once to add files that none of those runs tested - Generate coverage reports and check thresholds against the unified result With coverage providers that support deferred finalization, runs using the blob reporter deliberately skip coverage report generation and threshold checks. Runs without the blob reporter finalize coverage normally, including sharded runs. Older providers retain their existing per-run finalization behavior. Enable coverage for `merge-reports` through your configuration or the `--coverage` flag so the merge job can finalize coverage. The merge command accepts the same `--coverage.*` options as `rstest run`. Coverage options passed only to a blob-producing run are not stored in its blob, so define finalization options such as `coverage.include`, `coverage.reporters`, and `coverage.reportsDirectory` in the configuration file or repeat them on `merge-reports`. Use `--cleanup` to remove the blob report inputs after merging. The directory is also removed when it becomes empty. If `coverage.reportsDirectory` is the blob directory or one of its subdirectories, generated coverage reports and their containing directory are retained: ```bash npx rstest merge-reports --cleanup ``` ## rstest init `rstest init` creates starter configuration for supported project types. ```bash npx rstest init ``` Currently, `browser` is the available initializer: ```bash npx rstest init browser ``` Use `--yes` to skip the interactive prompt and apply the default setup: ```bash npx rstest init browser --yes ``` ## CLI options Rstest CLI options are registered per command instead of being shared by every command. ### Test commands `rstest`, `rstest run`, and `rstest watch` share the same test runtime options, except `--related`, `--findRelatedTests`, `--changed`, and `--shard`, which are rejected in watch mode: | Flag | Description | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--bail [number]` | Abort the test run after the specified number of test failures, see [bail](/config/test/bail.md) | | `--browser, --browser.enabled` | Run tests in Browser Mode, see [browser](/config/test/browser.md) | | `--browser.headless` | Run browser in headless mode (default: `true` in CI), see [browser](/config/test/browser.md) | | `--browser.name ` | Browser to use: `chromium`, `firefox`, `webkit` (default: `chromium`), see [browser](/config/test/browser.md) | | `--browser.port ` | Port for the Browser Mode dev server, see [browser](/config/test/browser.md) | | `--browser.strictPort` | Exit if the specified port is already in use, see [browser](/config/test/browser.md) | | `--changed [commit]` | Run tests related to changed files in the current Git repository, optionally since a commit | | `--clearMocks` | Automatically clear mock calls, instances, contexts and results before every test, see [clearMocks](/config/test/clear-mocks.md) | | `-c, --config ` | Specify the configuration file, can be a relative or absolute path, see [Specify config file](/guide/basic/configure-rstest.md#specify-config-file) | | `--config-loader ` | Specify the config loader (`auto` \| `jiti` \| `native`), see [Rsbuild - Specify config loader](https://rsbuild.rs/guide/configuration/rsbuild#specify-config-loader) | | `--coverage` | Enable code coverage collection, see [coverage](/config/test/coverage.md) | | `--coverage.allowExternal` | Collect coverage for files outside the project root, see [coverage.allowExternal](/config/test/coverage.md#allowexternal) | | `--coverage.changed [commit]` | Collect coverage only for changed files in the current Git repository, optionally since a commit | | `--coverage.clean` | Clean the coverage directory before running tests, see [coverage.clean](/config/test/coverage.md#clean) | | `--coverage.enabled` | Enable code coverage collection, see [coverage.enabled](/config/test/coverage.md#enabled) | | `--coverage.exclude ` | Exclude files from coverage collection, see [coverage.exclude](/config/test/coverage.md#exclude) | | `--coverage.include ` | Include files for coverage collection, see [coverage.include](/config/test/coverage.md#include) | | `--coverage.provider ` | Choose the coverage provider (`istanbul` \| `v8`), see [coverage.provider](/config/test/coverage.md#provider) | | `--coverage.reporters ` | Specify coverage reporter(s), see [coverage.reporters](/config/test/coverage.md#reporters) | | `--coverage.reportOnFailure` | Generate coverage reports even when tests fail, see [coverage.reportOnFailure](/config/test/coverage.md#reportonfailure) | | `--coverage.reportsDirectory ` | Directory to store coverage reports, see [coverage.reportsDirectory](/config/test/coverage.md#reportsdirectory) | | `--dev.writeToDisk` | Write test temporary files to disk, see [dev.writeToDisk](/config/build/dev.md#devwritetodisk) | | `--detectAsyncLeaks` | Detect async resources that leak after tests finish, see [detectAsyncLeaks](/config/test/detect-async-leaks.md) | | `--disableConsoleIntercept` | Disable console intercept, see [disableConsoleIntercept](/config/test/disable-console-intercept.md) | | `--exclude ` | Exclude files from test, see [exclude](/config/test/exclude.md) | | `--findRelatedTests` | Alias for `--related` for Jest compatibility | | `--globals` | Provide global APIs, see [globals](/config/test/globals.md) | | `-h, --help` | Display help for command | | `--hideSkippedTestFiles` | Do not display skipped test file logs, see [hideSkippedTestFiles](/config/test/hide-skipped-test-files.md) | | `--hideSkippedTests` | Do not display skipped test logs, see [hideSkippedTests](/config/test/hide-skipped-tests.md) | | `--hookTimeout ` | Timeout of hook in milliseconds, see [hookTimeout](/config/test/hook-timeout.md) | | `--include ` | Specify test file matching pattern, see [include](/config/test/include.md) | | `--includeTaskLocation` | Collect test and suite locations, see [includeTaskLocation](/config/test/include-task-location.md) | | `--isolate` | Run tests in an isolated environment, see [isolate](/config/test/isolate.md) | | `--logHeapUsage` | Print heap usage for each test, see [logHeapUsage](/config/test/log-heap-usage.md) | | `--maxConcurrency ` | Maximum number of concurrent tests, see [maxConcurrency](/config/test/max-concurrency.md) | | `-f, --onlyFailures` | Run only the test files that failed in the previous run, see [onlyFailures](/config/test/only-failures.md) | | `--output.cleanDistPath` | Clean test temporary files before the test starts, see [output.cleanDistPath](/config/build/output.md#outputcleandistpath) | | `--output.emitAssets` | Emit imported static assets, see [output.emitAssets](/config/build/output.md#outputemitassets) | | `--output.module` | Output JavaScript files in ES module format, see [output.module](/config/build/output.md#outputmodule) | | `--passWithNoTests` | Allows the test suite to pass when no files are found, see [passWithNoTests](/config/test/pass-with-no-tests.md) | | `--pool ` | Shorthand for `--pool.type`, see [pool](/config/test/pool.md) | | `--pool.execArgv ` | Additional Node.js execArgv for worker processes (repeatable), see [pool](/config/test/pool.md) | | `--pool.maxWorkers ` | Maximum number or percentage of workers, see [pool](/config/test/pool.md) | | `--pool.memoryLimit ` | Memory recycling threshold for `forks` with `isolate: false` (RSS) and VM pools (V8 heap), see [pool](/config/test/pool.md#poolmemorylimit) | | `--pool.type ` | Specify the test pool type, see [pool](/config/test/pool.md) | | `--printConsoleTrace` | Print console traces when calling any console method, see [printConsoleTrace](/config/test/print-console-trace.md) | | `--project ` | Only run tests for the specified project, see [Filter by project name](/guide/basic/test-filter.md#filter-by-project-name) | | `--related` | Treat positional arguments as source file paths and only run related tests | | `--reporters, --reporter ` | Specify the test reporter(s), see [reporters](/config/test/reporters.md) | | `--resetMocks` | Automatically reset mock state before every test, see [resetMocks](/config/test/reset-mocks.md) | | `--restoreMocks` | Automatically restore mock state and implementation before every test, see [restoreMocks](/config/test/restore-mocks.md) | | `--retry ` | Number of times to retry a test if it fails, see [retry](/config/test/retry.md) | | `-r, --root ` | Specify the project root directory, see [root](/config/test/root.md) | | `--shard ` | Split tests into several shards, see [sharding](#sharding-tests) | | `--silent [value]` | Silence intercepted test console output, or keep logs only for failed tasks with `passed-only`, see [silent](/config/test/silent.md) | | `--slowTestThreshold ` | The number of milliseconds after which a test or suite is considered slow, see [slowTestThreshold](/config/test/slow-test-threshold.md) | | `--source.tsconfigPath ` | Path to the tsconfig.json file, see [source.tsconfigPath](/config/build/source.md#sourcetsconfigpath) | | `--testEnvironment ` | The environment that will be used for testing, see [testEnvironment](/config/test/test-environment.md) | | `-t, --testNamePattern ` | Run only tests with a name that matches the regex, see [testNamePattern](/config/test/test-name-pattern.md) | | `--testTimeout ` | Timeout of a test in milliseconds, see [testTimeout](/config/test/test-timeout.md) | | `--trace` | Dump a Perfetto-compatible performance trace JSON file, plus a ranked markdown timing summary printed to the terminal and written next to it, see [Using --trace](/guide/debug/profiling.md#using-trace) | | `--unstubEnvs` | Restores all `process.env` values that were changed with `rs.stubEnv` before every test, see [unstubEnvs](/config/test/unstub-envs.md) | | `--unstubGlobals` | Restores all global variables that were changed with `rs.stubGlobal` before every test, see [unstubGlobals](/config/test/unstub-globals.md) | | `-u, --update` | Update snapshot files, see [update](/config/test/update.md) | `rstest` also supports `-w, --watch`, which switches the default command into watch mode. ### rstest list `rstest list` supports the same filtering and config options as the test commands above, and adds: | Flag | Description | | ----------------------- | ------------------------------------------- | | `--filesOnly` | Only print matching test files | | `--json [boolean/path]` | Print tests as JSON or write JSON to a file | | `--includeSuites` | Include suites in the output | | `--printLocation` | Print test and suite locations | | `--summary` | Print a compact summary after the list | ### rstest merge-reports `rstest merge-reports` has its own smaller option set: | Flag | Description | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-c, --config ` | Specify the configuration file, can be a relative or absolute path, see [Specify config file](/guide/basic/configure-rstest.md#specify-config-file) | | `--config-loader ` | Specify the config loader (`auto` \| `jiti` \| `native`), see [Rsbuild - Specify config loader](https://rsbuild.rs/guide/configuration/rsbuild#specify-config-loader) | | `-r, --root ` | Specify the project root directory, see [root](/config/test/root.md) | | `--coverage` | Enable coverage generation after merging, see [coverage](/config/test/coverage.md) | | `--reporters ` | Specify which reporter(s) run on merged results, see [reporters](/config/test/reporters.md) | | `--cleanup` | Remove blob report inputs after merging | | `-h, --help` | Display help for command | ### rstest init `rstest init` only accepts initialization-specific options: | Flag | Description | | ------------ | ------------------------------------------- | | `--yes` | Use default options and skip interactive UI | | `-h, --help` | Display help for command | ### Boolean option negation For boolean options, you can use the `--no-