0
# Configuration
1

2
Type-safe configuration APIs for Vitest with TypeScript support.
3

4
## Configuration Functions
5

6
```typescript { .api }
7
import { defineConfig, defineProject } from 'vitest/config';
8

9
// Main config
10
function defineConfig(config: UserConfig): UserConfig;
11

12
// Workspace project config
13
function defineProject(config: UserWorkspaceConfig): UserWorkspaceConfig;
14
```
15

16
**Basic Example:**
17
```typescript
18
// vitest.config.ts
19
import { defineConfig } from 'vitest/config';
20

21
export default defineConfig({
22
  test: {
23
    globals: true,
24
    environment: 'jsdom',
25
    setupFiles: './setup.ts',
26
    coverage: {
27
      provider: 'v8',
28
      reporter: ['text', 'json', 'html']
29
    }
30
  }
31
});
32
```
33

34
## Core Configuration Options
35

36
```typescript { .api }
37
interface TestProjectConfiguration {
38
  // Test file patterns
39
  include?: string[];                    // Default: ['**/*.{test,spec}.?(c|m)[jt]s?(x)']
40
  exclude?: string[];                    // Default: ['**/node_modules/**', ...]
41

42
  // Environment
43
  environment?: 'node' | 'jsdom' | 'happy-dom' | 'edge-runtime' | string;
44
  globals?: boolean;                     // Enable global APIs (test, expect, etc.)
45

46
  // Setup & Timeouts
47
  setupFiles?: string | string[];
48
  testTimeout?: number;                  // Default: 5000ms
49
  hookTimeout?: number;                  // Default: 10000ms
50

51
  // Execution
52
  pool?: 'threads' | 'forks' | 'vmThreads' | 'vmForks' | 'browser';
53
  poolOptions?: PoolOptions;
54
  isolate?: boolean;                     // Isolate each test file
55
  maxConcurrency?: number;               // Max concurrent tests
56
  sequence?: SequenceOptions;            // Test ordering
57

58
  // Retry & Repeat
59
  retry?: number;                        // Retry failed tests N times
60
  repeats?: number;                      // Repeat each test N times
61

62
  // Reporting
63
  reporters?: Array<Reporter | string>;
64
  outputFile?: string | Record<string, string>;
65

66
  // Coverage
67
  coverage?: CoverageOptions;
68

69
  // Browser Testing
70
  browser?: BrowserConfigOptions;
71

72
  // Typecheck
73
  typecheck?: TypecheckConfig;
74

75
  // Watch Mode
76
  watch?: boolean;
77
  watchExclude?: string[];
78

79
  // Mocking
80
  mockReset?: boolean;                   // Reset mocks before each test
81
  restoreMocks?: boolean;                // Restore mocks after each test
82
  clearMocks?: boolean;                  // Clear mock history before each test
83
  unstubGlobals?: boolean;               // Unstub globals after each test
84
  unstubEnvs?: boolean;                  // Unstub env vars after each test
85

86
  // Multi-project
87
  projects?: Array<UserWorkspaceConfig>;
88
  workspace?: string;
89

90
  // Sharding
91
  shard?: { index: number; count: number };
92

93
  // Snapshot
94
  snapshotFormat?: SnapshotStateOptions;
95

96
  // CSS
97
  css?: boolean | { include?: RegExp | RegExp[]; modules?: { classNameStrategy?: string } };
98
}
99
```
100

101
## Configuration Defaults
102

103
```typescript { .api }
104
configDefaults: Partial<UserConfig>;
105
defaultInclude: string[];               // ['**/*.{test,spec}.?(c|m)[jt]s?(x)']
106
defaultExclude: string[];               // ['**/node_modules/**', '**/dist/**', ...]
107
defaultBrowserPort: number;             // 63315
108
benchmarkConfigDefaults: BenchmarkConfig;
109
coverageConfigDefaults: CoverageOptions;
110
fakeTimersDefaults: FakeTimerInstallOpts;
111
```
112

113
**Usage:**
114
```typescript
115
import { defaultInclude, defaultExclude, defineConfig } from 'vitest/config';
116

117
export default defineConfig({
118
  test: {
119
    include: [...defaultInclude, '**/*.integration.test.ts'],
120
    exclude: [...defaultExclude, '**/fixtures/**']
121
  }
122
});
123
```
124

