Vitest

Vitest

Overview

Vitest is a blazing-fast unit test framework powered by Vite. This skill provides complete Vitest documentation, APIs, configuration options, and migration guides to enable flawless test development in any JavaScript or TypeScript project.

Key capabilities:

• Vite-native for instant feedback and HMR
• Jest-compatible API for easy migration
• Works in Vite and non-Vite projects
• Built-in TypeScript, JSX, and ESM support
• Native code coverage (V8 and Istanbul)
• Browser mode for component testing
• Workspace support for monorepos

Quick Start Decision Tree

Is this a new project or adding tests to an existing project?

• New project: Start with "Installation & Setup"
• Existing project: Check framework type below

What type of project is it?

• Vite/Vue/React/Svelte: Use Vite integration (see "Vite Project Setup")
• Non-Vite (Next.js, Angular, vanilla): Use standalone mode (see "Standalone Project Setup")
• Monorepo: Use workspace configuration (see "Workspace Setup")

Are you migrating from Jest?

• Yes: See "Migration from Jest" section

Installation & Setup

Basic Installation

# Install Vitest
npm install -D vitest

# Add test script to package.json
{
  "scripts": {
    "test": "vitest",
    "test:ui": "vitest --ui"
  }
}

Vite Project Setup

For projects already using Vite, extend the existing vite.config.ts:

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    // test options
  },
  // your existing Vite config
})

Vitest automatically shares your Vite config, plugins, and transformations.

Standalone Project Setup

For non-Vite projects, create vitest.config.ts:

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    include: ['**/*.{test,spec}.{js,ts}'],
    environment: 'node' // or 'jsdom' for browser environment
  }
})

Framework-specific setup guides:

• Next.js: See references/guide/index.md for configuration
• Angular: Use environment: 'jsdom' with appropriate transformers
• React/Vue/Svelte: Extend Vite config for best experience

TypeScript Setup

Vitest supports TypeScript out of the box. Ensure tsconfig.json includes test files:

{
  "include": ["src/**/*", "**/*.test.ts"]
}

Writing Tests

Basic Test Structure

// math.test.ts
import { describe, it, expect } from 'vitest'
import { add } from './math'

describe('add', () => {
  it('should add two numbers', () => {
    expect(add(1, 2)).toBe(3)
  })

  it('should handle negative numbers', () => {
    expect(add(-1, -2)).toBe(-3)
  })
})

Test Organization

• Use describe blocks to group related tests
• Name test files with .test.ts or .spec.ts suffix
• Co-locate tests with source code or in __tests__ directories
• Use test context for sharing data between tests (see references/guide/test-context.md)

Lifecycle Hooks

import { beforeAll, beforeEach, afterAll, afterEach } from 'vitest'

describe('database tests', () => {
  beforeAll(async () => {
    // Runs once before all tests
    await connectDatabase()
  })

  beforeEach(async () => {
    // Runs before each test
    await clearDatabase()
  })

  afterEach(async () => {
    // Runs after each test
    await cleanup()
  })

  afterAll(async () => {
    // Runs once after all tests
    await disconnectDatabase()
  })
})

For complete lifecycle reference, see references/api/hooks.md.

Running Tests

# Run all tests once
vitest run

# Watch mode (default)
vitest

# Run matching pattern
vitest --testNamePattern="should add"

# UI mode
vitest --ui

# Coverage
vitest --coverage

See references/guide/cli.md for complete CLI reference.

Mocking

Vitest provides comprehensive mocking capabilities through the vi utility.

Function Mocking

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

const mockFn = vi.fn()
mockFn('hello')
expect(mockFn).toHaveBeenCalledWith('hello')

// With return value
const mocked = vi.fn().mockReturnValue('test')
expect(mocked()).toBe('test')

// With implementation
const callback = vi.fn((x) => x + 1)
expect(callback(1)).toBe(2)

Module Mocking

import { vi, expect, it } from 'vitest'
import { fetchData } from './api'

// Mock entire module
vi.mock('./api', () => ({
  fetchData: vi.fn(() => Promise.resolve('mocked data'))
}))

it('uses mocked API', async () => {
  const data = await fetchData()
  expect(data).toBe('mocked data')
})

Timer Mocking

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

beforeEach(() => {
  vi.useFakeTimers()
})

it('calls callback after timeout', () => {
  const callback = vi.fn()
  setTimeout(callback, 1000)

  vi.advanceTimersByTime(1000)
  expect(callback).toHaveBeenCalled()
})

Complete mocking reference:

• Functions: references/guide/mocking/functions.md
• Modules: references/guide/mocking/modules.md
• Timers: references/guide/mocking/timers.md
• Globals: references/guide/mocking/globals.md
• Dates: references/guide/mocking/dates.md

Configuration Patterns

Common Configuration Scenarios

