Vitest Guide

The complete reference for Vitest — the blazing-fast, Vite-native test runner with a Jest-compatible API. Covers setup, mocking, coverage, HMR watch mode, and in-source testing.

What is Vitest?

Vitest is a next-generation JavaScript testing framework built on top of Vite. Created by the Vite core team, it solves a fundamental problem: test tooling and build tooling used to be completely separate pipelines with different configuration, different module resolution, and different transform stacks. Vitest unifies them — your vite.config.ts is automatically reused by the test runner, including plugins, path aliases, and environment variables.

The result is dramatically faster test startup and a more consistent development experience. Vitest uses esbuild to transform TypeScript and JSX (the same as Vite's dev server), achieving sub-100ms cold starts on most projects. Its Jest-compatible API means most test suites can be migrated with minimal changes, making adoption low-risk.

Installation & Configuration

# Install Vitest
npm install --save-dev vitest

# Install coverage provider
npm install --save-dev @vitest/coverage-v8

# vitest.config.ts (or extend vite.config.ts)
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'jsdom',      // or 'node', 'happy-dom'
    globals: true,             // use describe/it without imports
    setupFiles: ['./tests/setup.ts'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'html'],
      thresholds: { lines: 80, branches: 70 },
    },
  },
});

Basic Test Syntax (Jest-compatible)

// With globals: true — no imports needed
describe('formatCurrency()', () => {
  it('formats USD correctly', () => {
    expect(formatCurrency(1234.5, 'USD')).toBe('$1,234.50');
  });

  it('handles zero', () => {
    expect(formatCurrency(0, 'EUR')).toBe('€0.00');
  });
});

// Without globals (explicit imports)
import { describe, it, expect, vi } from 'vitest';
import { fetchUser } from './api';

describe('fetchUser()', () => {
  it('returns user object', async () => {
    const user = await fetchUser(1);
    expect(user).toMatchObject({ id: 1, name: expect.any(String) });
  });
});

Mocking with vi (the Jest-equivalent)

import { vi, describe, it, expect, beforeEach } from 'vitest';

// Mock a module
vi.mock('./emailService', () => ({
  sendEmail: vi.fn().mockResolvedValue({ success: true }),
}));

// Spy on a method
const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});

// Mock timers
vi.useFakeTimers();

describe('RetryService', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it('retries 3 times before failing', async () => {
    const mockFn = vi.fn()
      .mockRejectedValueOnce(new Error('fail'))
      .mockRejectedValueOnce(new Error('fail'))
      .mockResolvedValueOnce('success');

    const result = await retryWithBackoff(mockFn);
    expect(result).toBe('success');
    expect(mockFn).toHaveBeenCalledTimes(3);
  });
});

In-Source Testing

Vitest's unique in-source testing feature lets you colocate tests with your implementation code. The import.meta.vitest block is stripped from production builds automatically.

// utils/clamp.ts
export function clamp(value: number, min: number, max: number): number {
  return Math.min(Math.max(value, min), max);
}

// In-source tests — stripped in production builds
if (import.meta.vitest) {
  const { it, expect } = import.meta.vitest;

  it('clamps values within range', () => {
    expect(clamp(5, 0, 10)).toBe(5);
    expect(clamp(-5, 0, 10)).toBe(0);
    expect(clamp(15, 0, 10)).toBe(10);
  });
}

Running Coverage

# Run tests with coverage
npx vitest run --coverage

# Watch mode (re-runs affected tests on change)
npx vitest

# UI mode (browser-based test explorer)
npx vitest --ui

Key Features

• Vite-native — reuses your vite.config.ts, plugins, path aliases, and env vars
• HMR watch mode — only re-runs tests affected by changed modules
• Native ESM — full ESM support without experimental flags or Babel transforms
• Concurrent test files — runs files in parallel worker threads by default
• UI mode — browser-based test explorer with pass/fail visualization
• Snapshot testing — fully compatible with Jest snapshot format
• TypeScript first — no separate ts-jest configuration needed

Comparison: Vitest vs Alternatives

Pros & Cons