插件 API 3.1.0+

WARNING

這是一個進階 API。如果您僅需執行測試，則可能無需使用此功能。它主要供函式庫開發者使用。

本指南假設您已熟悉 Vite 插件的使用方式。

Vitest 自 3.1 版起支援實驗性的 configureVitest 插件鉤子。歡迎在 GitHub 上提供有關此 API 的任何回饋。

only vitestvite and vitest

import type { Vite, VitestPluginContext } from 'vitest/node';

export function plugin(): Vite.Plugin {
  return {
    name: 'vitest:my-plugin',
    configureVitest(context: VitestPluginContext) {
      // ...
    },
  };
}

/// <reference types="vitest/config" />

import type { Plugin } from 'vite';

export function plugin(): Plugin {
  return {
    name: 'vitest:my-plugin',
    transform() {
      // ...
    },
    configureVitest(context) {
      // ...
    },
  };
}

TypeScript

Vitest 透過 Vite 命名空間重新匯出所有 Vite 僅型別匯入，您可以使用它來保持版本一致性。然而，如果您正在為 Vite 和 Vitest 編寫插件，您可以繼續使用來自 vite 入口點的 Plugin 型別。只需確保您在某處引用了 vitest/config，以便正確擴展 configureVitest：

/// <reference types="vitest/config" />

與 reporter.onInit 不同，此鉤子在 Vitest 生命週期早期執行，允許您修改 coverage 和 reporters 等配置。一個更值得注意的特性是，如果您的插件定義在專案中而非全域配置中，您可以從測試專案中修改全域配置。

上下文

project

插件所屬的測試專案。

瀏覽器模式

請注意，如果您依賴瀏覽器功能，project.browser 屬性尚未設定。請改用 reporter.onBrowserInit 事件。

vitest

全域 Vitest 實例。您可以透過直接變更 vitest.config 屬性來修改全域配置：

vitest.config.coverage.enabled = false;
vitest.config.reporters.push([['my-reporter', {}]]);

配置已解析

請注意，Vitest 已經解析了配置，因此某些型別可能與一般使用者配置不同。這也意味著某些屬性不會重複解析，例如 setupFile。如果您要新增檔案，請務必先進行解析。

此時報表尚未建立，因此修改 vitest.reporters 將無效，因為它將被覆寫。如果您需要注入自己的報表，請改為修改配置。

injectTestProjects

function injectTestProjects(
  config: TestProjectConfiguration | TestProjectConfiguration[]
): Promise<TestProject[]>;

此方法接受配置的 glob 模式、配置檔案路徑或行內配置。它會回傳一個已解析的測試專案陣列。

// 注入一個帶有自訂別名的單一專案
const newProjects = await injectTestProjects({
  // 您可以透過引用 `extends` 來繼承當前專案配置
  // 請注意，您不能擁有一個名稱已存在的專案，
  // 因此定義一個自訂名稱是個好習慣
  extends: project.vite.config.configFile,
  test: {
    name: 'my-custom-alias',
    alias: {
      customAlias: resolve('./custom-path.js'),
    },
  },
});

專案已篩選

Vitest 在配置解析期間會篩選專案，因此如果使用者定義了篩選器，注入的專案可能不會被解析，除非它符合該篩選器。您可以透過 vitest.config.project 選項來更新篩選器，以始終包含您的測試專案：

vitest.config.project.push('my-project-name');

請注意，這僅會影響使用 injectTestProjects 方法注入的專案。

引用當前配置

如果您想保留使用者配置，可以指定 extends 屬性。所有其他屬性將與使用者定義的配置合併。

專案的 configFile 可以在 Vite 的配置中取得：project.vite.config.configFile。

請注意，這也會繼承 name - Vitest 不允許有多個同名的專案，因此這將會拋出錯誤。請確保您指定了不同的名稱。您可以透過 project.name 屬性取得當前名稱，並且所有已使用的名稱都可在 vitest.projects 陣列中取得。

插件 API 3.1.0+ ​

上下文 ​

project ​

vitest ​

injectTestProjects ​

插件 API 3.1.0+

上下文

project

vitest

injectTestProjects