1. Browser Environment (React/Vue/Svelte)

import { defineConfig } from 'vitest/config'

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

2. Code Coverage

export default defineConfig({
  test: {
    coverage: {
      provider: 'v8', // or 'istanbul'
      include: ['src/**/*.{js,ts}'],
      exclude: ['src/**/*.test.{js,ts}', 'src/**/*.config.{js,ts}']
    }
  }
})

3. Monorepo/Workspace

export default defineConfig({
  test: {
    workspace: [
      'packages/*',
      'apps/*'
    ]
  }
})

4. Browser Mode (Component Testing)

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright', // or 'webdriverio'
      headless: true
    }
  }
})

See references/config/INDEX.md for complete configuration reference.

Advanced Features

Snapshot Testing

import { expect, it } from 'vitest'

it('matches snapshot', () => {
  const data = { foo: 'bar' }
  expect(data).toMatchSnapshot()
})

See references/guide/snapshot.md for complete snapshot guide.

In-Source Testing

Write tests directly next to code:

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

// @ts-ignore
if (import.meta.vitest) {
  const { it, expect } = import.meta.vitest
  it('adds numbers', () => {
    expect(add(1, 2)).toBe(3)
  })
}

See references/guide/in-source.md for configuration.

Test Tags

Organize and filter tests by tags:

import { test } from 'vitest'

test('slow integration test', { tags: ['@slow', '@integration'] }, () => {
  // test code
})

// Run only fast tests
// vitest --tags @fast

See references/guide/test-tags.md for usage.

Browser Testing

Test components in real browser:

import { expect, test } from 'vitest'
import { render } from '@testing-library/vue'

test('renders button', async () => {
  const { getByText } = render(Button, {
    props: { label: 'Click me' }
  })

  expect(getByText('Click me')).toBeTruthy()
})

See references/guide/browser/ for complete browser testing guide.

Migration

From Jest to Vitest

Vitest is largely compatible with Jest. The migration process:

1. Install Vitest: npm install -D vitest
2. Update configuration: Replace jest.config.js with vitest.config.ts
3. Update scripts: Change test script to use vitest
4. Update imports: Replace @jest/globals with vitest
5. Verify mocks: Most Jest mocks work unchanged

Key differences:

• Auto-mocked modules: Vitest doesn't auto-mock by default
• Timer mocks: Use vi.useFakeTimers() instead of jest.useFakeTimers()
• Environment variables: Use process.env directly

See references/guide/comparisons.md for detailed Jest comparison.

From Older Vitest Versions

Migrating to Vitest 4.0:

• Coverage provider changes: V8 now uses AST-based remapping
• Removed coverage.all and coverage.extensions - use coverage.include instead
• Coverage ignore hints updated - see references/guide/migration.md

See migration guides:

• Vitest 4.0: references/guide/migration.md#vitest-4
• Vitest 3.0: references/vitest-3.md
• Vitest 3.2: references/vitest-3-2.md

Troubleshooting

Common Issues

Tests run in wrong environment:

// vitest.config.ts
export default defineConfig({
  test: {
    environment: 'jsdom' // for browser tests
    // or 'node' for server tests
  }
})

Modules not transforming:

• Check transformMode configuration
• Ensure dependencies are in deps.interopDefault

Timeouts:

• Increase timeout: test({ timeout: 10000 }, () => { ... })
• Or globally: test: { timeout: 10000 }

Watch mode not detecting changes:

• Check file inclusion patterns
• Verify include and exclude in config

See references/guide/common-errors.md for more troubleshooting.

Resources

This skill includes comprehensive Vitest documentation organized for progressive disclosure:

Documentation Indices

• Main INDEX - Complete documentation navigation
• Guide INDEX - Usage guides by topic
• API INDEX - Complete API reference
• Config INDEX - All configuration options

Key Documentation

Getting Started:

• Getting Started Guide - Installation and first test
• Features - Vitest capabilities overview
• CLI Reference - Command-line options

Core Concepts:

• Lifecycle - Test hooks and setup/teardown
• Test Context - Sharing data between tests
• Filtering - Running specific tests

Mocking:

• Mocking Overview - Mocking guide
• vi API - Mocking utilities
• mock API - Mock functions

API Reference:

• test - Test definition
• expect - Assertions and matchers
• describe - Test suites
• hooks - Lifecycle hooks

Configuration:

• Config Reference - All options
• Coverage - Coverage setup
• Browser Mode - Browser testing config

Migration:

• Migration Guide - Version migration
• Jest Comparison - Jest to Vitest
• Vitest 4.0 - Latest release notes

Advanced:

• Browser Testing - Component testing guide
• Workspace - Monorepo setup
• Performance - Optimization

When working with Vitest, consult the appropriate reference file based on your task. Start with the guide for conceptual understanding, then refer to API/config references for specific implementation details.