name: vitest description: "Vitest testing framework: Vite-powered tests, Jest-compatible API, mocking, snapshots, coverage, browser mode, and TypeScript support. Use when writing or configuring tests with Vitest, setting up mocking/snapshots, configuring coverage, or running browser-mode tests. Keywords: Vitest, testing, Vite, Jest, mocking, coverage." metadata: version: "5.0.5" release_date: "2026-10-15"

Vitest

Next generation testing framework powered by Vite.

Quick Navigation

• Test API - test, describe, hooks
• Expect API - matchers and assertions
• Mocking - vi.fn, vi.mock, fake timers
• Configuration - vitest.config.ts options
• CLI - command line reference
• Browser Mode - real browser testing

When to Use

• Testing Vite-based applications (shared config)
• Need Jest-compatible API with native ESM support
• Component testing in real browser
• Fast watch mode with HMR
• TypeScript testing without extra config
• Parallel test execution

Installation

Install: npm install -D vitest. Requires Node.js >=22 and Vite >=6.4 in v5.

Release Highlights (5.0.0)

• Requirements: Node.js >=22 and Vite >=6.4 are required. @vitest/runner is inlined (the package is no longer published) and expect is inlined, so old entry points were removed.
• Mock/timer behavior: mocks are cleared by default before each test, and Temporal can now be mocked (with or without fake timers).
• Replaced APIs: sequential test/suite options are removed in favor of concurrent; the webdriverio browser provider is removed; toHaveTextContent is strict with toMatchTextContent as the alternative; expect.poll fails when the function does not resolve in time.
• New defaults/outputs: attachmentsDir defaults to .vitest/attachments/ (was .vitest-attachments/), and blob/json/junit/html reporter outputs default to .vitest; a createReport API and .vitest report directory convention are introduced.
• Projects: inline projects extend the root config by default, nested projects are supported, distinct projects share one Vite server, and the config file is no longer looked up from ancestor directories (parent dirs no longer apply).
• Browser: locator objects replace locator strings, locators.exact is on by default, and a screenshotDirectory config controls toMatchScreenshot output.
• Misc: benchmark public API was rewritten with a pluggable provider API; -p is a shorthand for --project; -t uses > as separator; coverage thresholds.perFile accepts an object and TypeScript build mode / vitest list static parsing are supported.

Patch Notes (5.0.1 -> 5.0.5)

• 5.0.2 to 5.0.5 are fixes only — the 5.0 API surface is unchanged.
• The root temp directory is removed when the run closes, and --changed handles quoted file names.
• import.meta.hot stubs expose data, skipIf sets skip and ignores undefined options, and the native loader keeps the import frame inside its errors.
• Browser mode: late connections of closed sessions are dropped, global setup runs once with instances, the browser waits up to 30s to close, and synthetic pagehide events are ignored.
• Hook cleanups run even when a later hook fails, mocks of finished test files are released, and all running tests are aborted on cancel.
• The reporter reports end reason failed when a worker crashes.

Release Highlights (4.1.0 -> 4.1.6)

• New control-flow hooks: aroundEach and aroundAll.
• Test metadata expands with tags, meta, and improved test.extend type inference.
• CLI adds --detect-async-leaks, richer --update modes, and static collection for vitest list.
• Browser mode grows Playwright persistent contexts, userEvent.wheel, and stronger trace/artifact handling.
• Mocking/timers add disposable doMock(), mockThrow / mockThrowOnce, and setTickMode.
• 4.1.4 adds experimental ARIA snapshots, filterMeta for the JSON reporter, and exposes assertion as a public experimental field.
• 4.1.5 adds coverage instrumenter support and improves reporter/UI behavior around large snapshots and HTML output.
• 4.1.6 tightens browser screenshot path resolution and fixes sequence.concurrent handling for concurrent test scheduling.

Quick Start

// sum.js
export function sum(a, b) {
  return a + b;
}

// sum.test.js
import { expect, test } from "vitest";
import { sum } from "./sum.js";
test("adds 1 + 2 to equal 3", () => {
  expect(sum(1, 2)).toBe(3);
});

