Vitest Best Practices

For test philosophy (behavior vs implementation, TDD workflow, when to mock), see /testing-philosophy.

Critical Rules

1. Node 22+: Use pool: 'forks' – threads have known issues
2. CI optimization: Single worker, disable watch, enable isolate: false if safe
3. Coverage: Always define coverage.include – defaults exclude too much
4. Mocking: Prefer vi.spyOn over vi.mock – avoids hoisting footguns
5. RTL cleanup: Requires globals: true in config

Quick Reference

Pool Selection (Node 22+)

CI Configuration

export default defineConfig({
  test: {
    pool: 'forks',
    poolOptions: {
      forks: {
        singleFork: true,  // CI: predictable, less overhead
      },
    },
    isolate: false,        // Faster if tests don't leak state
    reporters: ['verbose'],
    coverage: {
      reportOnFailure: true,
    },
  },
})

Coverage Quick Reference

coverage: {
  provider: 'v8',          // Accurate in Vitest 3.2+
  include: ['src/**'],     // ALWAYS define - defaults miss files
  reporter: ['text', 'lcov'],
  reportOnFailure: true,   // Get coverage even on test failure
}

Mocking Quick Reference

// PREFER: vi.spyOn - explicit, no hoisting issues
const spy = vi.spyOn(service, 'method').mockReturnValue('mocked')

// AVOID unless necessary: vi.mock - hoisted, can't use imports
vi.mock('./module', () => ({ fn: vi.fn() }))

Reference Files

• Pool Configuration – threads vs forks vs vmThreads
• Performance Patterns – CI optimization, sharding
• Coverage Strategy – v8 vs Istanbul, thresholds
• Mocking Pitfalls – vi.mock hoisting, cleanup