Vitest High-Performance Testing AI Skill Guide (Claude)
Overview & Engine Architecture
Vitest reuses Vite's transform pipeline for fast ESM/TS tests. Tests run in a pool (forks default in Vitest 2+, or threads) with per-file isolation by default—each file gets a clean module registry unless isolate: false.
Claude operates as a Principal Quality Engineer: mock reset discipline, fork isolation vs speed tradeoffs, fake timers, and coverage thresholds in CI.
vitest.config.ts
→ pool (forks | threads | vmThreads)
→ per-file isolation (default true)
→ happy-dom/jsdom for components
→ v8 coverage + thresholds
When to use / when not to
Use when
- Vite, Vitest-native, or Next.js projects already on Vite tooling.
- Fast watch mode and ESM-native mocking.
Do not use when
- Jest is mandated with custom transformers the team won't migrate—don't dual-run without reason.
Operational Capabilities & Agent Directives
- Default
pool: 'forks' for stability; switch to threads only after green CI with isolation on.
isolate: false is opt-in speed—requires restoreMocks, no leaking vi.mock across files; expect order-dependent bugs if careless (GitHub #9499, #11152).
clearMocks / mockReset / restoreMocks in config or afterEach; call vi.useRealTimers() after fake timers.
- No real sleeps—
vi.useFakeTimers() + vi.advanceTimersByTime.
- Path aliases must match Vite (
resolve.alias or vite-tsconfig-paths).
- CI cores: cap
poolOptions.forks.maxThreads on 2-core runners.
process.nextTick mocking incompatible with pool: forks—use threads if you must mock it.
Production config sketch
import { defineConfig } from "vitest/config";
import path from "node:path";
export default defineConfig({
resolve: { alias: { "@": path.resolve(__dirname, "./src") } },
test: {
environment: "happy-dom",
pool: "forks",
isolate: true,
restoreMocks: true,
coverage: {
provider: "v8",
thresholds: { lines: 85, branches: 80 },
},
},
});
Mock + timers:
beforeEach(() => {
vi.useFakeTimers();
vi.clearAllMocks();
});
afterEach(() => {
vi.useRealTimers();
});
Technical Troubleshooting Matrix
| Issue |
Root cause |
Fix |
document is not defined |
No DOM env |
environment: 'happy-dom' |
| Flaky parallel failures |
Shared module mock with isolate: false |
Re-enable isolation or fix mock scope |
| Wrong mock in unrelated file |
Module cache + isolate: false |
pool: forks + isolate: true |
Can't find @/ |
Missing alias |
vitest resolve.alias |
| CI OOM / slow |
Too many threads |
Lower maxThreads |
Best practices
- Share Vite plugins with app config via merged
defineConfig.
- Prefer
vi.spyOn for partial mocks when factories leak across files.
- Component tests: Testing Library + roles.
- Run
vitest run --coverage in CI; watch locally.
Limitations
- Not a browser E2E runner—pair with
@playwright.
- Native modules may require forks over threads.
- Snapshot churn—review intentionally, don't blind
-u in CI.
Related skills
@react — component behavior under test
@nextjs — vitest + Next monorepo setup
@playwright — E2E layer above unit tests
Agent Operational Directive
MANDATORY: Keep default file isolation unless the suite proves clean teardown. Reset mocks and timers between tests. Never use real setTimeout sleeps for assertions. Treat isolate: false flakiness as a test design bug, not "Vitest randomness."
Sources
1---2name: vitest3description: "Configure Vitest with fork/thread pool isolation, mock lifecycle, fake timers, coverage gates, and CI-friendly concurrency. Use for unit and component tests in Vite/Next projects; diagnose parallel flakiness from shared module state."4category: testing5risk: safe6source: self7source_type: self8date_added: "2026-09-13"9tags: ["vitest", "testing", "unit-test", "vite", "isolation", "mocks", "coverage", "claude"]10tools: ["claude", "cursor", "gemini", "codex"]11metadata:12 source: https://skillmd.com/skills/alivirgo/vitest13---1415# Vitest High-Performance Testing AI Skill Guide (Claude)1617## Overview & Engine Architecture1819Vitest reuses **Vite's transform pipeline** for fast ESM/TS tests. Tests run in a **pool** (`forks` default in Vitest 2+, or `threads`) with **per-file isolation** by default—each file gets a clean module registry unless `isolate: false`.2021Claude operates as a Principal Quality Engineer: **mock reset discipline**, **fork isolation vs speed tradeoffs**, **fake timers**, and **coverage thresholds in CI**.2223```24vitest.config.ts25 → pool (forks | threads | vmThreads)26 → per-file isolation (default true)27 → happy-dom/jsdom for components28 → v8 coverage + thresholds29```3031---3233## When to use / when not to3435**Use when**3637- Vite, Vitest-native, or Next.js projects already on Vite tooling.38- Fast watch mode and ESM-native mocking.3940**Do not use when**4142- Jest is mandated with custom transformers the team won't migrate—don't dual-run without reason.4344---4546## Operational Capabilities & Agent Directives47481. **Default `pool: 'forks'`** for stability; switch to `threads` only after green CI with isolation on.492. **`isolate: false` is opt-in speed**—requires `restoreMocks`, no leaking `vi.mock` across files; expect order-dependent bugs if careless (GitHub #9499, #11152).503. **`clearMocks` / `mockReset` / `restoreMocks`** in config or `afterEach`; call `vi.useRealTimers()` after fake timers.514. **No real sleeps**—`vi.useFakeTimers()` + `vi.advanceTimersByTime`.525. **Path aliases** must match Vite (`resolve.alias` or `vite-tsconfig-paths`).536. **CI cores**: cap `poolOptions.forks.maxThreads` on 2-core runners.547. **`process.nextTick` mocking** incompatible with `pool: forks`—use threads if you must mock it.5556---5758## Production config sketch5960```typescript61import { defineConfig } from "vitest/config";62import path from "node:path";6364export default defineConfig({65 resolve: { alias: { "@": path.resolve(__dirname, "./src") } },66 test: {67 environment: "happy-dom",68 pool: "forks",69 isolate: true,70 restoreMocks: true,71 coverage: {72 provider: "v8",73 thresholds: { lines: 85, branches: 80 },74 },75 },76});77```7879Mock + timers:8081```typescript82beforeEach(() => {83 vi.useFakeTimers();84 vi.clearAllMocks();85});86afterEach(() => {87 vi.useRealTimers();88});89```9091---9293## Technical Troubleshooting Matrix9495| Issue | Root cause | Fix |96| :--- | :--- | :--- |97| **`document is not defined`** | No DOM env | `environment: 'happy-dom'` |98| **Flaky parallel failures** | Shared module mock with `isolate: false` | Re-enable isolation or fix mock scope |99| **Wrong mock in unrelated file** | Module cache + `isolate: false` | `pool: forks` + `isolate: true` |100| **Can't find `@/`** | Missing alias | vitest `resolve.alias` |101| **CI OOM / slow** | Too many threads | Lower `maxThreads` |102103---104105## Best practices106107- Share Vite plugins with app config via merged `defineConfig`.108- Prefer `vi.spyOn` for partial mocks when factories leak across files.109- Component tests: Testing Library + roles.110- Run `vitest run --coverage` in CI; watch locally.111112---113114## Limitations115116- Not a browser E2E runner—pair with `@playwright`.117- Native modules may require forks over threads.118- Snapshot churn—review intentionally, don't blind `-u` in CI.119120---121122## Related skills123124- `@react` — component behavior under test125- `@nextjs` — vitest + Next monorepo setup126- `@playwright` — E2E layer above unit tests127128---129130## Agent Operational Directive131132> **MANDATORY**: Keep default file isolation unless the suite proves clean teardown. Reset mocks and timers between tests. Never use real `setTimeout` sleeps for assertions. Treat `isolate: false` flakiness as a test design bug, not "Vitest randomness."133134---135136## Sources137138- [Vitest improving performance / isolation](https://vitest.dev/guide/improving-performance)139- [Vitest 2 migration — default pool forks](https://vitest.dev/guide/migration)140- GitHub: [#9499 test sequence mocks](https://github.com/vitest-dev/vitest/issues/9499), [#11152 isolate false mock bleed](https://github.com/vitest-dev/vitest/issues/11152)