{ ILoveJS }

Vitest

Testing

A Vite-native testing framework

weekly downloads31.1M
versionv4.0.18
licenseMIT
↗ official docs↗ github
Jest-compatible APIVite config sharingBrowser mode

Overview

Vitest is a modern unit testing framework designed specifically for Vite-powered projects, though it works excellently with any JavaScript or TypeScript codebase. Created by the Vite team, it leverages Vite's transformation pipeline and ESM-first architecture to deliver exceptionally fast test execution with near-instant Hot Module Replacement during watch mode. With over 31 million weekly downloads, Vitest has rapidly become a popular choice for developers seeking a testing solution that matches the speed and developer experience of modern build tools.

The framework positions itself as a spiritual successor to Jest, offering a familiar API surface while solving many pain points of traditional test runners. Vitest natively supports ESM, TypeScript, and JSX without configuration overhead, and it automatically inherits your existing Vite config—eliminating the need to maintain separate transformation setups for testing. This unified configuration model is particularly valuable for developers tired of wrestling with Babel, webpack loaders, or other transpilation layers just to run tests.

Vitest ships with everything needed for comprehensive testing: built-in assertion libraries (Chai), mocking utilities (Tinyspy), coverage reporting, snapshot testing, and even component testing for frontend frameworks. It supports multiple test environments including Node, jsdom, and happy-dom, making it suitable for both pure logic testing and DOM-dependent code. The framework's architecture enables advanced features like test sharding for CI parallelization, workspace support for monorepos, and even in-browser testing for component validation.

Developers migrating from Jest will find the transition straightforward due to Vitest's compatible APIs, while those starting fresh benefit from superior performance and a configuration-free experience when using Vite. The project is particularly popular in the Vue, React, and Svelte ecosystems where Vite adoption is high, but its standalone capabilities make it viable for any JavaScript testing scenario.

Quick Start

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

export async function fetchUser(id: string) {
  const response = await fetch(`https://api.example.com/users/${id}`);
  return response.json();
}

// sum.test.ts
import { describe, it, expect, vi } from 'vitest';
import { sum, fetchUser } from './sum';

describe('sum', () => {
  it('adds two numbers correctly', () => {
    expect(sum(2, 3)).toBe(5);
    expect(sum(-1, 1)).toBe(0);
  });

  it('handles floating point numbers', () => {
    expect(sum(0.1, 0.2)).toBeCloseTo(0.3);
  });
});

describe('fetchUser', () => {
  it('fetches user data from API', async () => {
    const mockUser = { id: '123', name: 'Alice' };
    
    global.fetch = vi.fn(() =>
      Promise.resolve({
        json: () => Promise.resolve(mockUser),
      } as Response)
    );

    const user = await fetchUser('123');
    
    expect(fetch).toHaveBeenCalledWith('https://api.example.com/users/123');
    expect(user).toEqual(mockUser);
  });
});

// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    coverage: {
      provider: 'v8',
      reporter: ['text', 'html'],
    },
  },
});

// package.json scripts:
// "test": "vitest"
// "test:ui": "vitest --ui"
// "test:coverage": "vitest --coverage"

Use Cases

Unit testing Vite-based applications: Vitest automatically uses your existing Vite configuration, making it the natural choice for testing Vue 3, React with Vite, or Svelte projects without duplicating transformation logic. Tests run with the same module resolution, path aliases, and plugins as your production code.

Migrating from Jest with minimal refactoring: Teams looking to modernize their test infrastructure can switch to Vitest while keeping most test code unchanged, as it implements Jest-compatible APIs including describe, it, expect, mock functions, and snapshot testing. The primary changes involve updating imports and configuration files.

Component testing in real browsers: Vitest's browser mode allows running tests in actual browser environments (Chromium, Firefox, WebKit) rather than simulated DOMs, ensuring components behave correctly with real browser APIs, CSS rendering, and user interactions. This is valuable for testing complex UI components with third-party libraries.

Monorepo testing with workspace support: Large codebases with multiple packages can define separate Vitest configurations per workspace while sharing common setup, enabling isolated test environments with different dependencies, environments (Node vs. jsdom), or coverage thresholds per package.

Performance-critical test suites with watch mode: Development teams practicing TDD benefit from Vitest's smart watch mode that only re-runs affected tests when code changes, providing sub-second feedback loops. The instant restart capability eliminates the 5-15 second startup overhead common in Jest for large projects.

Pros & Cons

Pros

  • +Extremely fast test execution and watch mode with instant HMR, especially for Vite projects where configuration is shared and no separate transpilation is needed
  • +Native ESM, TypeScript, and JSX support without configuration, eliminating complex Babel or ts-jest setup required by traditional frameworks
  • +Jest-compatible API makes migration straightforward while offering modern features like concurrent tests, benchmarking, and type testing
  • +Built-in component testing for major frameworks and browser mode for testing with actual browser APIs rather than limited DOM simulation
  • +Excellent developer experience with smart filtering, concurrent execution, UI mode for debugging, and detailed error reporting with code frames

Cons

  • −Ecosystem maturity is lower than Jest—some community plugins, custom reporters, and integrations may not exist or require adaptation
  • −Projects not using Vite lose the main performance advantage and may need additional configuration that Jest handles more automatically
  • −Breaking changes between major versions have been more frequent than established frameworks as Vitest is still maturing (currently version 4.x)
  • −Browser mode and some advanced features are still experimental, with documentation gaps and potential stability issues in complex scenarios
  • −Global APIs (describe, it, expect) require explicit imports by default or configuring globals: true, which differs from Jest's behavior and can confuse migrating teams

Comparisons

vitest vs jesttesting →vitest vs cypresstesting →vitest vs happy-domtesting →

Install

bash
npm install vitest
bash
pnpm add vitest
bash
bun add vitest
↗ View full npm package details