Vitest API

Vitest 实例需要当前的测试模式，模式可以是：

test：运行时测试时
benchmark：执行基准测试时实验性

Vitest 3 的新特性

Vitest 3 在稳定公共 API 方面又迈进了一步。因此，我们废弃并移除了 Vitest 类上一些以前的公共方法，这些 API 已变为私有：

configOverride (使用 setGlobalTestNamePattern 或 enableSnapshotUpdate)
coverageProvider
filenamePattern
runningPromise
closingPromise
isCancelling
coreWorkspaceProject
resolvedProjects
_browserLastPort
_options
reporters
vitenode
runner
pool
setServer
_initBrowserServers
rerunTask
changeProjectName
changeNamePattern
changeFilenamePattern
rerunFailed
_createRootProject (重命名为 _ensureRootProject，但仍为私有)
filterTestsBySource (此方法已移至新的内部 vitest.specifications 实例中)
runFiles (请改用 runTestSpecifications)
onAfterSetServer

这些 API 已被废弃：

invalidates
changedTests (请改用 onFilterWatchedSpecification)
server (请改用 vite)
getProjectsByTestFile (请改用 getModuleSpecifications)
getFileWorkspaceSpecs (请改用 getModuleSpecifications)
getModuleProjects (请自行通过 this.projects 过滤)
updateLastChanged (重命名为 invalidateFile)
globTestSpecs (请改用 globTestSpecifications)
globTestFiles (请改用 globTestSpecifications)
listFile (请改用 getRelevantTestSpecifications)

mode

test

测试模式仅会调用 test 或 it 中的函数，并在遇到 bench 时抛出错误。此模式使用配置中的 include 和 exclude 选项来查找测试文件。

benchmark 实验性

基准测试模式将调用 bench 函数，并在遇到 test 或 it 时抛出错误。此模式使用配置中的 benchmark.include 和 benchmark.exclude 选项来查找基准测试文件。

config

根配置（或全局配置）。如果定义了项目，它们将把此配置引用为 globalConfig。

WARNING

这是 Vitest 配置，它不扩展 Vite 配置。它只包含 test 属性中解析后的值。

vite

这是一个全局的 ViteDevServer。

state 实验性

WARNING

公开的 state 是一个实验性 API（vitest.state.getReportedEntity 除外）。破坏性更改可能不遵循 SemVer，使用时请固定 Vitest 的版本。

全局状态存储当前测试的相关信息。默认情况下，它使用 @vitest/runner 中的相同 API，但我们建议通过在 @vitest/runner API 上调用 state.getReportedEntity() 来改用报告任务 API：

const task = vitest.state.idMap.get(taskId); // 旧 API
const testCase = vitest.state.getReportedEntity(task); // 新 API

将来，旧 API 将不再暴露。

snapshot

全局快照管理器。Vitest 使用 snapshot.add 方法跟踪所有快照。

您可以通过 vitest.snapshot.summary 属性获取最新的快照摘要。

cache

缓存管理器，用于存储最新的测试结果和测试文件统计信息。在 Vitest 本身中，这仅由默认的序列器用于排序测试。

projects

一个包含用户测试项目的数组。如果用户未指定项目，则此数组将只包含一个根项目。

Vitest 将确保此数组中始终至少有一个项目。如果用户指定了一个不存在的 --project 名称，Vitest 将在此数组定义之前抛出错误。

getRootProject

function getRootProject(): TestProject;

这会返回根测试项目。根项目通常不运行任何测试，并且不包含在 vitest.projects 中，除非用户在其配置中明确包含根配置，或者根本未定义任何项目。

根项目的主要目的是设置全局配置。实际上，rootProject.config 直接引用 rootProject.globalConfig 和 vitest.config：

(rootProject.config === rootProject.globalConfig) === rootProject.vitest.config;

provide

function provide<T extends keyof ProvidedContext & string>(
  key: T,
  value: ProvidedContext[T]
): void;

Vitest 提供了 provide 方法，它是 vitest.getRootProject().provide 的简写。使用此方法可以将值从主线程传递给测试。所有值在存储前都会通过 structuredClone 进行检查，但值本身不会被克隆。

若要在测试中获取这些值，您需要从 vitest 入口点导入 inject 方法：

import { inject } from 'vitest';
const port = inject('wsPort'); // 3000

为了获得更好的类型安全，我们鼓励您扩展 ProvidedContext 的类型：

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test', {
  watch: false,
});
vitest.provide('wsPort', 3000);

declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number;
  }
}

WARNING

