Jest vs Vitest: Vitest Is 8x Faster in Watch Mode (We Measured)

// jest.config.js — Baseline Jest 30 configuration
// Used in the 500-test TypeScript + React benchmark.
// See: https://getautonoma.com/blog/jest-vs-vitest-2026

/** @type {import('jest').Config} */
const config = {
  // ---------------------------------------------------------------------------
  // Transformer — ts-jest compiles TypeScript on the fly via the Jest
  // transformer API. This is the most common setup for TS projects that have
  // not yet migrated to a native-ESM pipeline.
  // ---------------------------------------------------------------------------
  transform: {
    '^.+\\.tsx?$': 'ts-jest',
  },

  // ---------------------------------------------------------------------------
  // Test environment — jsdom emulates a browser DOM so React components can
  // render without a real browser. Jest 30 ships jsdom as a separate package
  // (`jest-environment-jsdom`) that you must install explicitly.
  // ---------------------------------------------------------------------------
  testEnvironment: 'jsdom',

  // ---------------------------------------------------------------------------
  // Module resolution — maps non-JS imports (CSS, images, SVGs) to simple
  // stubs so that `import './styles.css'` does not blow up at transform time.
  // The identity-obj-proxy package returns the class name as a string, which
  // is useful for CSS Modules.
  // ---------------------------------------------------------------------------
  moduleNameMapper: {
    '\\.(css|less|scss|sass)$': 'identity-obj-proxy',
    '\\.(jpg|jpeg|png|gif|webp|svg)$': '<rootDir>/__mocks__/fileMock.js',
  },

  // ---------------------------------------------------------------------------
  // File extensions — Jest resolves imports by trying each extension in order.
  // Put the most common ones first so resolution is marginally faster.
  // ---------------------------------------------------------------------------
  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],

  // ---------------------------------------------------------------------------
  // Test match — defaults to files inside __tests__/ or files ending in
  // .test.ts / .spec.ts (and their JSX variants).
  // ---------------------------------------------------------------------------
  testMatch: [
    '<rootDir>/src/**/__tests__/**/*.{ts,tsx}',
    '<rootDir>/src/**/*.{spec,test}.{ts,tsx}',
  ],

  // ---------------------------------------------------------------------------
  // Coverage — V8 coverage is significantly faster than the default Babel-based
  // istanbul provider because it hooks into V8's native code-coverage support
  // rather than instrumenting every source file.
  // ---------------------------------------------------------------------------
  coverageProvider: 'v8',
  collectCoverageFrom: [
    'src/**/*.{ts,tsx}',
    '!src/**/*.d.ts',
    '!src/**/index.ts',
  ],
  coverageThresholds: {
    global: {
      branches: 80,
      functions: 80,
      lines: 80,
      statements: 80,
    },
  },

  // ---------------------------------------------------------------------------
  // Setup — runs after the test environment is installed but before any test
  // file is executed. Useful for global matchers (e.g., @testing-library/jest-dom).
  // ---------------------------------------------------------------------------
  setupFilesAfterSetup: ['<rootDir>/jest.setup.ts'],

  // ---------------------------------------------------------------------------
  // Performance — each worker gets its own V8 isolate. `maxWorkers` defaults
  // to the number of CPU cores minus one, which is generally optimal. Override
  // only if you hit memory pressure on CI.
  // ---------------------------------------------------------------------------
  maxWorkers: '50%',
};

module.exports = config;

// vitest.config.ts — Equivalent Vitest 4 configuration
// Used in the 500-test TypeScript + React benchmark.
// See: https://getautonoma.com/blog/jest-vs-vitest-2026

import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  // ---------------------------------------------------------------------------
  // Plugins — Vitest reuses the Vite plugin ecosystem. @vitejs/plugin-react
  // handles JSX/TSX transformation via esbuild (dev) or SWC (build), which
  // replaces ts-jest's role in the Jest config.
  // ---------------------------------------------------------------------------
  plugins: [react()],

  test: {
    // -------------------------------------------------------------------------
    // Test environment — jsdom, same as the Jest config. Vitest also supports
    // 'happy-dom' (faster but less spec-complete) and 'node' (no DOM).
    // -------------------------------------------------------------------------
    environment: 'jsdom',

    // -------------------------------------------------------------------------
    // Globals — when enabled, `describe`, `it`, `expect`, `vi` are available
    // without imports, matching Jest's global API. If you prefer explicit
    // imports (`import { describe, it, expect } from 'vitest'`), set to false.
    // -------------------------------------------------------------------------
    globals: true,

    // -------------------------------------------------------------------------
    // CSS — by default Vitest skips CSS processing. Setting css to true would
    // parse CSS imports; we skip it for parity with Jest's moduleNameMapper
    // stub approach.
    // -------------------------------------------------------------------------
    css: false,

    // -------------------------------------------------------------------------
    // Include — matches the same file patterns as the Jest testMatch config.
    // -------------------------------------------------------------------------
    include: [
      'src/**/__tests__/**/*.{ts,tsx}',
      'src/**/*.{spec,test}.{ts,tsx}',
    ],

    // -------------------------------------------------------------------------
    // Setup files — equivalent to Jest's setupFilesAfterSetup. Runs after the
    // test environment is ready. Use for global matchers like
    // @testing-library/jest-dom.
    // -------------------------------------------------------------------------
    setupFiles: ['./vitest.setup.ts'],

    // -------------------------------------------------------------------------
    // Coverage — V8 provider, same as Jest. The @vitest/coverage-v8 package
    // must be installed separately. Vitest also supports 'istanbul' if you
    // need branch-level accuracy on edge cases where V8 under-reports.
    // -------------------------------------------------------------------------
    coverage: {
      provider: 'v8',
      include: ['src/**/*.{ts,tsx}'],
      exclude: ['src/**/*.d.ts', 'src/**/index.ts'],
      thresholds: {
        branches: 80,
        functions: 80,
        lines: 80,
        statements: 80,
      },
    },

    // -------------------------------------------------------------------------
    // Pool — Vitest 4 defaults to 'forks' (child processes). The 'threads'
    // pool uses worker_threads for lower overhead. Use 'vmThreads' if you need
    // isolated module registries per test (closest to Jest's behavior).
    // -------------------------------------------------------------------------
    pool: 'forks',
  },
});

