configuring-vitest-4

name	configuring-vitest-4
description	Configure Vitest 4.x with correct pool architecture, coverage settings, and multi-project setup. Use when creating or modifying vitest.config files or setting up test infrastructure. Use when this capability is needed.
metadata	{"author":"djankies"}

Configuring Vitest 4

This skill teaches correct Vitest 4.x configuration patterns, focusing on the breaking changes introduced in version 4.0.

Core Concepts

Vitest 4.0 introduced major configuration changes:

1. Pool Architecture: Consolidated pool configuration with maxWorkers
2. Coverage: Requires explicit include patterns
3. Multi-Project: Uses projects array instead of workspace
4. Dependencies: Moved under server.deps namespace

Quick Reference

Worker Configuration

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    pool: 'forks',
    maxWorkers: 4,
    isolate: true,
    fileParallelism: true,
  },
});

Key changes from Vitest 3.x:

• maxThreads → maxWorkers
• maxForks → maxWorkers
• singleThread: true → maxWorkers: 1, isolate: false

For detailed pool configuration options, see references/pool-configuration.md

Coverage Configuration

export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',
      reporter: ['text', 'html'],
      include: ['src/**/*.{ts,tsx}'],
    },
  },
});

Required: Coverage now requires explicit include patterns.

For detailed coverage configuration, see references/coverage-configuration.md

For testing Zod schema coverage, use the testing-zod-schemas skill for patterns on validation logic testing, ensuring 100% branch coverage.

Multi-Project Setup

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: 'unit',
          include: ['tests/unit/**/*.test.ts'],
          environment: 'node',
        },
      },
      {
        test: {
          name: 'integration',
          include: ['tests/integration/**/*.test.ts'],
          testTimeout: 30000,
        },
      },
    ],
  },
});

Key change: defineWorkspace replaced by projects in defineConfig

For detailed multi-project configuration, see references/multi-project-setup.md

For testing Next.js server actions with Vitest, use the securing-server-actions skill for patterns on authentication, validation, and security testing.

Browser Mode

import { playwright } from '@vitest/browser-playwright';

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: playwright(),
      instances: [{ browser: 'chromium' }],
    },
  },
});

Key changes:

• Separate provider package required
• browser.name → browser.instances array
• Provider must be function call

For detailed browser mode configuration, see references/browser-mode-config.md

Dependency Configuration

export default defineConfig({
  test: {
    server: {
      deps: {
        inline: ['vue', 'lodash-es'],
        external: ['aws-sdk'],
      },
    },
  },
});

Key change: deps.* moved to server.deps.*

Environment Configuration

Node Environment (Default)

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

DOM Environments

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

Or use happy-dom for better performance:

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

For configuring Vitest to test React components, use the testing-components skill for setup patterns and testing @testing-library/react with React 19 components.

Common Patterns

Basic Unit Testing

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    include: ['src/**/*.test.ts'],
    coverage: {
      provider: 'v8',
      include: ['src/**/*.ts'],
    },
  },
});

React Component Testing

import react from '@vitejs/plugin-react';

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

Multi-Environment Testing

Use projects for different test types:

export default defineConfig({
  test: {
    projects: [
      { test: { name: 'unit', environment: 'node' } },
      { test: { name: 'component', environment: 'jsdom' } },
      { test: { name: 'browser', browser: { enabled: true } } },
    ],
  },
});

For complete configuration examples, see references/complete-examples.md

Validation

After creating config, verify with:

vitest --run

Check for deprecation warnings in output. If warnings appear, consult migration guide.

Deprecated Options Summary

Never use these (removed in Vitest 4.0):

Pool Options

• maxThreads → Use maxWorkers
• maxForks → Use maxWorkers
• singleThread → Use maxWorkers: 1, isolate: false
• poolOptions → Flatten to top-level

Coverage Options

• coverage.ignoreEmptyLines → No longer needed
• coverage.all → Use explicit include
• coverage.extensions → Use explicit include

Workspace Options

• defineWorkspace → Use defineConfig with projects
• poolMatchGlobs → Use projects with include
• environmentMatchGlobs → Use projects with environment

Dependency Options

• deps.inline → Use server.deps.inline
• deps.external → Use server.deps.external

Browser Options

• browser.name → Use browser.instances
• browser.testerScripts → Use browser.testerHtmlPath

Common Mistakes

1. Missing coverage.include: Coverage requires explicit include patterns in 4.x
2. Using removed pool options: maxThreads, singleThread no longer exist
3. Using defineWorkspace: Replaced by projects in defineConfig
4. Wrong browser provider import: Must import from provider package
5. Nested poolOptions: Flatten to top-level configuration

Performance Optimization

Fast Unit Tests

export default defineConfig({
  test: {
    pool: 'threads',
    isolate: false,
    fileParallelism: true,
    maxWorkers: 4,
  },
});

Fast Browser Tests

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: playwright(),
      instances: [{ browser: 'chromium' }],
      headless: true,
      fileParallelism: true,
    },
  },
});

References

For detailed configuration documentation:

• Pool Configuration - Worker management and pool options
• Coverage Configuration - V8/Istanbul coverage setup
• Multi-Project Setup - Projects array configuration
• Browser Mode Config - Playwright/WebDriverIO setup
• Complete Examples - Full configuration templates

For migration from Vitest 3.x, see @vitest-4/skills/migrating-to-vitest-4

For browser mode setup, see @vitest-4/skills/using-browser-mode

For complete API reference, see @vitest-4/knowledge/vitest-4-comprehensive.md

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.