close
Rstest
  • English

      • 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

Options:
  -w, --watch                              Run tests in watch mode
  -h, --help                               Display this message
  -v, --version                            Display version number
  -c, --config <config>
  ...

      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

      CLI options

      Rstest CLI provides several common options that can be used with all commands:

      FlagDescription
      -c, --config <config>Specify the configuration file, can be a relative or absolute path, see Specify config file
      --config-loader <loader>Specify the config loader, can be jiti or native, see Rsbuild - Specify config loader
      -r, --root <root>Specify the project root directory, see root
      --globalsProvide global APIs, see globals
      --isolateRun tests in an isolated environment, see isolate
      --reporter <reporter>Specify the test reporter, see reporters
      --exclude <exclude>Exclude files from test, see exclude
      -u, --updateUpdate snapshot files, see update
      --coverageEnable code coverage collection, see coverage
      --passWithNoTestsAllows the test suite to pass when no files are found, see passWithNoTests
      --printConsoleTracePrint console traces when calling any console method, see printConsoleTrace
      --project <name>Only run tests for the specified project, see Filter by project name
      --disableConsoleInterceptDisable console intercept, see disableConsoleIntercept
      --slowTestThreshold <value>The number of milliseconds after which a test or suite is considered slow, see slowTestThreshold
      -t, --testNamePattern <value>Run only tests with a name that matches the regex, see testNamePattern
      --testEnvironment <name>The environment that will be used for testing, see testEnvironment
      --testTimeout <value>Timeout of a test in milliseconds, see testTimeout
      --hookTimeout <value>Timeout of hook in milliseconds, see hookTimeout
      --retry <retry>Number of times to retry a test if it fails, see retry
      --bail [number]Abort the test run after the specified number of test failures, see bail
      --browser, --browser.enabledRun tests in Browser Mode, see browser
      --browser.name <name>Browser to use: chromium, firefox, webkit (default: chromium), see browser
      --browser.headlessRun browser in headless mode (default: true in CI), see browser
      --browser.port <port>Port for the Browser Mode dev server, see browser
      --browser.strictPortExit if the specified port is already in use, see browser
      --maxConcurrency <value>Maximum number of concurrent tests, see maxConcurrency
      --clearMocksAutomatically clear mock calls, instances, contexts and results before every test, see clearMocks
      --resetMocksAutomatically reset mock state before every test, see resetMocks
      --restoreMocksAutomatically restore mock state and implementation before every test, see restoreMocks
      --unstubGlobalsRestores all global variables that were changed with rstest.stubGlobal before every test, see unstubGlobals
      --unstubEnvsRestores all process.env values that were changed with rstest.stubEnv before every test, see unstubEnvs
      --include <pattern>Specify test file matching pattern, see include
      --includeSource <pattern>Specify in-source testing file matching pattern, see includeSource
      --logHeapUsagePrint heap usage for each test, see logHeapUsage
      --hideSkippedTestsDo not display skipped test logs, see hideSkippedTests
      --hideSkippedTestFilesDo not display skipped test file logs, see hideSkippedTestFiles
      --chaiConfig <config>Customize Chai configuration, see chaiConfig
      --env <key=value>Set environment variables, see env
      --pool <type>Shorthand for --pool.type, see pool
      --pool.type <type>Specify the test pool type, see pool
      --pool.maxWorkers <value>Maximum number or percentage of workers, see pool
      --pool.minWorkers <value>Minimum number or percentage of workers, see pool
      --pool.execArgv <arg>Additional Node.js execArgv for worker processes (repeatable), see pool
      --setupFiles <files>Specify setup files list, see setupFiles
      --snapshotFormat <options>Customize snapshot format, see snapshotFormat
      --resolveSnapshotPathCustomize snapshot path resolution, see resolveSnapshotPath
      --onConsoleLog <handler>Handle console logs, see onConsoleLog
      --name <name>Set test suite name, see name
      --projects <projects>Configure multi-project testing, see projects
      -h, --helpDisplay help for command
      -v, --versionDisplay version

      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
      Note

      CLI shortcuts are only available when running Rstest in watch mode (rstest watch or rstest --watch) and when the terminal supports TTY (interactive mode).