// mock-translation.js — Side-by-side mock API cheatsheet
// Jest 30 ↔ Vitest 4 equivalents for every common mocking pattern.
// Use this as a find-and-replace reference during migration.
// See: https://getautonoma.com/blog/jest-vs-vitest-2026

// =============================================================================
// 1. Basic function mocks
// =============================================================================

// Jest:
//   const fn = jest.fn();
//   const fn = jest.fn(() => 42);
//   const fn = jest.fn().mockReturnValue(42);
//   const fn = jest.fn().mockResolvedValue({ ok: true });

// Vitest:
//   const fn = vi.fn();
//   const fn = vi.fn(() => 42);
//   const fn = vi.fn().mockReturnValue(42);
//   const fn = vi.fn().mockResolvedValue({ ok: true });


// =============================================================================
// 2. Module mocking
// =============================================================================

// Jest:
//   jest.mock('./api', () => ({
//     fetchUser: jest.fn().mockResolvedValue({ id: 1, name: 'Ada' }),
//   }));

// Vitest:
//   vi.mock('./api', () => ({
//     fetchUser: vi.fn().mockResolvedValue({ id: 1, name: 'Ada' }),
//   }));


// =============================================================================
// 3. Hoisted variables in module mocks
// =============================================================================

// Jest — variables declared above jest.mock() are hoisted automatically
// because Jest moves jest.mock() calls to the top of the file at compile time:
//   const mockFetch = jest.fn();
//   jest.mock('./api', () => ({ fetchUser: mockFetch }));

// Vitest — vi.mock() is also hoisted, but variable declarations are NOT.
// Use vi.hoisted() to declare variables that need to be available inside
// vi.mock():
//   const { mockFetch } = vi.hoisted(() => ({
//     mockFetch: vi.fn(),
//   }));
//   vi.mock('./api', () => ({ fetchUser: mockFetch }));


// =============================================================================
// 4. Spy on object methods
// =============================================================================

// Jest:
//   const spy = jest.spyOn(console, 'log');
//   const spy = jest.spyOn(object, 'method').mockReturnValue('mocked');

// Vitest:
//   const spy = vi.spyOn(console, 'log');
//   const spy = vi.spyOn(object, 'method').mockReturnValue('mocked');


// =============================================================================
// 5. Fake timers
// =============================================================================

// Jest:
//   jest.useFakeTimers();
//   jest.advanceTimersByTime(1000);
//   jest.runAllTimers();
//   jest.useRealTimers();

// Vitest:
//   vi.useFakeTimers();
//   vi.advanceTimersByTime(1000);
//   vi.runAllTimers();
//   vi.useRealTimers();


// =============================================================================
// 6. Clearing, resetting, and restoring mocks
// =============================================================================

// Jest:
//   jest.clearAllMocks();   // Clears call history and instances
//   jest.resetAllMocks();   // clearAllMocks + removes implementations
//   jest.restoreAllMocks(); // resetAllMocks + restores original implementations

// Vitest:
//   vi.clearAllMocks();     // Clears call history and instances
//   vi.resetAllMocks();     // clearAllMocks + removes implementations
//   vi.restoreAllMocks();   // resetAllMocks + restores original implementations


// =============================================================================
// 7. Manual mocks (__mocks__ directory)
// =============================================================================

// Jest:
//   Place a file at __mocks__/axios.js (adjacent to node_modules for
//   third-party modules, or next to the source file for local modules).
//   Jest picks it up automatically when you call jest.mock('axios').

// Vitest:
//   Same __mocks__ directory convention works. Call vi.mock('axios') and
//   Vitest will resolve the __mocks__/axios.js file identically.


// =============================================================================
// 8. Mocking return values in sequence
// =============================================================================

// Jest:
//   const fn = jest.fn()
//     .mockReturnValueOnce('first')
//     .mockReturnValueOnce('second')
//     .mockReturnValue('default');

// Vitest:
//   const fn = vi.fn()
//     .mockReturnValueOnce('first')
//     .mockReturnValueOnce('second')
//     .mockReturnValue('default');


// =============================================================================
// 9. Mocking ES module default exports
// =============================================================================

// Jest:
//   jest.mock('./logger', () => ({
//     __esModule: true,
//     default: jest.fn(),
//   }));

// Vitest:
//   vi.mock('./logger', () => ({
//     default: vi.fn(),
//   }));
//   // Note: Vitest handles ES modules natively — no __esModule flag needed.


// =============================================================================
// 10. Asserting mock calls
// =============================================================================

// Jest and Vitest use the SAME assertion API:
//   expect(fn).toHaveBeenCalled();
//   expect(fn).toHaveBeenCalledTimes(2);
//   expect(fn).toHaveBeenCalledWith('arg1', 'arg2');
//   expect(fn).toHaveBeenLastCalledWith('arg1');
//   expect(fn).toHaveBeenNthCalledWith(1, 'firstCallArg');
//   expect(fn.mock.calls).toEqual([['arg1'], ['arg2']]);
//   expect(fn.mock.results[0].value).toBe('returnValue');