1---
2name: test-filtering
3description: Filter tests by name, file patterns, and tags
4---
5 
6# Test Filtering
7 
8## CLI Filtering
9 
10### By File Path
11 
12```bash
13# Run files containing "user"
14vitest user
15 
16# Multiple patterns
17vitest user auth
18 
19# Specific file
20vitest src/user.test.ts
21 
22# By line number
23vitest src/user.test.ts:25
24```
25 
26### By Test Name
27 
28```bash
29# Tests matching pattern
30vitest -t "login"
31vitest --testNamePattern "should.*work"
32 
33# Regex patterns
34vitest -t "/user|auth/"
35```
36 
37## Changed Files
38 
39```bash
40# Uncommitted changes
41vitest --changed
42 
43# Since specific commit
44vitest --changed HEAD~1
45vitest --changed abc123
46 
47# Since branch
48vitest --changed origin/main
49```
50 
51## Related Files
52 
53Run tests that import specific files:
54 
55```bash
56vitest related src/utils.ts src/api.ts --run
57```
58 
59Useful with lint-staged:
60 
61```js
62// .lintstagedrc.js
63export default {
64  '*.{ts,tsx}': 'vitest related --run',
65}
66```
67 
68## Focus Tests (.only)
69 
70```ts
71test.only('only this runs', () => {})
72 
73describe.only('only this suite', () => {
74  test('runs', () => {})
75})
76```
77 
78In CI, `.only` throws error unless configured:
79 
80```ts
81defineConfig({
82  test: {
83    allowOnly: true, // Allow .only in CI
84  },
85})
86```
87 
88## Skip Tests
89 
90```ts
91test.skip('skipped', () => {})
92 
93// Conditional
94test.skipIf(process.env.CI)('not in CI', () => {})
95test.runIf(!process.env.CI)('local only', () => {})
96 
97// Dynamic skip
98test('dynamic', ({ skip }) => {
99  skip(someCondition, 'reason')
100})
101```
102 
103## Tags
104 
105Tags must be declared in config, then applied to tests/suites and filtered with a tag expression:
106 
107```ts
108// vitest.config.ts
109defineConfig({
110  test: {
111    tags: [{ name: 'db' }, { name: 'slow' }, { name: 'flaky' }],
112  },
113})
114 
115// test file
116test('database test', { tags: ['db'] }, () => {})
117```
118 
119```bash
120vitest --tagsFilter "db && !flaky"
121vitest --tagsFilter "unit || e2e"
122vitest --list-tags            # show defined tags
123```
124 
125Full syntax, priority, and per-tag options: see [features-test-tags](features-test-tags.md).
126 
127## Include/Exclude Patterns
128 
129```ts
130defineConfig({
131  test: {
132    // Test file patterns
133    include: ['**/*.{test,spec}.{ts,tsx}'],
134    
135    // Exclude patterns
136    exclude: [
137      '**/node_modules/**',
138      '**/e2e/**',
139      '**/*.skip.test.ts',
140    ],
141    
142    // Include source for in-source testing
143    includeSource: ['src/**/*.ts'],
144 
145    // Scope discovery to a directory (faster than broad excludes)
146    dir: './src',
147  },
148})
149```
150 
151> v4 simplified default `exclude` to only `node_modules`/`.git`. Prefer `test.dir` to limit where tests are found; spread `configDefaults.exclude` to restore the old excludes.
152 
153## Watch Mode Filtering
154 
155In watch mode, press:
156- `p` - Filter by filename pattern
157- `t` - Filter by test name pattern
158- `a` - Run all tests
159- `f` - Run only failed tests
160 
161## Projects Filtering
162 
163Run specific project:
164 
165```bash
166vitest --project unit
167vitest --project integration --project e2e
168```
169 
170## Environment-based Filtering
171 
172```ts
173const isDev = process.env.NODE_ENV === 'development'
174const isCI = process.env.CI
175 
176describe.skipIf(isCI)('local only tests', () => {})
177describe.runIf(isDev)('dev tests', () => {})
178```
179 
180## Combining Filters
181 
182```bash
183# File pattern + test name + changed
184vitest user -t "login" --changed
185 
186# Related files + run mode
187vitest related src/auth.ts --run
188```
189 
190## List Tests Without Running
191 
192```bash
193vitest list                 # Show all test names
194vitest list -t "user"       # Filter by name
195vitest list --filesOnly     # Show only file paths
196vitest list --json          # JSON output
197```
198 
199## Key Points
200 
201- Use `-t` for test name pattern filtering
202- `--changed` runs only tests affected by changes
203- `--related` runs tests importing specific files
204- Tags provide semantic test grouping
205- Use `.only` for debugging, but configure CI to reject it
206- Watch mode has interactive filtering
207 
208<!-- 
209Source references:
210- https://vitest.dev/guide/filtering.html
211- https://vitest.dev/guide/cli.html
212-->
213