125
## Coverage Configuration
126

127
```typescript { .api }
128
interface CoverageOptions {
129
  provider?: 'v8' | 'istanbul';
130
  enabled?: boolean;
131
  include?: string[];
132
  exclude?: string[];
133
  reporter?: Array<'text' | 'json' | 'html' | 'lcov' | 'text-summary' | string>;
134
  reportsDirectory?: string;
135
  all?: boolean;
136

137
  // Thresholds
138
  lines?: number;
139
  functions?: number;
140
  branches?: number;
141
  statements?: number;
142

143
  clean?: boolean;
144
  extension?: string | string[];
145
}
146
```
147

148
**Example:**
149
```typescript
150
export default defineConfig({
151
  test: {
152
    coverage: {
153
      provider: 'v8',
154
      reporter: ['text', 'json', 'html'],
155
      include: ['src/**/*.ts'],
156
      exclude: ['**/*.test.ts', '**/*.spec.ts'],
157
      lines: 80,
158
      functions: 80,
159
      branches: 80,
160
      statements: 80
161
    }
162
  }
163
});
164
```
165

166
## Pool Options
167

168
```typescript { .api }
169
interface PoolOptions {
170
  threads?: {
171
    maxThreads?: number;
172
    minThreads?: number;
173
    singleThread?: boolean;
174
    useAtomics?: boolean;
175
    isolate?: boolean;
176
  };
177

178
  forks?: {
179
    maxForks?: number;
180
    minForks?: number;
181
    singleFork?: boolean;
182
    isolate?: boolean;
183
  };
184

185
  vmThreads?: {
186
    maxThreads?: number;
187
    minThreads?: number;
188
    memoryLimit?: string | number;
189
    useAtomics?: boolean;
190
  };
191

192
  vmForks?: {
193
    maxForks?: number;
194
    minForks?: number;
195
    memoryLimit?: string | number;
196
  };
197
}
198
```
199

200
**Example:**
201
```typescript
202
export default defineConfig({
203
  test: {
204
    pool: 'threads',
205
    poolOptions: {
206
      threads: {
207
        maxThreads: 4,
208
        minThreads: 1
209
      }
210
    }
211
  }
212
});
213
```
214

215
## Multiple Projects
216

217
```typescript
218
// vitest.config.ts
219
export default defineConfig({
220
  test: {
221
    projects: [
222
      {
223
        test: {
224
          name: 'unit',
225
          environment: 'node',
226
          include: ['src/**/*.test.ts']
227
        }
228
      },
229
      {
230
        test: {
231
          name: 'integration',
232
          environment: 'node',
233
          include: ['tests/**/*.integration.test.ts'],
234
          testTimeout: 30000
235
        }
236
      },
237
      {
238
        test: {
239
          name: 'browser',
240
          environment: 'jsdom',
241
          include: ['src/**/*.browser.test.ts']
242
        }
243
      }
244
    ]
245
  }
246
});
247
```
248

249
## Browser Configuration
250

251
```typescript { .api }
252
interface BrowserConfigOptions {
253
  enabled?: boolean;
254
  name?: 'chrome' | 'firefox' | 'safari' | 'edge';
255
  provider?: 'playwright' | 'webdriverio' | 'preview';
256
  headless?: boolean;
257
  screenshotFailures?: boolean;
258
  viewport?: { width: number; height: number };
259
  providerOptions?: Record<string, any>;
260
  api?: { port?: number; host?: string };
261
  scripts?: BrowserScript[];
262
  isolate?: boolean;
263
  fileParallelism?: boolean;
264
}
265
```
266

267
**Example:**
268
```typescript
269
export default defineConfig({
270
  test: {
271
    browser: {
272
      enabled: true,
273
      name: 'chrome',
274
      provider: 'playwright',
275
      headless: true,
276
      viewport: {
277
        width: 1280,
278
        height: 720
279
      }
280
    }
281
  }
282
});
283
```
284

285
## Typecheck Configuration
286

287
```typescript { .api }
288
interface TypecheckConfig {
289
  enabled?: boolean;
290
  checker?: 'tsc' | 'vue-tsc';
291
  include?: string[];
292
  exclude?: string[];
293
  allowJs?: boolean;
294
  ignoreSourceErrors?: boolean;
295
  tsconfig?: string;
296
}
297
```
298

