插件 API 3.1.0+

WARNING

这是一个高级 API。如果你只是想运行测试，你可能不需要它。它主要供库作者使用。

本指南假设你已经了解如何使用 Vite 插件。

Vitest 从 3.1 版本开始支持实验性的 configureVitest 插件钩子。欢迎在 GitHub 上提供对此 API 的任何反馈。

仅 VitestVite 和 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 已解析配置，因此某些类型可能与通常的用户配置不同。这也意味着某些属性不会再次解析，例如 setupFiles。如果你要添加新文件，请确保先解析它。

此时报告器尚未创建，因此修改 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