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 
105Filter by custom tags:
106 
107```ts
108test('database test', { tags: ['db'] }, () => {})
109test('slow test', { tags: ['slow', 'integration'] }, () => {})
110```
111 
112Run tagged tests:
113 
114```bash
115vitest --tags db
116vitest --tags "db,slow"      # OR
117vitest --tags db --tags slow # OR
118```
119 
120Configure allowed tags:
121 
122```ts
123defineConfig({
124  test: {
125    tags: ['db', 'slow', 'integration'],
126    strictTags: true, // Fail on unknown tags
127  },
128})
129```
130 
131## Include/Exclude Patterns
132 
133```ts
134defineConfig({
135  test: {
136    // Test file patterns
137    include: ['**/*.{test,spec}.{ts,tsx}'],
138    
139    // Exclude patterns
140    exclude: [
141      '**/node_modules/**',
142      '**/e2e/**',
143      '**/*.skip.test.ts',
144    ],
145    
146    // Include source for in-source testing
147    includeSource: ['src/**/*.ts'],
148  },
149})
150```
151 
152## Watch Mode Filtering
153 
154In watch mode, press:
155- `p` - Filter by filename pattern
156- `t` - Filter by test name pattern
157- `a` - Run all tests
158- `f` - Run only failed tests
159 
160## Projects Filtering
161 
162Run specific project:
163 
164```bash
165vitest --project unit
166vitest --project integration --project e2e
167```
168 
169## Environment-based Filtering
170 
171```ts
172const isDev = process.env.NODE_ENV === 'development'
173const isCI = process.env.CI
174 
175describe.skipIf(isCI)('local only tests', () => {})
176describe.runIf(isDev)('dev tests', () => {})
177```
178 
179## Combining Filters
180 
181```bash
182# File pattern + test name + changed
183vitest user -t "login" --changed
184 
185# Related files + run mode
186vitest related src/auth.ts --run
187```
188 
189## List Tests Without Running
190 
191```bash
192vitest list                 # Show all test names
193vitest list -t "user"       # Filter by name
194vitest list --filesOnly     # Show only file paths
195vitest list --json          # JSON output
196```
197 
198## Key Points
199 
200- Use `-t` for test name pattern filtering
201- `--changed` runs only tests affected by changes
202- `--related` runs tests importing specific files
203- Tags provide semantic test grouping
204- Use `.only` for debugging, but configure CI to reject it
205- Watch mode has interactive filtering
206 
207<!-- 
208Source references:
209- https://vitest.dev/guide/filtering.html
210- https://vitest.dev/guide/cli.html
211-->
212