严格来说，provide 是 TestProject 的一个方法，因此它仅限于特定项目。然而，所有项目都继承了根项目的值，这使得 vitest.provide 成为向测试传递值的通用方法。

getProvidedContext

function getProvidedContext(): ProvidedContext;

这会返回根上下文对象，等同于 vitest.getRootProject().getProvidedContext。

getProjectByName

function getProjectByName(name: string): TestProject;

此方法根据名称返回项目。类似于调用 vitest.projects.find。

WARNING

如果项目不存在，此方法将返回根项目——请确保再次检查名称，以确认返回的项目是否为您所寻找。

如果用户未自定义名称，Vitest 将分配一个空字符串作为名称。

globTestSpecifications

function globTestSpecifications(
  filters?: string[]
): Promise<TestSpecification[]>;

此方法使用 project.globTestFiles 收集所有项目中的测试，并构建新的测试规范。它接受字符串过滤器来匹配测试文件——这些过滤器与 CLI 支持的过滤器相同。

此方法会自动缓存所有测试规范。当您下次调用 getModuleSpecifications 时，它将返回相同的规范，除非在此之前调用了 clearSpecificationsCache。

WARNING

截至 Vitest 3，如果 poolMatchGlob 有多个池或启用了 typecheck，则可能存在具有相同模块 ID（文件路径）的多个测试规范。Vitest 4 将移除这种可能性。

const specifications = await vitest.globTestSpecifications(['my-filter']);
// [TestSpecification{ moduleId: '/tests/my-filter.test.ts' }]
console.log(specifications);

getRelevantTestSpecifications

function getRelevantTestSpecifications(
  filters?: string[]
): Promise<TestSpecification[]>;

此方法通过调用 project.globTestFiles 来解析所有测试规范。它接受字符串过滤器来匹配测试文件——这些过滤器与 CLI 支持的过滤器相同。如果指定了 --changed 标志，列表将过滤为仅包含已更改的文件。getRelevantTestSpecifications 不运行任何测试文件。

WARNING

此方法可能很慢，因为它需要过滤 --changed 标志。如果您只需要测试文件列表，请勿使用此方法。

如果您需要获取已知测试文件的规范列表，请改用 getModuleSpecifications。
如果您需要获取所有可能的测试文件列表，请使用 globTestSpecifications。

mergeReports

function mergeReports(directory?: string): Promise<TestRunResult>;

合并指定目录中多次运行的报告（如果未指定，则为 --merge-reports 的值）。此值也可以在 config.mergeReports 上设置（默认情况下，它将读取 .vitest-reports 文件夹）。

请注意，directory 将始终相对于工作目录解析。

如果设置了 config.mergeReports，此方法将由 startVitest 自动调用。

collect

function collect(filters?: string[]): Promise<TestRunResult>;

执行测试文件而不运行测试回调。collect 方法返回未处理的错误和测试模块数组。它接受字符串过滤器来匹配测试文件——这些过滤器与 CLI 支持的过滤器相同。

此方法根据配置的 include、exclude 和 includeSource 值解析测试规范。更多信息请阅读 project.globTestFiles。如果指定了 --changed 标志，列表将过滤为仅包含已更改的文件。

WARNING

请注意，Vitest 不使用静态分析来收集测试。Vitest 将像运行常规测试一样，隔离运行每个测试文件。

这使得此方法非常慢，除非您在收集测试之前禁用隔离。

start

function start(filters?: string[]): Promise<TestRunResult>;

初始化报告器和覆盖率提供程序，并运行测试。此方法接受字符串过滤器来匹配测试文件——这些过滤器与 CLI 支持的过滤器相同。

WARNING

如果同时调用了 vitest.init()，则不应调用此方法。如果您需要在 Vitest 初始化后运行测试，请改用 runTestSpecifications 或 rerunTestSpecifications。

如果未设置 config.mergeReports 和 config.standalone，此方法将由 startVitest 自动调用。

init

function init(): Promise<void>;

初始化报告器和覆盖率提供程序。此方法不运行任何测试。如果提供了 --watch 标志，即使未调用此方法，Vitest 仍会运行已更改的测试。

在内部，仅当启用 --standalone 标志时才调用此方法。

WARNING

如果同时调用了 vitest.start()，则不应调用此方法。

如果设置了 config.standalone，此方法将由 startVitest 自动调用。

getModuleSpecifications

function getModuleSpecifications(moduleId: string): TestSpecification[];

返回与模块 ID 相关的测试规范列表。该 ID 应已解析为绝对文件路径。如果 ID 不匹配 include 或 includeSource 模式，则返回的数组将为空。

