#CLI

Rstest comes with a lightweight CLI that includes commands such as rstest watch and rstest run.

#rstest -h

rstest -h can help you view all available CLI commands and options:

npx rstest -h

The output is shown below:

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 <command> -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.

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

If you want to automatically rerun the test when the file changes, you can use the --watch flag or rstest watch command:

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

#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.

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

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

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

$ npx rstest list --json

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

You can use --includeSuites to print test suites along side test cases:

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

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

$ 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

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.

#Workflow

1. Run each shard with the blob reporter to generate blob report files:

# On CI machine 1
npx rstest run --shard 1/3 --reporter=blob

# On CI machine 2
npx rstest run --shard 2/3 --reporter=blob

# On CI machine 3
npx rstest run --shard 3/3 --reporter=blob

2. Collect all .rstest-reports/ directories into a single location, then merge:

npx rstest merge-reports

By default, blob reports are read from .rstest-reports/ in the project root. You can specify a custom path:

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

The merge command will:

• Combine test results from all shards
• Run configured reporters (e.g., default, junit) with the merged data
• Merge and generate coverage reports (if coverage is enabled)

Use --cleanup to remove the blob reports directory after merging:

npx rstest merge-reports --cleanup

#rstest init

rstest init creates starter configuration for supported project types.

npx rstest init

Currently, browser is the available initializer:

npx rstest init browser

Use --yes to skip the interactive prompt and apply the default setup:

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:

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:

#rstest merge-reports

rstest merge-reports has its own smaller option set:

#rstest init

rstest init only accepts initialization-specific options:

#Boolean option negation

For boolean options, you can use the --no-<option> prefix to set them to false. For example:

# These are equivalent:
npx rstest --isolate false
npx rstest --no-isolate

# More examples:
npx rstest --no-coverage      # Disable coverage
npx rstest --no-globals        # Disable global APIs
npx rstest --no-clearMocks     # Disable auto-clearing mocks

#CLI shortcuts

When running Rstest in watch mode, you can use keyboard shortcuts to perform various actions.

All shortcuts:

  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