進階 API

WARNING

本指南列出了透過 Node.js 腳本執行測試的進階 API。如果您僅需執行測試，則可能無需使用這些 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 參數。它接受一個字串（其中參數由單一空格分隔）或一個字串陣列，其 CLI 參數格式與 Vitest 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']