此方法可以根据 moduleId 和 pool 返回已缓存的规范。但请注意，project.createSpecification 总是返回一个新实例，并且不会自动缓存。然而，当调用 runTestSpecifications 时，规范会自动缓存。

WARNING

截至 Vitest 3，此方法使用缓存来检查文件是否为测试。为确保缓存不为空，请至少调用一次 globTestSpecifications。

clearSpecificationsCache

function clearSpecificationsCache(moduleId?: string): void;

当调用 globTestSpecifications 或 runTestSpecifications 时，Vitest 会自动缓存每个文件的测试规范。此方法根据第一个参数清除给定文件的缓存或整个缓存。

runTestSpecifications

function runTestSpecifications(
  specifications: TestSpecification[],
  allTestsRun = false
): Promise<TestRunResult>;

此方法根据接收到的规范运行每个测试。第二个参数 allTestsRun 由覆盖率提供程序使用，以确定是否需要在根目录中的_所有_文件上进行覆盖率检测（这仅在启用覆盖率且 coverage.all 设置为 true 时才重要）。

WARNING

此方法不会触发 onWatcherRerun、onWatcherStart 和 onTestsRerun 回调。如果您是根据文件更改来重新运行测试，请考虑改用 rerunTestSpecifications。

rerunTestSpecifications

function rerunTestSpecifications(
  specifications: TestSpecification[],
  allTestsRun = false
): Promise<TestRunResult>;

此方法发出 reporter.onWatcherRerun 和 onTestsRerun 事件，然后使用 runTestSpecifications 运行测试。如果主进程中没有错误，它将发出 reporter.onWatcherStart 事件。

updateSnapshot

function updateSnapshot(files?: string[]): Promise<TestRunResult>;

更新指定文件中的快照。如果未提供文件，它将更新包含失败测试和已过时快照的文件。

collectTests

function collectTests(
  specifications: TestSpecification[]
): Promise<TestRunResult>;

执行测试文件而不运行测试回调。collectTests 方法返回未处理的错误和测试模块数组。

此方法与 collect 完全相同，但您需要自行提供测试规范。

WARNING

请注意，Vitest 不使用静态分析来收集测试。Vitest 将像运行常规测试一样，隔离运行每个测试文件。

这使得此方法非常慢，除非您在收集测试之前禁用隔离。

cancelCurrentRun

function cancelCurrentRun(reason: CancelReason): Promise<void>;

此方法将优雅地取消所有正在进行的测试任务。它将等待已开始的测试完成运行，并且不会运行那些已计划但尚未开始的测试。

setGlobalTestNamePattern

function setGlobalTestNamePattern(pattern: string | RegExp): void;

此方法将覆盖全局的测试名称模式。

WARNING

此方法不会开始运行任何测试。要使用更新的模式运行测试，请调用 runTestSpecifications。

resetGlobalTestNamePattern

function resetGlobalTestNamePattern(): void;

此方法重置全局的测试名称模式。这意味着 Vitest 现在不会跳过任何测试。

WARNING

此方法不会开始运行任何测试。要在没有模式的情况下运行测试，请调用 runTestSpecifications。

enableSnapshotUpdate

function enableSnapshotUpdate(): void;

启用允许在运行测试时更新快照的模式。此方法调用后运行的每个测试都会更新快照。要禁用此模式，请调用 resetSnapshotUpdate。

WARNING

此方法不会开始运行任何测试。要更新快照，请使用 runTestSpecifications 运行测试。

resetSnapshotUpdate

function resetSnapshotUpdate(): void;

禁用允许在运行测试时更新快照的模式。此方法不会开始运行任何测试。

invalidateFile

function invalidateFile(filepath: string): void;

此方法会使每个项目缓存中的文件失效。如果您依赖自定义的观察器，这会非常有用，因为 Vite 的缓存会保留在内存中。

DANGER

如果禁用 Vitest 的观察器但仍保持其运行，则手动使用此方法清除缓存非常重要，因为无法禁用缓存。此方法还将使文件的导入者失效。

import

function import<T>(moduleId: string): Promise<T>

使用 Vite 模块运行器导入文件。文件将由 Vite 使用全局配置进行转换，并在单独的上下文中执行。请注意，moduleId 将相对于 config.root。

DANGER

project.import 重用 Vite 的模块图，因此使用常规导入导入相同的模块将返回不同的模块：

import * as staticExample from './example.js';
const dynamicExample = await vitest.import('./example.js');

