You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
As your test suite grows, running every test on every change becomes slow and distracting. If you're fixing a bug in a single module, you don't need to wait for hundreds of unrelated tests to finish. Test filtering lets you narrow down which tests run so you can stay focused on the code you're actively working on.
Vitest offers several ways to filter tests: from the command line, inside your test files, and through tags. Each approach is useful in different situations.
Filters like `-t`, `--tags-filter`, `.only`, and`.skip`are applied *per test file* — Vitest still has to run each test file to discover which tests match. In a large project, this overhead adds up even if only a few tests actually execute.
Alternatively, you can use the [`--experimental.preParse`](/config/experimental#experimental-preparse)flag, which parses test files to discover test names without fully executing them:
The simplest way to run a subset of tests is to pass a filename pattern as a CLI argument. Vitest will only run test files whose path contains the given string:
This matches any test file with `basic`in its path:
36
+
匹配路径中包含 `basic`的任意测试文件：
36
37
37
38
```
38
39
basic.test.ts
39
40
basic-foo.test.ts
40
41
basic/foo.test.ts
41
42
```
42
43
43
-
This is useful when you know which file you need to work on and want to skip everything else.
44
+
适用于明确知道需要处理哪些文件，并希望跳过其他所有内容。
44
45
45
-
## Filtering by Test Name
46
+
## 按测试名称过滤 {#filtering-by-test-name}
46
47
47
-
Sometimes the test you care about is buried in a file with many other tests. The `-t` (or `--testNamePattern`) option filters by the test's name rather than the filename. It accepts a regex pattern and matches against the full test name, which includes any `describe`block names:
vitest basic/foo.test.ts:10-25 # ❌ ranges are not supported
84
+
vitest basic/foo.test.ts:10-25 # ❌ 不支持范围
84
85
```
85
86
86
-
## Filtering by Tags
87
+
## 按标签过滤 {#filtering-by-tags}
87
88
88
-
For larger projects, you may want to categorize tests and run them by category. [Tags](/guide/test-tags) let you label tests and then filter by those labels from the CLI:
This is particularly helpful in CI pipelines where you might want to run frontend and backend tests in separate jobs, or skip slow integration tests during quick checks.
105
+
适合在 CI 流水线中使用，例如你可能希望在不同的任务中分别运行前端测试和后端测试，或者在快速检查时跳过耗时较长的集成测试。
When you're debugging a failing test, you want to run just that test without modifying CLI arguments every time. Adding `.only`to a test or suite tells Vitest to skip everything else in the file:
//This runs because the suite is marked with .only
116
+
//仅有这个会运行，因为测试套件被标记为 .only
116
117
expect(Math.sqrt(4)).toBe(2)
117
118
})
118
119
})
119
120
120
121
describe('another suite', () => {
121
122
it('skipped test', () => {
122
-
//This does not run
123
+
//这个不会运行
123
124
expect(Math.sqrt(4)).toBe(2)
124
125
})
125
126
126
127
it.only('focused test', () => {
127
-
//This also runs because it is marked with .only
128
+
//这个也会运行，因为它被标记为 .only
128
129
expect(Math.sqrt(4)).toBe(2)
129
130
})
130
131
})
131
132
```
132
133
133
-
You can use`.only` on both `describe` blocks and individual tests. When any test or suite in a file is marked with `.only`, all unmarked tests in that file are skipped.
Remember to remove `.only` before committing. By default, Vitest will fail the entire test run if it encounters `.only` in CI (when`process.env.CI`is set), preventing you from accidentally skipping tests in your pipeline. This behavior is controlled by the [`allowOnly`](/config/allowonly)option.
137
+
请记得在提交前移除 `.only`。默认情况下，在 CI 环境中（即设置了`process.env.CI`时）， Vitest 遇到 `.only` 会使整个测试运行失败，以防你在流水线中意外跳过测试。此行为由 [`allowOnly`](/config/allowonly)选项控制。
137
138
138
-
To catch `.only` even earlier, the [`no-focused-tests`](https://github.com/vitest-dev/eslint-plugin-vitest/blob/main/docs/rules/no-focused-tests.md) ESLint rule (also available in [oxlint](https://oxc.rs/docs/guide/usage/linter/rules/jest/no-focused-tests.html)) can flag it in your editor before you commit.
The opposite of `.only` is`.skip`. Use it to temporarily disable a test or suite without deleting it. Skipped tests still show up in the report so you don't forget about them:
This is useful when a test is flaky or depends on an external service that's temporarily down. It lets you keep the test in place as a reminder while unblocking the rest of the suite.
When planning new features, you might know what tests you'll need before you write the actual implementation. `.todo`marks a test as planned but not yet written. It shows up in the report as a reminder:
0 commit comments