Migrating to Vitest 4

This skill guides migration from Vitest 2.x/3.x to 4.x, focusing on breaking changes and deprecated patterns.

Migration Overview

Vitest 4.0 introduces breaking changes in:

1. Pool Architecture: Consolidated worker configuration
2. Coverage: Required explicit include patterns
3. Workspace: Replaced by projects array
4. Browser Mode: Separate provider packages
5. Dependencies: Moved to server namespace
6. Module Runner: New Vite-based implementation

Quick Migration Guide

Pool Configuration

Before (Vitest 3.x):

export default defineConfig({
  test: {
    maxThreads: 4,
    singleThread: true,
  },
});

After (Vitest 4.x):

export default defineConfig({
  test: {
    maxWorkers: 4,
    maxWorkers: 1,
    isolate: false,
  },
});

Coverage Configuration

Before (Vitest 3.x):

coverage: {
  provider: 'v8',
  all: true,
}

After (Vitest 4.x):

coverage: {
  provider: 'v8',
  include: ['src/**/*.{ts,tsx}'],
}

Workspace to Projects

Before (Vitest 3.x):

import { defineWorkspace } from 'vitest/config';

export default defineWorkspace([
  { test: { name: 'unit' } },
]);

After (Vitest 4.x):

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      { test: { name: 'unit' } },
    ],
  },
});

Browser Mode

Before (Vitest 3.x):

browser: {
  enabled: true,
  name: 'chromium',
  provider: 'playwright',
}

After (Vitest 4.x):

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

browser: {
  enabled: true,
  provider: playwright(),
  instances: [{ browser: 'chromium' }],
}

Import updates:

import { page } from 'vitest/browser';

Dependencies

Before (Vitest 3.x):

deps: {
  inline: ['vue'],
}

After (Vitest 4.x):

server: {
  deps: {
    inline: ['vue'],
  },
}

For detailed migration tables covering all options, see references/migration-tables.md

Migration Workflow

Step 1: Update Package

npm install -D vitest@latest

Step 2: Update Config

1. Replace maxThreads/maxForks with maxWorkers
2. Add coverage.include patterns
3. Replace defineWorkspace with projects
4. Move deps.* to server.deps.*
5. Update browser provider imports

Step 3: Update Test Files

grep -r "@vitest/browser/context" . --include="*.ts"

Replace with:

import { page, userEvent } from 'vitest/browser';

Step 4: Install Browser Providers

If using browser mode:

npm install -D @vitest/browser-playwright

Step 5: Run Tests

vitest --run

Check for deprecation warnings.

Step 6: Verify Coverage

vitest --coverage

For complete migration workflow with troubleshooting, see references/migration-workflow.md

Migration Checklist

Configuration

• Update vitest to 4.x
• Replace maxThreads/maxForks with maxWorkers
• Add explicit coverage.include patterns
• Replace defineWorkspace with projects
• Move deps.* to server.deps.*
• Update browser provider config

Test Files

• Update imports from @vitest/browser/context to vitest/browser
• Remove vitest/execute imports

Environment

• Replace VITE_NODE_DEPS_MODULE_DIRECTORIES with VITEST_MODULE_DIRECTORIES

Verification

• Run tests and verify no deprecation warnings
• Verify coverage reports generate correctly

Common Migration Issues

Issue: "maxThreads is not a valid option"

Solution: Replace with maxWorkers

Issue: Coverage Reports Empty

Solution: Add explicit coverage.include patterns

Issue: Workspace Config Not Working

Solution: Replace defineWorkspace with defineConfig and projects

Issue: Browser Tests Fail

Solution: Install provider package and update imports

Issue: "deps.inline is not a valid option"

Solution: Move to server.deps.inline

For detailed troubleshooting, see references/migration-workflow.md

Mock Implementation Changes

Mock Names

Returns vi.fn() instead of spy in Vitest 4.x

Invocation Order

Starts at 1 instead of 0 (matching Jest)

Restore Mocks

No longer affects automocks

Reporter Changes

Before (Vitest 3.x):

reporters: ['basic']

After (Vitest 4.x):

reporters: ['default'],
summary: false

Environment Variables

Before:

VITE_NODE_DEPS_MODULE_DIRECTORIES=/path vitest

After:

VITEST_MODULE_DIRECTORIES=/path vitest

Default Exclusions

Vitest 3.x: Excluded many directories by default

Vitest 4.x: Only excludes node_modules and .git

Add explicit excludes if needed:

coverage: {
  include: ['src/**/*.ts'],
  exclude: [
    '**/node_modules/**',
    '**/dist/**',
    '**/*.test.ts',
  ],
}

References

For detailed migration information:

• Migration Tables - Complete before/after comparisons
• Migration Workflow - Step-by-step process with troubleshooting

For new configuration patterns, see @vitest-4/skills/configuring-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