// package.json
{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "coverage": "vitest run --coverage"
  }
}

Configuration

// vitest.config.ts (recommended)
import { defineConfig } from "vitest/config";
export default defineConfig({
  test: {
    globals: true, // Enable global test APIs
    environment: "jsdom", // Browser-like environment
    include: ["**/*.{test,spec}.{js,ts,jsx,tsx}"],
    coverage: {
      provider: "v8",
      reporter: ["text", "html"],
    },
  },
});

Or extend Vite config:

// vite.config.ts
/// <reference types="vitest/config" />
import { defineConfig } from "vite";
export default defineConfig({
  test: {
    // test options
  },
});

Test File Naming

By default, tests must contain .test. or .spec. in filename:

• sum.test.js
• sum.spec.ts
• __tests__/sum.js

Key Commands

# Watch mode (default)
vitest
 
# Single run
vitest run
 
# With coverage
vitest run --coverage
 
# Filter by file/test name
vitest sum
vitest -t "should add"
 
# UI mode
vitest --ui
 
# Browser tests
vitest --browser.enabled

Common Patterns

Basic Test

import { describe, it, expect, beforeEach } from "vitest";
describe("Calculator", () => {
  let calc: Calculator;
  beforeEach(() => {
    calc = new Calculator();
  });
  it("adds numbers", () => {
    expect(calc.add(1, 2)).toBe(3);
  });
  it("throws on invalid input", () => {
    expect(() => calc.add("a", 1)).toThrow();
  });
});

Mocking

import { vi, expect, test } from "vitest";
import { fetchUser } from "./api";
vi.mock("./api", () => ({
  fetchUser: vi.fn(),
}));
test("uses mocked API", async () => {
  vi.mocked(fetchUser).mockResolvedValue({ name: "John" });
  const user = await fetchUser(1);
  expect(fetchUser).toHaveBeenCalledWith(1);
  expect(user.name).toBe("John");
});

Snapshot Testing

import { expect, test } from "vitest";
test("matches snapshot", () => {
  const result = generateConfig();
  expect(result).toMatchSnapshot();
});
// Inline snapshot (auto-updates)
test("inline snapshot", () => {
  expect({ foo: "bar" }).toMatchInlineSnapshot();
});

Async Testing

import { expect, test } from "vitest";
test("async/await", async () => {
  const result = await fetchData();
  expect(result).toBeDefined();
});
test("resolves", async () => {
  await expect(Promise.resolve("ok")).resolves.toBe("ok");
});
test("rejects", async () => {
  await expect(Promise.reject(new Error())).rejects.toThrow();
});

Fake Timers

import { vi, expect, test, beforeEach, afterEach } from "vitest";
beforeEach(() => {
  vi.useFakeTimers();
});
afterEach(() => {
  vi.useRealTimers();
});
test("advances time", () => {
  const callback = vi.fn();
  setTimeout(callback, 1000);
  vi.advanceTimersByTime(1000);
  expect(callback).toHaveBeenCalled();
});

Jest Migration

Most Jest code works with minimal changes:

- import { jest } from '@jest/globals'
+ import { vi } from 'vitest'
 
- jest.fn()
+ vi.fn()
 
- jest.mock('./module')
+ vi.mock('./module')
 
- jest.useFakeTimers()
+ vi.useFakeTimers()

Key differences:

• Use vi instead of jest
• Globals not enabled by default (add globals: true)
• vi.mock is hoisted (use vi.doMock for non-hoisted)
• No jest.requireActual (use vi.importActual)

Environment Selection

// vitest.config.ts
{
  test: {
    environment: 'jsdom', // or 'happy-dom', 'node', 'edge-runtime'
  }
}
// Per-file (docblock at top)
/** @vitest-environment jsdom */

TypeScript

// tsconfig.json
{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

References

See references/ directory for detailed documentation on:

• Test API and hooks
• All expect matchers
• Mocking functions and modules
• Configuration options
• CLI commands
• Browser mode testing

Links

• Documentation
• API Reference
• GitHub
• VS Code Extension