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