#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

Run a specific test file:

rstest test/foo.test.ts

Use glob patterns:

rstest test/**/*.test.ts

Run test files with foo in the name, such as foo.test.ts, foo/index.test.ts, foo-bar/index.test.ts, etc.:

rstest foo

You can also specify multiple test files or glob patterns:

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

#Filter by file path

This method also applies to filtering by file path.

When filtering by file path, it can be either an absolute path or a relative path based on the current working directory (also called the project root directory or workspace 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 filter files directly with rstest **/*.test.ts, rstest will further filter files based on 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 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 test/api/*.test.ts

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

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

• Combined filtering: rstest 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', () => {
  // ...
});