工作区

示例项目

GitHub - 在线运行

Vitest 通过工作区配置文件提供对 monorepo（单代码仓库）的内置支持。你可以创建一个工作区来定义项目的设置。

定义工作区

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

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

vitest.workspace.ts

export default ['packages/*'];

Vitest 会将 packages 目录下的每个文件夹都视为一个单独的项目，即使其内部没有配置文件。

WARNING

除非在此配置中指定，否则 Vitest 不会将根配置视为工作区项目（因此它不会运行在 include 中指定的测试）。

你还可以使用配置文件引用项目：

vitest.workspace.ts

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

此模式将仅包含那些文件名包含 e2e 或 unit 的 vitest.config 文件对应的项目。

WARNING

如果使用 glob 模式引用文件名，请确保你的配置文件以 vite.config 或 vitest.config 开头。否则，Vitest 将跳过该文件。

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

vitest.workspace.ts

import { defineWorkspace } from 'vitest/config';

// defineWorkspace 提供了良好的开发者体验和类型提示
export default defineWorkspace([
  '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 默认会使用目录名作为项目名称。

如果你不依赖内联配置，可以在根目录中创建一个 json 文件：

vitest.workspace.json

["packages/*"]

工作区项目不支持某些配置属性。为了更好的类型安全，请在项目配置文件中，使用 defineProject 方法代替 defineConfig 方法：

packages/a/vitest.config.ts

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 run test --project e2e

TIP

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

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

此外，某些配置选项在项目配置中是不允许的。最值得注意的是：

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

TIP

所有在项目配置中不受支持的配置选项，在 "Config" 页面中都标记为 *。

覆盖率

覆盖率功能可以直接使用。但是，如果你启用了 all 选项，并且某些项目使用了非常规的文件扩展名，你需要在根配置文件中添加一个处理此扩展名的插件。

例如，如果你有一个使用 Vue 文件的包，并且它有自己的配置文件，但某些文件没有在测试中被引用，那么覆盖率分析可能会因为依赖于根配置而非项目配置而失效，从而无法分析这些未被引用的文件。