configuring-vitest-4

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configuring Vitest 4

配置Vitest 4

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

本技能将介绍正确的Vitest 4.x配置模式，重点关注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

Vitest 4.0引入了重大配置变更：

池架构：使用
```
maxWorkers
```
统一池配置
覆盖率：需要显式的
```
include
```
规则
多项目：使用
```
projects
```
数组替代工作区模式
依赖项：移至
```
server.deps
```
命名空间下

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

typescript

import { defineConfig } from 'vitest/config';

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

与Vitest 3.x的主要差异：

```
maxThreads
```
→
```
maxWorkers
```
```
maxForks
```
→
```
maxWorkers
```

singleThread: true

→

maxWorkers: 1, isolate: false

有关池配置的详细选项，请参阅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.

typescript

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

必填项： 4.x版本中覆盖率配置必须显式设置

include

规则。

有关覆盖率配置的详细内容，请参阅references/coverage-configuration.md

若要测试Zod Schema覆盖率，请使用testing-zod-schemas技能，学习验证逻辑测试的模式，确保100%分支覆盖率。

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.

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,
        },
      },
    ],
  },
});

主要差异：

defineWorkspace

被

defineConfig

中的

projects

替代

有关多项目配置的详细内容，请参阅references/multi-project-setup.md

若要使用Vitest测试Next.js Server Actions，请使用securing-server-actions技能，学习身份验证、验证和安全测试的模式。

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

typescript

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

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

主要差异：

需要单独的提供程序包
```
browser.name
```
→
```
browser.instances
```
数组
提供程序必须以函数调用形式传入

有关浏览器模式配置的详细内容，请参阅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.*

typescript

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

主要差异：

deps.*

移至

server.deps.*

下

Environment Configuration

环境配置

Node Environment (Default)

Node环境（默认）

typescript

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

typescript

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

DOM Environments

DOM环境

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.

typescript

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

或者使用happy-dom以获得更好的性能：

typescript

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

若要配置Vitest测试React组件，请使用testing-components技能，学习设置模式以及如何结合@testing-library/react测试React 19组件。

Common Patterns

常见模式

Basic Unit Testing

基础单元测试

typescript

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

typescript

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

React Component Testing

React组件测试

typescript

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

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

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

使用

projects

配置不同类型的测试：

typescript

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

有关完整的配置示例，请参阅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.

创建配置后，使用以下命令验证：

bash

vitest --run

检查输出中的弃用警告。如果出现警告，请查阅迁移指南。

Deprecated Options Summary

已弃用选项汇总

Never use these (removed in Vitest 4.0):

切勿使用以下选项（已在Vitest 4.0中移除）：

Pool Options

池选项

```
maxThreads
```
→ Use
```
maxWorkers
```
```
maxForks
```
→ Use
```
maxWorkers
```

singleThread

→ Use

maxWorkers: 1, isolate: false

```
poolOptions
```
→ Flatten to top-level

```
maxThreads
```
→ 使用
```
maxWorkers
```
```
maxForks
```
→ 使用
```
maxWorkers
```

singleThread

→ 使用

maxWorkers: 1, isolate: false

```
poolOptions
```
→ 扁平化至顶层配置

Coverage Options

覆盖率选项

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

```
coverage.ignoreEmptyLines
```
→ 不再需要
```
coverage.all
```
→ 使用显式的
```
include
```
```
coverage.extensions
```
→ 使用显式的
```
include
```

Workspace Options

工作区选项

```
defineWorkspace
```
→ Use
```
defineConfig
```
with
```
projects
```
```
poolMatchGlobs
```
→ Use
```
projects
```
with
```
include
```

environmentMatchGlobs

→ Use

projects

with

environment

```
defineWorkspace
```
→ 使用带有
```
projects
```
的
```
defineConfig
```
```
poolMatchGlobs
```
→ 使用带有
```
include
```
的
```
projects
```

environmentMatchGlobs

→ 使用带有

environment

的

projects

Dependency Options

依赖项选项

```
deps.inline
```
→ Use
```
server.deps.inline
```
```
deps.external
```
→ Use
```
server.deps.external
```

```
deps.inline
```
→ 使用
```
server.deps.inline
```
```
deps.external
```
→ 使用
```
server.deps.external
```

Browser Options

浏览器选项

```
browser.name
```
→ Use
```
browser.instances
```

browser.testerScripts

→ Use

browser.testerHtmlPath

```
browser.name
```
→ 使用
```
browser.instances
```

browser.testerScripts

→ 使用

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

缺少coverage.include：4.x版本中覆盖率配置必须显式设置include规则
使用已移除的池选项：
```
maxThreads
```
、
```
singleThread
```
已不再存在
使用defineWorkspace：已被
```
defineConfig
```
中的
```
projects
```
替代
浏览器提供程序导入错误：必须从提供程序包中导入
嵌套poolOptions：需扁平化至顶层配置

Performance Optimization

性能优化

Fast Unit Tests

快速单元测试

typescript

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

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,
    },
  },
});

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

有关详细的配置文档：

Pool Configuration - 工作线程管理和池选项
Coverage Configuration - V8/Istanbul覆盖率设置
Multi-Project Setup - Projects数组配置
Browser Mode Config - Playwright/WebDriverIO设置
Complete Examples - 完整的配置模板

有关从Vitest 3.x迁移的内容，请参阅

@vitest-4/skills/migrating-to-vitest-4

有关浏览器模式设置的内容，请参阅

@vitest-4/skills/using-browser-mode

有关完整的API参考，请参阅

@vitest-4/knowledge/vitest-4-comprehensive.md