Vitest

入门指南 高级 ​

WARNING

本指南列出了通过 Node.js 脚本运行测试的高级 API。如果你只是想 运行测试，可能不需要这个。它主要由库作者使用。

你可以从 vitest/node 入口点导入任何方法。

startVitest ​

ts
function startVitest(
  cliFilters: string[] = [],
  options: CliOptions = {},
  viteOverrides?: ViteUserConfig,
  vitestOptions?: VitestOptions,
): Promise<Vitest>

你可以使用其 Node API 开始运行 Vitest 测试：

js
import { startVitest } from 'vitest/node'

const vitest = await startVitest()

await vitest.close()

如果测试可以启动，startVitest 函数会返回 Vitest 实例。

如果未启用监视模式，Vitest 将自动调用 close 方法。

如果启用了监视模式且终端支持 TTY，Vitest 将注册控制台快捷键。

你可以将过滤器列表作为第二个参数传递。Vitest 将只运行文件路径中包含至少一个传递字符串的测试。

此外，你可以使用第三个参数传入 CLI 参数，这将覆盖任何测试配置选项。或者，你可以将完整的 Vite 配置作为第四个参数传入，这将优先于任何其他用户定义的选项。

运行测试后，你可以从 state.getTestModules API 获取结果：

ts
import type { TestModule } from 'vitest/node'

const vitest = await startVitest()

console.log(vitest.state.getTestModules()) // [TestModule]

TIP

"运行测试" 指南中有一个使用示例。

createVitest ​

ts
function createVitest(
  options: CliOptions,
  viteOverrides: ViteUserConfig = {},
  vitestOptions: VitestOptions = {},
): Promise<Vitest>

你可以使用 createVitest 函数创建 Vitest 实例。它返回与 startVitest 相同的 Vitest 实例，但它不会启动测试，也不会验证已安装的软件包。

js
import { createVitest } from 'vitest/node'

const vitest = await createVitest('test', {
  watch: false,
})

TIP

"运行测试" 指南中有一个使用示例。

resolveConfig ​

ts
function resolveConfig(
  options: UserConfig = {},
  viteOverrides: ViteUserConfig = {},
  harness?: PluginHarness,
): Promise<ResolvedViteConfig>

此方法使用自定义参数解析配置，但不会创建 Vite 服务器。如果未提供参数，root 将为 process.cwd()。

它会返回解析后的 Vite 配置。完全解析后的 Vitest 配置（包括每个项目）位于其 test 属性上。

ts
import { resolveConfig } from 'vitest/node'

const viteConfig = await resolveConfig({
  mode: 'custom',
  configFile: false,
  resolve: {
    conditions: ['custom']
  },
  test: {
    setupFiles: ['/my-setup-file.js'],
    pool: 'threads',
  },
})

viteConfig.test.pool // 'threads'

INFO

这是 Vitest 在创建服务器前用于解析配置的同一个方法。如果将选项传递给 startVitest 或 createVitest，Vitest 会再次解析这些选项。

你可以将共享的 PluginHarness 作为第三个参数传入，以便在多次调用之间复用日志记录器和包安装器。

项目配置解析 ​

本节介绍 startVitest、createVitest 和 resolveConfig 的参数如何与测试项目交互。如果没有项目，所有解析后的选项都会应用于单个根项目，本节内容也就无关紧要了。

根配置按照优先级从低到高由以下三个输入解析而来：

  1. 根配置文件
  2. viteOverrides，在配置文件的值之上进行合并
  3. CLI 选项（options），在其他所有内容之上应用

随后，每个项目都会独立解析自己的 Vite 配置：

  • 作为配置文件或目录引用的项目只解析其自身的文件，不会继承根配置中的任何选项。
  • 内联项目默认继承根配置（参见 extends）：会为该项目重新执行根配置文件，在其上合并 viteOverrides，最后再合并项目自身的选项。即使不存在根配置文件，继承也依然有效，因为 viteOverrides 是有效根配置的一部分。
  • 使用 extends: false 时，内联项目只解析自身的选项。使用 extends: './path' 时，会重新执行所引用的文件，而不是根配置文件，并且不会合并 viteOverrides。

以下选项不会被继承：

  • viteOverrides 中的 plugins 永远不会被继承。配置文件会针对每个项目重新执行，从而创建全新的插件实例；但传入 viteOverrides 的插件实例属于根 Vite 服务器，无法与项目服务器共享。
  • viteOverrides 中的 test.browser 和 test.tagsFilter 永远不会被继承：browser 描述单个项目的实例，而 tagsFilter 应用于整个运行过程。
  • name 和 projects 永远不会被继承；根配置中的 globalSetup 也不会被继承，因为它已经在每次测试运行时执行一次。
  • 项目自身的 tags 始终会替换从扩展配置中合并而来的 tags 数组，而不是与其拼接，因此可以重新定义相同的标签名称。

无论是否使用 extends，两组选项都会传递给每个项目：

  • 一组固定的 CLI 选项用于配置测试的运行方式（--testTimeout、--retry、--pool 等），并以最高优先级应用于每个项目，与根配置的解析方式保持一致。
  • 运行级选项只对整个测试运行过程有意义：每个项目都会接收根配置中已解析的 coverage、attachmentsDir 和 mergeReportsLabel 值。

parseCLI ​

ts
function parseCLI(argv: string | string[], config: CliParseOptions = {}): {
  filter: string[]
  options: CliOptions
}

你可以使用此方法解析 CLI 参数。它接受一个字符串（其中参数由单个空格分隔）或 Vitest CLI 使用的相同格式的 CLI 参数字符串数组。它返回一个过滤器和 options，你可以稍后将其传递给 createVitest 或 startVitest 方法。

ts
import { parseCLI } from 'vitest/node'

const result = parseCLI('vitest ./files.ts --coverage --browser=chrome')

result.options
// {
//   coverage: { enabled: true },
//   browser: { name: 'chrome', enabled: true }
// }

result.filter
// ['./files.ts']

createCLI ​

ts
function createCLI(options?: CliParseOptions): CAC

创建 Vitest 命令行界面：一个已注册 Vitest 所有命令和选项的 cac 实例。parseCLI 基于它构建；如果需要原始解析器，请直接使用 createCLI。

ts
import { createCLI } from 'vitest/node'

const cli = createCLI()

插件容器 ​

ts
class PluginHarness {
  vitest?: Vitest
  version: string
  logger: Logger
  packageInstaller: VitestPackageInstaller
  getVitest(): Vitest
}

Vitest 在解析配置期间、Vitest 实例存在之前，传递给其内部插件的容器。它包含 Logger、包安装器和已解析的版本，并在 Vitest 实例创建后通过 getVitest() 提供该实例（提前调用会抛出异常）。

这是一个面向高级用户的插件 API。你很少会直接构造它，但可以将共享实例传递给 resolveConfig，以复用日志记录器和包安装器。

日志记录器 ​

ts
class Logger {
  constructor(
    outputStream?: Writable,
    errorStream?: Writable,
  )
}

Vitest 的终端日志记录器，通过 vitest.logger 暴露。它负责处理格式化输出、错误摘要、运行横幅和清屏操作。使用自定义的 stdout/stderr 流构造一个实例，即可在以编程方式运行 Vitest 时捕获或重定向其输出。

ts
import { Logger } from 'vitest/node'

const logger = new Logger(process.stdout, process.stderr)

© 2026 VoidZero Inc. and Vitest contributors.