---

name: vitest-configuration description: Vitest setup and best practices. Use when configuring Vitest for TypeScript projects.

Vitest Configuration Skill

This skill covers Vitest configuration for TypeScript projects.

When to Use

Use this skill when:

• Setting up testing infrastructure
• Configuring coverage thresholds
• Setting up test environments
• Migrating from Jest to Vitest

Core Principle

FAST, NATIVE ESM TESTING - Vitest provides Jest-compatible API with native ESM support and Vite-powered performance.

Installation

Copynpm install -D vitest @vitest/coverage-v8

Basic Configuration

vitest.config.ts

Copyimport { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    include: ['src/**/__tests__/**/*.test.{ts,tsx}'],
    exclude: ['node_modules', 'dist'],
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      exclude: [
        'node_modules/',
        'dist/',
        '**/*.test.ts',
        '**/__tests__/**',
        '**/*.d.ts',
      ],
      thresholds: {
        lines: 80,
        functions: 80,
        branches: 80,
        statements: 80,
      },
    },
    typecheck: {
      enabled: true,
      tsconfig: './tsconfig.json',
    },
  },
});

Package.json Scripts

Copy{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage",
    "test:ui": "vitest --ui"
  }
}

Test Environments

Node Environment (Default)

Copyexport default defineConfig({
  test: {
    environment: 'node',
  },
});

JSDOM Environment (For DOM Testing)

Copynpm install -D jsdom

Copyexport default defineConfig({
  test: {
    environment: 'jsdom',
  },
});

Happy-DOM Environment (Faster Alternative)

Copynpm install -D happy-dom

Copyexport default defineConfig({
  test: {
    environment: 'happy-dom',
  },
});

Per-File Environment

Copy// In test file header
// @vitest-environment jsdom

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

Global Setup and Teardown

Setup Files

Copy// vitest.config.ts
export default defineConfig({
  test: {
    setupFiles: ['./src/test/setup.ts'],
    globalSetup: ['./src/test/global-setup.ts'],
  },
});

Copy// src/test/setup.ts
import { beforeAll, afterAll, afterEach } from 'vitest';

beforeAll(() => {
  // Runs once before all tests
});

afterEach(() => {
  // Runs after each test
});

afterAll(() => {
  // Runs once after all tests
});

Copy// src/test/global-setup.ts
export default async function setup() {
  // Global setup (runs before all test files)
  console.log('Starting test suite');
}

export async function teardown() {
  // Global teardown (runs after all test files)
  console.log('Test suite complete');
}

Coverage Configuration

Comprehensive Coverage Setup

Copyexport default defineConfig({
  test: {
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html', 'lcov'],
      reportsDirectory: './coverage',
      exclude: [
        'node_modules/',
        'dist/',
        '**/*.test.ts',
        '**/*.test.tsx',
        '**/__tests__/**',
        '**/__mocks__/**',
        '**/*.d.ts',
        '**/types/**',
        '**/index.ts', // Re-export files
      ],
      thresholds: {
        lines: 80,
        functions: 80,
        branches: 80,
        statements: 80,
      },
      // Fail if coverage drops
      thresholds: {
        '100': true, // Enforce 100% on new code
      },
    },
  },
});

TypeScript Integration

Type Checking in Tests

Copyexport default defineConfig({
  test: {
    typecheck: {
      enabled: true,
      tsconfig: './tsconfig.json',
      include: ['**/*.test.ts', '**/*.test.tsx'],
    },
  },
});

tsconfig.json for Tests

Copy{
  "compilerOptions": {
    "types": ["vitest/globals"]
  },
  "include": ["src/**/*", "src/**/__tests__/**/*"]
}

Path Aliases

Copyimport { defineConfig } from 'vitest/config';
import path from 'node:path';

export default defineConfig({
  test: {
    alias: {
      '@': path.resolve(__dirname, './src'),
      '@test': path.resolve(__dirname, './src/test'),
    },
  },
});

Parallel Execution

Copyexport default defineConfig({
  test: {
    // Run tests in parallel (default)
    pool: 'threads',
    poolOptions: {
      threads: {
        singleThread: false,
        maxThreads: 4,
        minThreads: 1,
      },
    },
    // Or run tests sequentially
    // sequence: {
    //   concurrent: false,
    // },
  },
});

Test Filtering

By Pattern

Copy# Run tests matching pattern
vitest run --grep="user"

# Run specific file
vitest run src/utils/__tests__/format.test.ts

By Annotation

Copyimport { describe, it, expect } from 'vitest';

describe('feature', () => {
  it.skip('skipped test', () => {
    // This test is skipped
  });

  it.only('only this test runs', () => {
    // Only this test runs when using .only
  });

  it.todo('not yet implemented');
});

Snapshot Testing

Copyimport { describe, it, expect } from 'vitest';

describe('snapshots', () => {
  it('should match snapshot', () => {
    const result = { id: 1, name: 'test' };
    expect(result).toMatchSnapshot();
  });

  it('should match inline snapshot', () => {
    const result = { id: 1, name: 'test' };
    expect(result).toMatchInlineSnapshot(`
      {
        "id": 1,
        "name": "test",
      }
    `);
  });
});

Snapshot Configuration

Copyexport default defineConfig({
  test: {
    snapshotFormat: {
      printBasicPrototype: false,
    },
  },
});

Mocking Configuration

Auto-Mocking

Copyexport default defineConfig({
  test: {
    mockReset: true, // Reset mocks before each test
    clearMocks: true, // Clear mock calls before each test
    restoreMocks: true, // Restore original implementations
  },
});

Module Mocking Directory

Copyexport default defineConfig({
  test: {
    deps: {
      interopDefault: true,
    },
  },
});

Reporter Configuration

Copyexport default defineConfig({
  test: {
    reporters: ['default', 'json', 'html'],
    outputFile: {
      json: './test-results/results.json',
      html: './test-results/results.html',
    },
  },
});

Watch Mode Configuration

Copyexport default defineConfig({
  test: {
    watch: true,
    watchExclude: ['**/node_modules/**', '**/dist/**'],
    forceRerunTriggers: ['**/vitest.config.ts', '**/vite.config.ts'],
  },
});

CI Configuration

Copyexport default defineConfig({
  test: {
    // CI-specific settings
    ...(process.env.CI
      ? {
          minWorkers: 1,
          maxWorkers: 2,
          coverage: {
            reporter: ['text', 'json', 'lcov'],
          },
        }
      : {}),
  },
});

Vitest UI

Copynpm install -D @vitest/ui

Copyvitest --ui

Opens interactive UI at http://localhost:51204/__vitest__/

Migration from Jest

Configuration Mapping

Import Changes

Copy// Jest
import { jest } from '@jest/globals';

// Vitest
import { vi } from 'vitest';

// Jest mock
jest.fn();
jest.mock('./module');

// Vitest mock
vi.fn();
vi.mock('./module');

Best Practices Summary

1. Use TypeScript for configuration
2. Set coverage thresholds to 80%+
3. Enable type checking in tests
4. Use appropriate test environment
5. Configure parallel execution
6. Use setup files for common setup
7. Configure reporters for CI

Code Review Checklist

• vitest.config.ts uses TypeScript
• Coverage thresholds set (80%+)
• Type checking enabled
• Correct environment selected
• Setup files configured if needed
• Snapshot format configured
• CI-specific settings applied