工作区

示例项目

GitHub - 在线运行

Vitest 允许在单个 Vitest 进程中定义多个项目配置。此功能特别适用于 Monorepo 架构，但也可用于运行具有不同配置（例如 resolve.alias、plugins 或 test.browser 等）的测试。

定义工作区

工作区在其根目录中必须包含 vitest.workspace 或 vitest.projects 文件（如果不存在，则位于与根配置文件或工作目录相同的文件夹中）。Vitest 支持该文件的 ts、js 和 json 扩展名。

命名

请注意，此功能名为 workspace，而不是 workspaces（末尾没有“s”）。

工作区配置文件必须默认导出一个文件列表或 glob 模式，用于引用您的项目。例如，如果您有一个名为 packages 的文件夹，其中包含您的项目，则可以使用以下配置文件定义工作区：

vitest.workspace.ts

export default ['packages/*'];

Vitest 会将 packages 目录下的每个文件夹视为一个独立的项目，即使其内部没有配置文件。自 Vitest 2.1 起，如果此 glob 模式匹配到任何文件，即使其名称中不包含 vitest，该文件也将被视为 Vitest 配置。

WARNING

Vitest 不会将根 vitest.config 文件视为工作区项目，除非在工作区配置中明确指定该文件。因此，根配置只会影响 reporters 和 coverage 等全局选项。

您还可以通过项目的配置文件来引用项目：

vitest.workspace.ts

export default ['packages/*/vitest.config.{e2e,unit}.ts'];

此模式将仅包含其 vitest.config 文件在扩展名前包含 e2e 或 unit 的项目。

您还可以使用内联配置定义项目。工作区文件同时支持这两种语法。

vitest.workspace.ts

import { defineWorkspace } from 'vitest/config';

// defineWorkspace 提供了良好的类型提示开发体验
export default defineWorkspace([
  // 匹配 `packages` 文件夹内的所有文件夹和文件
  'packages/*',
  {
    // 添加 "extends" 以合并两个配置
    extends: './vite.config.js',
    test: {
      include: ['tests/**/*.{browser}.test.{ts,js}'],
      // 建议在使用内联配置时定义名称
      name: 'happy-dom',
      environment: 'happy-dom',
    },
  },
  {
    test: {
      include: ['tests/**/*.{node}.test.{ts,js}'],
      name: 'node',
      environment: 'node',
    },
  },
]);

WARNING

所有项目都必须具有唯一的名称，否则 Vitest 将抛出错误。如果在内联配置中未提供名称，Vitest 将自动分配一个数字。对于使用 glob 语法定义的项目配置，Vitest 将默认使用最近的 package.json 文件中的“name”属性；如果该属性不存在，则使用文件夹名称。

如果您不使用内联配置，可以在根目录中创建一个小的 JSON 文件：

vitest.workspace.json

["packages/*"]

工作区项目并非支持所有配置属性。为了更好的类型安全，请在项目配置文件中使用 defineProject 方法，而不是 defineConfig：

packages/a/vitest.config.ts

// @errors: 2769
import { defineProject } from 'vitest/config';

export default defineProject({
  test: {
    environment: 'jsdom',
    // "reporters" 在项目配置中不受支持，
    // 因此会显示错误
    reporters: ['json'],
  },
});

运行测试

要在工作区中运行测试，请在根 package.json 中定义一个脚本：

{
  "scripts": {
    "test": "vitest"
  }
}

现在可以使用您的包管理器运行测试：

npm

npm run test

yarn

yarn test

pnpm

pnpm run test

bun

bun test

如果您仅需在单个项目中运行测试，请使用 --project CLI 选项：

npm

npm run test --project e2e

yarn

yarn test --project e2e

pnpm

pnpm run test --project e2e

bun

bun test --project e2e

TIP

CLI 选项 --project 可以多次使用，以筛选出多个项目：

npm

npm run test --project e2e --project unit

yarn

yarn test --project e2e --project unit

pnpm

pnpm run test --project e2e --project unit

bun

bun test --project e2e --project unit

配置

任何配置选项都不会从根配置继承。您可以创建共享配置文件，并自行将其与项目配置合并：

packages/a/vitest.config.ts

import { defineProject, mergeConfig } from 'vitest/config';
import configShared from '../vitest.shared.js';

export default mergeConfig(
  configShared,
  defineProject({
    test: {
      environment: 'jsdom',
    },
  })
);

在 defineWorkspace 级别，您可以使用 extends 选项来继承根配置。所有选项都将合并。

vitest.workspace.ts

import { defineWorkspace } from 'vitest/config';

export default defineWorkspace([
  {
    extends: './vitest.config.ts',
    test: {
      name: 'unit',
      include: ['**/*.unit.test.ts'],
    },
  },
  {
    extends: './vitest.config.ts',
    test: {
      name: 'integration',
      include: ['**/*.integration.test.ts'],
    },
  },
]);

某些配置选项在项目配置中是不允许的。主要包括：

• coverage：覆盖率是针对整个工作区计算的
• reporters：仅支持根级报告器
• resolveSnapshotPath：仅遵循根级解析器
• 所有其他不影响测试运行器的选项

TIP

所有在项目配置中不支持的配置选项，在 "配置" 指南中都标记有 * 符号。