Vitest API

Vitest インスタンスは、現在のテストモードを必要とします。モードは以下のいずれかです。

• ランタイムテスト実行時: test
• ベンチマーク実行時: benchmark 実験的

Vitest 3 の新機能

Vitest 3 では、パブリック API の安定化に向けた取り組みが進められました。その一環として、以前 Vitest クラスのパブリックメソッドであった一部の API が非推奨化され、削除されました。これらの 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() を呼び出すことで、Reported Tasks API を使用することをお勧めします。

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

将来的には、古い API は公開されなくなります。

snapshot

グローバルなスナップショットマネージャーです。Vitest は snapshot.add メソッドを使用してすべてのスナップショットを追跡します。

vitest.snapshot.summary プロパティを介して、スナップショットの最新の概要を取得できます。

cache

最新のテスト結果とテストファイルの統計に関する情報を格納するキャッシュマネージャーです。Vitest 自体では、これはデフォルトのシーケンサーによってテストをソートするためにのみ使用されます。

projects

ユーザーのプロジェクトに属する テストプロジェクト の配列です。ユーザーがそれらを指定しなかった場合、この配列には ルートプロジェクト のみが含まれます。

Vitest は、この配列に常に少なくとも1つのプロジェクトがあることを保証します。ユーザーが存在しない --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 を少なくとも1回呼び出してください。

clearSpecificationsCache

function clearSpecificationsCache(moduleId?: string): void;

Vitest は、globTestSpecifications または runTestSpecifications が呼び出されると、ファイルごとにテスト仕様を自動的にキャッシュします。このメソッドは、最初の引数に応じて、指定されたファイルのキャッシュまたは全体のキャッシュをクリアします。

runTestSpecifications

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

このメソッドは、受け取った 仕様 に基づいてすべてのテストを実行します。2番目の引数 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 のウォッチャーを無効にしても 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>;

すべてのプロジェクトとその関連リソースを閉じます。これは一度しか呼び出すことができません。クローズプロミスはサーバーが再起動するまでキャッシュされます。

exit

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

すべてのプロジェクトを閉じ、プロセスを終了します。force が true に設定されている場合、プロジェクトを閉じた後すぐにプロセスが終了します。

このメソッドは、config.teardownTimeout ミリ秒後にプロセスがまだアクティブな場合、process.exit() を強制的に呼び出します。

shouldKeepServer

function shouldKeepServer(): boolean;

このメソッドは、テスト完了後にサーバーを実行し続けるべきかどうかを返します。これは通常 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)
);

Vitest は pool または locations オプションに応じて同じファイルに対して異なる仕様を作成できるため、参照に依存しないでください。Vitest は vitest.getModuleSpecifications からキャッシュされた仕様を返すこともできます。キャッシュは moduleId と pool に基づいています。ただし、project.createSpecification は常に新しいインスタンスを返すことに注意してください。

matchesProjectFilter 3.1.0+

function matchesProjectFilter(name: string): boolean;

名前が現在の プロジェクトフィルター に一致するかどうかを確認します。プロジェクトフィルターが設定されていない場合、常に true を返します。

--project CLI オプションをプログラムで変更することはできません。