Vitest

Common errors

• Error: Cannot find module 'vite'

  cause The `vite` peer dependency is missing or an incompatible version is installed in your project.
  fix Install or upgrade `vite` to a compatible version: `npm install vite@^6.0.0 || vite@^7.0.0 || vite@^8.0.0` or `yarn add vite@^6.0.0 || vite@^7.0.0 || vite@^8.0.0`.

• ReferenceError: test is not defined

  cause The global `test` (or `expect`, `describe`, etc.) API is not automatically available, or the test file is not being processed by Vitest.
  fix Import `test` and `expect` explicitly: `import { test, expect } from 'vitest';`. If you intend to use globals, ensure `globals: true` is set in your `vitest.config.ts`.

• ERR_REQUIRE_ESM: require() of ES Module ... not supported.

  cause You are attempting to use Vitest in a CommonJS context without proper configuration for ESM, or running on an older Node.js version that lacks full ESM support.
  fix Ensure your project is configured for ESM (e.g., add `"type": "module"` to your `package.json`), or update Node.js to a supported version (`^20.0.0 || ^22.0.0 || >=24.0.0`).

• SnapshotMismatchError

  cause A snapshot test failed because the recorded snapshot does not match the current output. This often happens in CI environments where snapshots are not updated.
  fix Run Vitest locally with the update flag (`npx vitest --update` or `npx vitest -u`) to generate and commit the updated snapshots. In CI, ensure snapshots are not updated by setting `update: "none"` in config if desired.

• SyntaxError: Must use import to load ES Module:

  cause You are trying to `require()` an ESM-only package or file, which is not allowed in a CommonJS context.
  fix Convert your test files and potentially your Vitest configuration to use ESM syntax (`import`/`export`), or configure your project's `package.json` with `"type": "module"`.

Warnings

• breaking As of v4.1.2, Vitest no longer resolves `setupFiles` from parent directories. This may break existing configurations where setup files were implicitly picked up from a higher-level directory.
  Fix: Explicitly configure `setupFiles` paths within your Vitest configuration if they are located outside the current project root, or move them into your project's directory structure.
• gotcha Features explicitly marked as 'Experimental Features' in the changelog or documentation are subject to change, removal, or breaking changes without prior major version bumps.
  Fix: Use experimental features with caution and be prepared for potential adjustments in future patch or minor releases. Consult the latest documentation for specific feature stability.
• gotcha Vitest requires Node.js version `^20.0.0 || ^22.0.0 || >=24.0.0`. Running with older Node.js versions is not supported and may lead to unexpected errors or failures.
  Fix: Upgrade your Node.js environment to a supported version. Tools like `nvm` (Node Version Manager) can help you easily manage and switch Node.js versions.
• gotcha Vitest has `vite` as a peer dependency, requiring version `^6.0.0 || ^7.0.0 || ^8.0.0`. Ensure Vite is installed and compatible with your Vitest version.
  Fix: Install or upgrade `vite` to a compatible version in your project: `npm install vite@^6.0.0 || vite@^7.0.0 || vite@^8.0.0` or `yarn add vite@^6.0.0 || vite@^7.0.0 || vite@^8.0.0`.

Install

• npm install vitest npm
• yarn add vitest yarn
• pnpm add vitest pnpm

Imports

• test

  import { test } from 'vitest'

  Vitest primarily uses ESM, aligning with modern Node.js environments.
• expect

  import { expect } from 'vitest'

• vi

  import { vi } from 'vitest'

Quickstart

This example demonstrates a basic Vitest test file, importing `test` and `expect` to define and assert a simple function. It's designed to be runnable by executing `npx vitest` in your project's terminal.

import { test, expect } from 'vitest';

function add(a: number, b: number): number {
  return a + b;
}

test('adds two numbers', () => {
  expect(add(1, 2)).toBe(3);
});

// To run: npx vitest