测试项目

示例项目

GitHub - 在线运行

WARNING

此功能曾被称为 workspace。workspace 自 3.2 版本起已弃用，并由 projects 配置取代。两者功能相同。

Vitest 提供了一种在单个 Vitest 进程中定义多个项目配置的方法。该功能特别适用于 monorepo（多项目仓库）设置，但也可用于运行具有不同配置的测试，例如 resolve.alias、plugins 或 test.browser 等。

定义项目

你可以在根 配置 中定义项目：

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: ['packages/*'],
  },
});

项目配置可以是内联配置、文件路径，或是引用项目文件的 glob 模式。例如，如果你有一个名为 packages 的文件夹，其中包含你的项目，你可以在根 Vitest 配置中定义一个数组：

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: ['packages/*'],
  },
});

Vitest 会将 packages 中的每个文件夹视为一个单独的项目，即使该文件夹内部没有配置文件。如果此 glob 模式匹配任何文件，它都将被视为 Vitest 配置，即使其名称中不包含 vitest 或具有不常见的扩展名。

WARNING

Vitest 不会将根 vitest.config 文件视为项目，除非在配置中明确指定。因此，根配置只会影响全局选项，例如 reporters 和 coverage。值得注意的是，Vitest 始终会运行在根配置文件中指定的某些插件钩子，例如 apply、config、configResolved 或 configureServer。Vitest 还会使用相同的插件执行全局设置和自定义覆盖率提供程序。

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

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: ['packages/*/vitest.config.{e2e,unit}.ts'],
  },
});

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

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

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      // 匹配 `packages` 文件夹下的所有文件夹和文件
      'packages/*',
      {
        // 添加 "extends: true" 以继承根配置中的选项
        extends: true,
        test: {
          include: ['tests/**/*.{browser}.test.{ts,js}'],
          // 建议在使用内联配置时定义一个名称
          name: 'happy-dom',
          environment: 'happy-dom',
        },
      },
      {
        test: {
          include: ['tests/**/*.{node}.test.{ts,js}'],
          // 名称标签的颜色可以修改
          name: { label: 'node', color: 'green' },
          environment: 'node',
        },
      },
    ],
  },
});

WARNING

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

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

// @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 run test

若只需在单个项目中运行测试，请使用 --project CLI 选项：

npm

npm run test --project e2e

yarn

yarn test --project e2e

pnpm

pnpm run test --project e2e

bun

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

配置

所有配置选项不会从根级配置文件继承。你可以创建一个共享配置文件并将其与项目配置合并：

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

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

此外，你可以使用 extends 选项从根级配置继承。所有选项都将合并。

import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    pool: 'threads',
    projects: [
      {
        // 将继承此配置中的选项，例如插件和池
        extends: true,
        test: {
          name: 'unit',
          include: ['**/*.unit.test.ts'],
        },
      },
      {
        // 不会继承此配置中的任何选项
        // 这是默认行为
        extends: false,
        test: {
          name: 'integration',
          include: ['**/*.integration.test.ts'],
        },
      },
    ],
  },
});

不支持的选项

项目配置中不允许使用某些配置选项。最值得注意的是：

• coverage：覆盖率统计针对整个进程
• reporters：仅支持根级别的报告器
• resolveSnapshotPath：只遵循根级解析器
• 所有其他不影响测试运行器的选项

所有在项目配置中不受支持的配置选项，在“配置”指南中都标有 * 符号。它们必须在根配置文件中定义一次。