> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 过滤测试

Rstest 提供了多种灵活的方式来过滤和选择要运行的测试文件和测试用例。你可以通过配置文件、命令行参数、测试 API 等方式精准控制测试范围。

## 根据文件名过滤

运行所有测试：

```bash
rstest
```

只运行某个测试文件：

```bash
rstest test/foo.test.ts
```

用通配符匹配：

```bash
rstest test/**/*.test.ts
```

运行名称中包含 `foo` 的测试文件，如 `foo.test.ts`, `foo/index.test.ts`, `foo-bar/index.test.ts` 等：

```bash
rstest foo
```

你也可以指定多组测试文件或通配符：

```bash
rstest test/foo.test.ts test/bar.test.ts
```

### 根据文件路径过滤

此种方式也适用于根据文件路径过滤。

当你根据文件路径过滤，它可以是一个绝对路径或者基于当前工作目录（也称为项目根目录或 workspace 根目录）的相对路径。

```bash
# 根据绝对路径过滤
rstest /Users/userName/Desktop/projects/rstest/packages/core/tests/index.test.ts

# 根据相对路径过滤
rstest packages/core/tests/index.test.ts

# 根据 project 目录过滤
rstest packages/core
```

### include/exclude

当你直接通过 `rstest **/*.test.ts` 过滤文件时，Rstest 会在 [include](/zh/config/test/include.md) 和 [exclude](/zh/config/test/exclude.md) 配置的基础上进一步筛选文件。
你可以通过 `include` 和 `exclude` 选项修改测试文件的范围。

如，匹配 `test/a` 目录下的名为 `index` 的测试文件：

```bash
rstest index --include test/a/*.test.ts
```

匹配 `test/a` 和 `test/b` 目录下的测试文件：

```bash
rstest --include test/a/*.test.ts --include test/b/*.test.ts
```

## 根据测试名称过滤

如果你只想运行某些测试用例，可以使用 `--testNamePattern`（简写为 `-t`）选项。它会运行名称与给定模式匹配的测试。

### 按关键字匹配

这是最简单的方法。它将运行完整名称包含给定关键字的测试用例或测试套件。

例如，只运行名称包含 "bar" 的测试用例：

```bash
rstest -t bar
```

如果套件名称匹配，则其中的所有测试都将被运行。

你还可以提供多个由空格分隔的关键字。这将匹配完整名称中出现所有关键字的测试用例。例如，要运行套件路径中出现 `'suite-bar'` 且测试名称中包含 `'test-baz'` 的测试：

```bash
rstest -t 'suite-bar test-baz'
```

### 按完整测试名称匹配

你也可以提供完整的测试名称来运行特定的测试用例。

为了更好的输出可读性，Rstest 使用 `>` 来连接测试套件和测试用例的名称。完整的测试名称是测试套件从外到内的名称和测试用例名称的拼接，用 `>` 分隔。

例如，参考以下测试结构及其输出：

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

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

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

输出：

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

如果希望只运行 `suite-bar` 中的 `test-baz` 测试用例，你可以使用：

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

### 按正则表达式匹配

当需要更精确地匹配测试名称时，你可以将模式视为一个正则表达式。这对于复杂的过滤场景非常有用。

例如，如果你想精确匹配 `suite-bar > test-baz`，而不是任何包含此字符串的测试，可以使用正则表达式的起始符 `^` 和结束符 `$`：

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

## 根据项目名称过滤

Rstest 支持通过 [projects](/zh/config/test/projects.md) 配置来定义多个测试项目，你可以通过 `--project` 选项来过滤运行特定项目。

如，匹配[名称](/zh/config/test/name.md)为 `@test/a` 或 `@test/b` 的项目：

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

你也可以使用通配符来匹配项目名称：

```bash
rstest --project '@test/*'
```

你也可以通过取反来排除某些项目：

```bash
rstest --project '!@test/a'
```

## 组合过滤

所有过滤方式都可以组合使用。例如：

```bash
rstest test/**/*.test.ts --exclude test/legacy/** --testNamePattern login
```

此时，rstest 会只运行 `test` 目录下所有 `.test.ts` 文件中名称包含 login 的测试用例，同时排除 `test/legacy` 目录。

## 常见用法

- **只运行某个文件**：`rstest test/foo.test.ts`

- **只运行某个目录下的测试**：`rstest test/api/*.test.ts`

- **排除某些测试**：`rstest --exclude test/legacy/**`

- **只运行名称包含 login 的测试**：`rstest -t login`

- **组合过滤**：`rstest test/**/*.test.ts --exclude test/legacy/** --testNamePattern login`

## 通过测试 API 过滤

使用 `.only` 标记将仅运行某些测试套件或用例。

如，此时将仅运行 `suite A` 内的测试用例及 `case A`：

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

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

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

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

:::note
需要注意的是，`.only` 标记仅对当前测试文件生效。如果你希望仅执行某个特定文件内的特定用例，可使用 `根据文件名过滤` + `通过测试 API 过滤` 的组合方式。
:::

使用 `.skip` 或 `.todo` 标记将跳过某些测试套件或用例。

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

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