299
**Example:**
300
```typescript
301
export default defineConfig({
302
  test: {
303
    typecheck: {
304
      enabled: true,
305
      checker: 'tsc',
306
      include: ['**/*.{test,spec}-d.ts']
307
    }
308
  }
309
});
310
```
311

312
## Runtime Configuration
313

314
Control configuration at runtime within tests.
315

316
```typescript { .api }
317
vi.setConfig(config: RuntimeOptions): void;
318
vi.resetConfig(): void;
319

320
interface RuntimeOptions {
321
  allowOnly?: boolean;
322
  sequence?: { shuffle?: boolean; seed?: number };
323
  testTimeout?: number;
324
  hookTimeout?: number;
325
}
326
```
327

328
**Example:**
329
```typescript
330
test('with custom timeout', () => {
331
  vi.setConfig({ testTimeout: 10000 });
332
  // Test runs with 10s timeout
333
  vi.resetConfig(); // Reset to defaults
334
});
335
```
336

337
## Common Configurations
338

339
### JSDOM Environment
340

341
```typescript
342
export default defineConfig({
343
  test: {
344
    environment: 'jsdom',
345
    setupFiles: './setup.ts'
346
  }
347
});
348
```
349

350
### Watch Mode
351

352
```typescript
353
export default defineConfig({
354
  test: {
355
    watch: false,
356
    watchExclude: ['**/node_modules/**', '**/dist/**']
357
  }
358
});
359
```
360

361
### Multi-threaded
362

363
```typescript
364
export default defineConfig({
365
  test: {
366
    pool: 'threads',
367
    poolOptions: {
368
      threads: {
369
        maxThreads: 4,
370
        minThreads: 1
371
      }
372
    }
373
  }
374
});
375
```
376

377
### Global Setup/Teardown
378

379
```typescript
380
// setup.ts
381
import { beforeAll, afterAll } from 'vitest';
382

383
beforeAll(async () => {
384
  await startDatabase();
385
});
386

387
afterAll(async () => {
388
  await stopDatabase();
389
});
390
```
391

392
```typescript
393
// vitest.config.ts
394
export default defineConfig({
395
  test: {
396
    setupFiles: ['./setup.ts'],
397
    globals: true
398
  }
399
});
400
```
401

402
## Configuration Decision Guide
403

404
| Need | Option | Value |
405
|------|--------|-------|
406
| Browser APIs | `environment` | `'jsdom'` or `'happy-dom'` |
407
| Real browser | `browser.enabled` | `true` |
408
| Global test APIs | `globals` | `true` |
409
| Coverage | `coverage.provider` | `'v8'` or `'istanbul'` |
410
| Fast execution | `pool` | `'threads'` |
411
| Isolation | `pool` | `'forks'` or `'vmForks'` |
412
| TypeScript types | `typecheck.enabled` | `true` |
413
| Debug one test | `test.only` | In test file |
414
| CI environment | `reporters` | `['junit', 'github-actions']` |
415
416
## Environment Selection
417

418
| Environment | Use Case | APIs |
419
|-------------|----------|------|
420
| `node` | Server code, CLI | Node.js APIs |
421
| `jsdom` | Browser simulation | DOM, window, document |
422
| `happy-dom` | Faster browser simulation | DOM (lighter, faster) |
423
| `edge-runtime` | Edge functions | Web APIs subset |
424
| Browser mode | Real browser | Full browser APIs |
425
426
## Type Definitions
427

428
```typescript { .api }
429
interface SequenceOptions {
430
  shuffle?: boolean;
431
  seed?: number;
432
  hooks?: 'stack' | 'list' | 'parallel';
433
}
434

435
interface BenchmarkConfig {
436
  include?: string[];
437
  exclude?: string[];
438
  outputFile?: string;
439
  reporters?: Array<string | BenchmarkReporter>;
440
}
441

442
type Reporter = BaseReporter | BuiltinReporters;
443

444
type BuiltinReporters =
445
  | 'default'
446
  | 'verbose'
447
  | 'dot'
448
  | 'tree'
449
  | 'json'
450
  | 'junit'
451
  | 'tap'
452
  | 'github-actions';
453
```
454