#Filtering tests

Rstest provides a variety of flexible ways to filter and select which test files and test cases to run. You can precisely control the test scope via configuration files, command-line arguments, and test APIs.

#Filter by file name

Run all tests:

rstest

Match an exact test file path. The shell removes one layer of quotes, so use two layers:

rstest '"test/foo.test.ts"'

Use --include for glob patterns, with quotes to prevent shell expansion:

rstest --include "test/**/*.test.ts"

Positional filters use case-insensitive substring matching by default. Run test files with foo in the path, such as foo.test.ts, foo/index.test.ts, foo-bar/index.test.ts, etc.:

rstest foo

You can also specify multiple file filters:

rstest test/foo.test.ts test/bar.test.ts

#Filter by file path

Rstest does not interpret positional filters as glob patterns. An unquoted pattern may be expanded by your shell, but this behavior varies between shells; use --include for glob matching.

This method also applies to filtering by file path.

File paths can be absolute or relative to the Rstest root directory.

# Filtering by absolute path
rstest /Users/userName/Desktop/projects/rstest/packages/core/tests/index.test.ts

# Filtering by relative path
rstest packages/core/tests/index.test.ts

# Filtering by project directory
rstest packages/core

#include/exclude

When you pass positional filters, such as rstest foo, Rstest applies them to the files selected by the include and exclude configuration. You can modify the test file scope using the include and exclude options.

For example, to match test files named index in the test/a directory:

rstest index --include "test/a/*.test.ts"

To match test files in test/a or test/b directories:

rstest --include "test/a/*.test.ts" --include "test/b/*.test.ts"

#Filter by test name

If you only want to run some test cases, you can use the --testNamePattern (-t for short) option. It will run tests with names that match the given pattern.

#Match by keyword

This is the simplest way. It will run test cases or test suites whose full names contain the given keyword.

For example, to only run test cases whose names contain "bar":

rstest -t bar

If a suite name matches, all tests inside it will be run.

You can also provide multiple keywords separated by spaces. This will match test cases where all keywords appear in the full name. For example, to run tests where 'suite-bar' appears in the suite path and 'test-baz' is in the test name:

rstest -t 'suite-bar test-baz'

#Match by full test name

You can also provide a full test name to run a specific test case.

Rstest uses > to connect test suite and test case names for better output readability. The full test name is the concatenation of the names of the test suites from the outside in and the test case name, separated by >.

For example, consider the following test structure and its output:

// foo.test.ts
import { describe, test } from '@rstest/core';

describe('suite-foo', () => {
  describe('suite-bar', () => {
    test('test-baz', () => {
      // ...
    });

    describe('suite-bar1', () => {
      test('test-baz', () => {
        // ...
      });
    });
  });
});

Output:

✓ foo.test.ts
  ✓ suite-foo > suite-bar > test-baz
  ✓ suite-foo > suite-bar > suite-bar1 > test-baz

To run only the test-baz test case in suite-bar, you can use:

rstest foo.test.ts -t 'suite-foo > suite-bar > test-baz'

#Match by regular expression

The pattern is treated as a regular expression. You can use this for more complex filtering.

For example, if you want to precisely match suite-bar > test-baz, rather than any test containing this string, you can use the regex start ^ and end $ anchors:

rstest foo.test.ts -t '^suite-bar > test-baz$'

#Filter by project name

Rstest supports defining multiple test projects via projects. You can filter to run specific projects with the --project option.

For example, to match projects whose name is @test/a or @test/b:

rstest --project '@test/a' --project '@test/b'

You can also use wildcards to match project names:

rstest --project '@test/*'

You can exclude certain projects by negation:

rstest --project '!@test/a'

#Combined filtering

All filtering methods can be combined. For example:

rstest --include "test/**/*.test.ts" --exclude "test/legacy/**" --testNamePattern login

In this case, rstest will only run test cases whose names contain login in all .test.ts files under the test directory, while excluding the test/legacy directory.

#Common usage

• Run a specific file only: rstest '"test/foo.test.ts"'

• Run tests in a specific directory only: rstest --include "test/api/*.test.ts"

• Exclude certain tests: rstest --exclude "test/legacy/**"

• Run only tests whose names contain login: rstest -t login

• Combined filtering: rstest --include "test/**/*.test.ts" --exclude "test/legacy/**" --testNamePattern login

#Filter via test API

Use the .only modifier to run only certain test suites or cases.

For example, only the test cases in suite A and case A will be run:

describe.only('suite A', () => {
  // ...
});

describe('suite B', () => {
  // ...
});

test.only('case A', () => {
  // ...
});

test('case B', () => {
  // ...
});

Use .skip or .todo to skip certain test suites or cases.

describe.skip('suite A', () => {
  // ...
});

test.todo('case A', () => {
  // ...
});