工作區

範例專案

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 命令列選項：

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

所有不支援在專案設定中的設定選項在「設定」指南中都標有 * 標示。