dynamicExample !== staticExample; // ✅

INFO

在内部，Vitest 使用此方法导入全局设置、自定义覆盖率提供程序和自定义报告器，这意味着只要它们属于同一个 Vite 服务器，它们就共享相同的模块图。

close

function close(): Promise<void>;

关闭所有项目及其相关资源。此方法只能调用一次；关闭 promise 会被缓存，直到服务器重新启动。

exit

function exit(force = false): Promise<void>;

关闭所有项目并退出进程。如果 force 设置为 true，进程将在关闭项目后立即退出。

如果进程在 config.teardownTimeout 毫秒后仍处于活动状态，此方法还将强制调用 process.exit()。

shouldKeepServer

function shouldKeepServer(): boolean;

如果服务器在测试完成后应保持运行，此方法将返回 true。这通常意味着启用了 watch 模式。

onServerRestart

function onServerRestart(fn: OnServerRestartHandler): void;

注册一个处理程序，当服务器因配置更改而重新启动时，该处理程序将被调用。

onCancel

function onCancel(fn: (reason: CancelReason) => Awaitable<void>): void;

注册一个处理程序，当测试运行被 vitest.cancelCurrentRun 取消时，该处理程序将被调用。

onClose

function onClose(fn: () => Awaitable<void>): void;

注册一个处理程序，当服务器关闭时，该处理程序将被调用。

onTestsRerun

function onTestsRerun(fn: OnTestsRerunHandler): void;

注册一个处理程序，当测试重新运行时，该处理程序将被调用。当手动调用 rerunTestSpecifications，或文件更改触发内置观察器重新安排运行时，测试可以重新运行。

onFilterWatchedSpecification

function onFilterWatchedSpecification(
  fn: (specification: TestSpecification) => boolean
): void;

注册一个处理程序，当文件更改时，该处理程序将被调用。此回调应返回 true 或 false，指示测试文件是否需要重新运行。

通过此方法，您可以介入默认的观察器逻辑，以延迟或丢弃用户目前不想跟踪的测试：

const continuesTests: string[] = [];

myCustomWrapper.onContinuesRunEnabled(testItem =>
  continuesTests.push(item.fsPath)
);

vitest.onFilterWatchedSpecification(specification =>
  continuesTests.includes(specification.moduleId)
);

根据 pool 或 locations 选项，Vitest 可能为同一文件创建不同的规范，因此不要依赖引用。Vitest 还可以从 vitest.getModuleSpecifications 返回缓存的规范——缓存基于 moduleId 和 pool。请注意，project.createSpecification 总是返回一个新实例。

matchesProjectFilter 3.1.0+

function matchesProjectFilter(name: string): boolean;

检查名称是否与当前的项目过滤器匹配。如果没有项目过滤器，此方法将始终返回 true。

无法通过编程方式更改 --project CLI 选项。

Vitest API ​

mode ​

test ​

benchmark 实验性 ​

config ​

vite ​

state 实验性 ​

snapshot ​

cache ​

projects ​

getRootProject ​

provide ​

getProvidedContext ​

getProjectByName ​

globTestSpecifications ​

getRelevantTestSpecifications ​

mergeReports ​

collect ​

start ​

init ​

getModuleSpecifications ​

clearSpecificationsCache ​

runTestSpecifications ​

rerunTestSpecifications ​

updateSnapshot ​

collectTests ​

cancelCurrentRun ​

setGlobalTestNamePattern ​

resetGlobalTestNamePattern ​

enableSnapshotUpdate ​

resetSnapshotUpdate ​

invalidateFile ​

import ​

close ​

exit ​

shouldKeepServer ​

onServerRestart ​

onCancel ​

onClose ​

onTestsRerun ​

onFilterWatchedSpecification ​

matchesProjectFilter 3.1.0+ ​

Vitest API

mode

test

benchmark 实验性

config

vite

state 实验性

snapshot

cache

projects

getRootProject

provide

getProvidedContext

getProjectByName

globTestSpecifications

getRelevantTestSpecifications

mergeReports

collect

start

init

getModuleSpecifications

clearSpecificationsCache

runTestSpecifications

rerunTestSpecifications

updateSnapshot

collectTests

cancelCurrentRun

setGlobalTestNamePattern

resetGlobalTestNamePattern

enableSnapshotUpdate

resetSnapshotUpdate

invalidateFile

import

close

exit

shouldKeepServer

onServerRestart

onCancel

onClose

onTestsRerun

onFilterWatchedSpecification

matchesProjectFilter 3.1.0+