高级 API

WARNING

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

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

startVitest

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

您可以使用 Vitest 的 Node API 启动 Vitest 测试运行：

import { startVitest } from 'vitest/node';

const vitest = await startVitest('test');

await vitest.close();

如果测试能够成功启动，startVitest 函数将返回一个 Vitest 实例。

如果未启用监听模式，Vitest 将在测试运行结束后自动调用 close 方法。

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

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

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

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

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

const vitest = await startVitest('test');

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

TIP

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

createVitest

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

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

import { createVitest } from 'vitest/node';

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

TIP

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

resolveConfig

function resolveConfig(
  options: UserConfig = {},
  viteOverrides: ViteUserConfig = {}
): Promise<{
  vitestConfig: ResolvedConfig;
  viteConfig: ResolvedViteConfig;
}>;

此方法使用自定义参数解析配置。如果没有提供参数，root 将默认为 process.cwd()。

import { resolveConfig } from 'vitest/node';

// vitestConfig 只包含已解析的 "test" 属性
const { vitestConfig, viteConfig } = await resolveConfig({
  mode: 'custom',
  configFile: false,
  resolve: {
    conditions: ['custom'],
  },
  test: {
    setupFiles: ['/my-setup-file.js'],
    pool: 'threads',
  },
});

INFO

由于 Vite 的 createServer 的工作原理，Vitest 需要在插件的 configResolve 钩子中解析配置。因此，此方法实际上并未在内部使用，而是专门作为公共 API 公开。

如果您将配置传递给 startVitest 或 createVitest API 时，Vitest 仍将再次解析配置。

WARNING

resolveConfig 不会解析 projects。要解析项目配置，Vitest 需要一个已建立的 Vite 服务器。

另请注意，viteConfig.test 不会被完全解析。如果您需要 Vitest 配置，请改用 vitestConfig。

parseCLI

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

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

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']