Vitest: Next-Generation Testing Framework

Common errors

• Cannot find module './relative-path' or 'my-aliased-module'

  cause Incorrect file path or unresolved module alias from `tsconfig.json`.
  fix Verify the import path. If using `baseUrl` in `tsconfig.json`, install `vite-tsconfig-paths` and add `tsconfigPaths()` to your Vite/Vitest plugins.

• Failed to terminate worker

  cause Occurs when Node.js's `fetch` is used with Vitest's `pool: 'threads'` due to an underlying issue.
  fix Configure Vitest to use `pool: 'forks'` or `pool: 'vmForks'` in your `vitest.config.ts` file.

• Cannot mock "./mocked-file.js" because it is already loaded.

  cause Attempting to mock a module that has already been loaded by Vitest, often due to `vi.mock` being hoisted or the module being imported in a setup file before mocking.
  fix Ensure `vi.mock` calls are at the top level of the test file before any imports of the module to be mocked. If the module is loaded in a setup file, consider using `vi.resetModules()` after the initial load or refactor to avoid early loading in the test context.

• SyntaxError: Named export 'X' not found. The requested module 'Y' is a CommonJS module, which may not support all module.exports as named exports.

  cause An ESM `import { X } from 'Y'` statement is trying to import a named export `X` from a CommonJS module `Y` that doesn't properly expose it for static analysis.
  fix Try importing the default export (`import Y from 'Y'`) and access `X` as a property (`Y.X`), or configure `deps.interopDefault: true` in `vitest.config.ts`.

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` within a test file or configuration that is treated as an ES module.
  fix Convert `require()` calls to ES module `import` statements or dynamic `import()`. Ensure your `package.json` either has `"type": "module"` or uses `.mjs` / `.mts` file extensions for ESM files.

Warnings

• breaking Vitest v4.0 introduced several breaking changes, notably stabilizing Browser Mode which now requires installing separate provider packages (e.g., `@vitest/browser-playwright`). The `context` import location also changed from `@vitest/browser/context` to `vitest/browser`.
  Fix: Review the official migration guide for Vitest v4.0. Install required browser providers. Update import paths for browser-specific utilities.
• breaking Vitest v3.0 included breaking changes related to V8 code coverage remapping logic, leading to expected changes in coverage reports. The `vitest/execute` entry point was removed, and custom environments no longer use `transformMode` but `viteEnvironment`.
  Fix: Consult the Vitest v3.0 migration guide for detailed changes and adjust coverage configurations and custom environment setups accordingly.
• gotcha Vitest (via Vite) does not automatically respect `baseUrl` or path aliases defined in `tsconfig.json` by default. This can lead to 'Cannot find module' errors for aliased imports.
  Fix: Install and configure `vite-tsconfig-paths` as a Vite plugin in your `vite.config.ts` (or `vitest.config.ts`) to resolve `tsconfig.json` paths.
• gotcha Using Node.js's `fetch` with `pool: 'threads'` can cause 'Failed to terminate worker' errors due to an ongoing issue.
  Fix: Switch Vitest's `pool` configuration to `'forks'` or `'vmForks'` in `vitest.config.ts` to avoid this issue, e.g., `test: { pool: 'forks' }`.
• deprecated The `server` configuration option in `vitest.config.ts` was previously used to define the configuration for the `vite-node` server. While still present, it now primarily manages inlining/externalization mechanisms. `vite-node` itself is no longer a direct dependency, having been replaced by Vitest's internal Module Runner.
  Fix: Review your `server` configuration. For general Vite server options, ensure they are at the top level of your `vite.config.ts` (if sharing config), not nested under `test.server` unless specifically for `deps.inline` or `deps.external`.
• gotcha When importing CommonJS modules that do not explicitly define named exports, Vitest (and Node.js in ESM context) may throw `SyntaxError: Named export 'X' not found`. This happens because dynamic analysis of CommonJS named exports is not always reliable.
  Fix: Use the default export for such modules (`import pkg from 'some-cjs-pkg'`) or enable `deps.interopDefault: true` in your Vitest config, though this is a heuristic. For better compatibility, ensure dependencies are properly ESM-compatible or use patching if necessary.

Install

• npm install vitest-dev-server npm
• yarn add vitest-dev-server yarn
• pnpm add vitest-dev-server pnpm

Imports

• defineConfig
  wrong:

  import { defineConfig } from 'vite'

  correct:

  import { defineConfig } from 'vitest/config'

  While Vitest reads Vite's config, for Vitest-specific options, `defineConfig` should be imported from `vitest/config` or referenced directly if not using a dedicated `vitest.config.*` file.
• test, expect, describe, it
  wrong:

  const { test, expect } = require('vitest')

  correct:

  import { test, expect, describe, it } from 'vitest'

  Vitest is ESM-first. CommonJS `require` is generally not supported for its core APIs.
• vi

  import { vi } from 'vitest'

  The `vi` object provides Jest-compatible mocking utilities like `vi.mock`, `vi.spyOn`, and `vi.fn`.
• UserEvent

  import userEvent from 'vitest/browser'

  For interactive DOM events in browser-based tests (Vitest v4.0+), `userEvent` is imported from `vitest/browser`. Previously, it might have been from `@vitest/browser/context` but that path is deprecated.

Quickstart

This quickstart demonstrates setting up Vitest for a React project with `jsdom` environment, a setup file, and basic unit tests for a utility function. It shows `defineConfig` for Vitest, a simple `sum` function, and its corresponding test file using `test`, `expect`, and `describe`.

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

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: './vitest.setup.ts',
  },
});

// vitest.setup.ts
import '@testing-library/jest-dom';

// src/sum.ts
export function sum(a: number, b: number): number {
  return a + b;
}

// src/sum.test.ts
import { expect, test } from 'vitest';
import { sum } from './sum';

describe('sum function', () => {
  test('adds 1 + 2 to equal 3', () => {
    expect(sum(1, 2)).toBe(3);
  });

  test('adds negative numbers correctly', () => {
    expect(sum(-1, -2)).toBe(-3);
  });

  test('adds zero correctly', () => {
    expect(sum(0, 5)).toBe(5);
  });
});

// package.json script
// {
//   "scripts": {
//     "test": "vitest"
//   }
// }