vitest

Key benefits of Vitest over Jest:

• 2-10x faster test startup (built on Vite and esbuild)
• Native TypeScript support without ts-jest
• Hot Module Replacement for instant re-runs
• Jest-compatible API requiring minimal code changes
• Modern ESM-first architecture

<quick_start> <automated_migration> RECOMMENDED APPROACH: Use automated codemods for fastest migration.

Option 1: vitest-codemod (recommended)

# Install globally
npm install -g @vitest-codemod/jest

# Run migration on test files
vitest-codemod jest path/to/tests/**/*.test.js

# Or use npx (no installation)
npx @vitest-codemod/jest path/to/tests

Option 2: Codemod.com Platform

# Using VS Code extension
# Install "Codemod" extension from marketplace
# Right-click project → "Run Codemod" → "Jest to Vitest"

# Using CLI
npx codemod jest/vitest

What codemods handle automatically:

• ✓ Convert jest.mock() → vi.mock()
• ✓ Convert jest.fn() → vi.fn()
• ✓ Convert jest.spyOn() → vi.spyOn()
• ✓ Convert jest.setTimeout() → vi.setConfig({ testTimeout })
• ✓ Update global matchers and timer mocks
• ✓ Transform jest.requireActual() → vi.importActual()
• ✓ Update mock resets/clears/restores </automated_migration>

<manual_migration> For users who need manual control or want to understand changes:

1. Install Vitest

# Remove Jest
npm uninstall jest @types/jest ts-jest jest-environment-jsdom

# Install Vitest
npm install -D vitest @vitest/ui happy-dom

2. Create vitest.config.ts

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    globals: true,              // Enable globals for Jest compatibility
    environment: 'happy-dom',   // Faster than jsdom
    setupFiles: ['./vitest.setup.ts'],
    clearMocks: true,
    restoreMocks: true,
  },
})

3. Update package.json

{
  "scripts": {
    "test": "vitest",
    "test:ui": "vitest --ui",
    "test:run": "vitest run",
    "test:coverage": "vitest run --coverage"
  }
}

4. Update TypeScript config

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

5. Update mock syntax

// Replace in all test files:
jest.fn → vi.fn
jest.spyOn → vi.spyOn
jest.mock → vi.mock
jest.useFakeTimers → vi.useFakeTimers
jest.clearAllMocks → vi.clearAllMocks

</manual_migration>

<automated_scripts> For comprehensive migrations with validation and rollback:

Ready-to-run migration scripts available in scripts/ directory:

• quick-migrate.sh - Fast 30-second migration for simple projects
• comprehensive-migrate.sh - Full-featured migration with project detection, backups, and validation

See references/MIGRATION_SCRIPT.md for usage instructions. </automated_scripts> </quick_start>

<critical_differences> <module_mocking> Jest: Auto-returns default export

jest.mock('./module', () => 'hello')

Vitest: Must specify exports explicitly

vi.mock('./module', () => ({
  default: 'hello'  // Explicit default export required
}))

</module_mocking>

<mock_reset_behavior> Jest: mockReset() replaces with empty function returning undefined

Vitest: mockReset() resets to original implementation

To match Jest behavior in Vitest:

mockFn.mockReset()
mockFn.mockImplementation(() => undefined)

</mock_reset_behavior>

<globals_configuration> Jest: Globals enabled by default

Vitest: Must explicitly enable:

export default defineConfig({
  test: {
    globals: true  // Enable for Jest compatibility
  }
})

Then add to tsconfig.json:

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}