configuring-vitest-4

Original：🇺🇸 English

Translated

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.

1installs

Sourcedjankies/claude-configs

Added on2026-02-16

NPX Install

npx skill4agent add djankies/claude-configs configuring-vitest-4

SKILL.md Content

View Translation Comparison →

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:

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

Quick Reference

Worker Configuration

typescript

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

typescript

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

typescript

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

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

typescript

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

typescript

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)

typescript

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

DOM Environments

typescript

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

Or use happy-dom for better performance:

typescript

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

typescript

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

React Component Testing

typescript

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:

typescript

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:

bash

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

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

Performance Optimization

Fast Unit Tests

typescript

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

Fast Browser Tests

typescript

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

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:

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

Quick Reference

Worker Configuration

typescript

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

typescript

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

typescript

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

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

typescript

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

typescript

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)

typescript

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

DOM Environments

typescript

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

Or use happy-dom for better performance:

typescript

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

typescript

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

React Component Testing

typescript

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:

typescript

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:

bash

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

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

Performance Optimization

Fast Unit Tests

typescript

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

Fast Browser Tests

typescript

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

configuring-vitest-4

NPX Install

Tags

SKILL.md Content

Configuring Vitest 4

Core Concepts

Quick Reference

Worker Configuration

Coverage Configuration

Multi-Project Setup

Browser Mode

Dependency Configuration

Environment Configuration

Node Environment (Default)

DOM Environments

Common Patterns

Basic Unit Testing

React Component Testing

Multi-Environment Testing

Validation

Deprecated Options Summary

Pool Options

Coverage Options

Workspace Options

Dependency Options

Browser Options

Common Mistakes

Performance Optimization

Fast Unit Tests

Fast Browser Tests

References

configuring-vitest-4

NPX Install

Tags

SKILL.md Content

Configuring Vitest 4

Core Concepts

Quick Reference

Worker Configuration

Coverage Configuration

Multi-Project Setup

Browser Mode

Dependency Configuration

Environment Configuration

Node Environment (Default)

DOM Environments

Common Patterns

Basic Unit Testing

React Component Testing

Multi-Environment Testing

Validation

Deprecated Options Summary

Pool Options

Coverage Options

Workspace Options

Dependency Options

Browser Options

Common Mistakes

Performance Optimization

Fast Unit Tests

Fast Browser Tests

References