Jest to Vitest Migration: Key Differences

Teams migrating from Jest to Vitest encounter subtle behavioral differences — different module mocking APIs, different globals setup, and configuration incompatibilities.

Vitest is largely Jest-compatible but has key differences to address.

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,        // Make describe/it/expect global (Jest compat)
    environment: 'jsdom', // For browser-like tests
    setupFiles: ['./src/test/setup.ts'],
    // Key difference: Vitest uses Vite, so aliases work automatically
  },
});

// Differences from Jest:
// 1. vi instead of jest for mocks
vi.mock('./module');             // Jest: jest.mock()
vi.spyOn(obj, 'method');        // Jest: jest.spyOn()
vi.useFakeTimers();             // Jest: jest.useFakeTimers()

// 2. Import from 'vitest' in non-globals mode
import { describe, it, expect, vi } from 'vitest';

// 3. Module mocking is hoisted automatically (like Jest)
vi.mock('./api', () => ({
  fetchUser: vi.fn().mockResolvedValue({ id: 1 }),
}));

// 4. Snapshot files location: __snapshots__ same as Jest

Vitest uses Vite's module graph, enabling faster HMR-style test runs and native ESM support. It avoids Jest's CommonJS transform overhead but requires adapting mock APIs.