レポーター
WARNING
これは高度なAPIです。組み込みのレポーターを設定したいだけであれば、"レポーター"ガイドを参照してください。
Vitestには独自のテスト実行ライフサイクルがあり、レポーターの各メソッドによってその状態が表現されます。
onInit
onTestRunStart
onTestRunEnd
単一モジュール内のテストとスイートは、スキップされない限り順次報告されます。スキップされたすべてのテストは、スイート/モジュールの最後にまとめて報告されます。
テストモジュールは並行して実行されるため、Vitestもそれらを並行して報告します。
このガイドでは、サポートされているすべてのレポーターメソッドをリストしています。ただし、独自のレポーターをゼロから作成する代わりに、既存のものを拡張することも可能であることを忘れないでください。
import { BaseReporter } from 'vitest/reporters';
export default class CustomReporter extends BaseReporter {
onTestRunEnd(testModules, errors) {
console.log(testModules.length, 'tests finished running');
super.onTestRunEnd(testModules, errors);
}
}
onInit
function onInit(vitest: Vitest): Awaitable<void>;
このメソッドは、Vitestが初期化または開始された後、テストがフィルタリングされる前に呼び出されます。
INFO
内部的には、このメソッドはvitest.start
、vitest.init
、またはvitest.mergeReports
内で呼び出されます。プログラムAPIを使用している場合、例えばvitest.runTestSpecifications
を呼び出す前に、必要に応じてこれらのいずれかを呼び出すようにしてください。組み込みのCLIは常に正しい順序でメソッドを実行します。
vitest
インスタンスには、テストケース、スイート、テストモジュールからproject
プロパティを介してアクセスすることも可能ですが、このメソッドでvitest
への参照を保存することも有用です。
例
import type { Reporter, TestSpecification, Vitest } from 'vitest/node';
class MyReporter implements Reporter {
private vitest!: Vitest;
onInit(vitest: Vitest) {
this.vitest = vitest;
}
onTestRunStart(specifications: TestSpecification[]) {
console.log(
specifications.length,
'test files will run in',
this.vitest.config.root
);
}
}
export default new MyReporter();
onBrowserInit 実験的
function onBrowserInit(project: TestProject): Awaitable<void>;
このメソッドは、ブラウザインスタンスが初期化されたときに呼び出されます。ブラウザが初期化されるプロジェクトのインスタンスを受け取ります。このメソッドが呼び出されるとき、project.browser
は常に定義されています。
onTestRunStart
function onTestRunStart(specifications: TestSpecification[]): Awaitable<void>;
このメソッドは、新しいテスト実行が開始されたときに呼び出されます。実行がスケジュールされているテスト仕様の配列を受け取ります。この配列は読み取り専用であり、情報提供のみに利用されます。
Vitestが実行するテストファイルを見つけられなかった場合、このイベントは空の配列で呼び出され、その後すぐにonTestRunEnd
が呼び出されます。
例
import type { Reporter, TestSpecification } from 'vitest/node';
class MyReporter implements Reporter {
onTestRunStart(specifications: TestSpecification[]) {
console.log(specifications.length, 'test files will run');
}
}
export default new MyReporter();
非推奨
このメソッドはVitest 3で追加され、onPathsCollected
とonSpecsCollected
の両方を置き換えました。これらは現在非推奨です。
onTestRunEnd
function onTestRunEnd(
testModules: ReadonlyArray<TestModule>,
unhandledErrors: ReadonlyArray<SerializedError>,
reason: TestRunEndReason
): Awaitable<void>;
このメソッドは、すべてのテストの実行が終了し、カバレッジがすべてのレポートをマージした後(有効になっている場合)に呼び出されます。カバレッジ情報はonCoverage
フックで取得できることに注意してください。
テストモジュールの読み取り専用リストを受け取ります。testModule.children
プロパティを介して反復処理し、状態とエラー(もしあれば)を報告できます。
2番目の引数は、Vitestがどのテストにも関連付けられなかった未処理のエラーの読み取り専用リストです。これらは、プラグインのエラーによりテスト実行の外部で発生したり、非同期関数の副作用としてテスト実行の内部で発生したりする可能性があります(例えば、テストの実行が終了した後にエラーをスローしたタイムアウトなど)。
3番目の引数は、テスト実行が終了した理由を示します。
passed
: テスト実行が正常に終了し、エラーがないfailed
: テスト実行中に少なくとも1つのエラーが発生した(収集中の構文エラーまたはテスト実行中の実際のエラーによる)interrupted
: テストがvitest.cancelCurrentRun
呼び出しによって中断されたか、ターミナルでCtrl+C
が押された(この場合でも失敗したテストが存在する可能性があることに注意してください)
Vitestが実行するテストファイルを見つけられなかった場合、このイベントはモジュールとエラーの空の配列で呼び出され、その状態はconfig.passWithNoTests
の値に依存します。
例
import type {
Reporter,
SerializedError,
TestModule,
TestRunEndReason,
TestSpecification,
} from 'vitest/node';
class MyReporter implements Reporter {
onTestRunEnd(
testModules: ReadonlyArray<TestModule>,
unhandledErrors: ReadonlyArray<SerializedError>,
reason: TestRunEndReason
) {
if (reason === 'passed') {
testModules.forEach(module => console.log(module.moduleId, 'succeeded'));
} else if (reason === 'failed') {
// スイート内のエラーはスキップされる可能性があることに注意
// testSuite.errors() から取得できます
for (const testCase of testModules.children.allTests()) {
if (testCase.result().state === 'failed') {
console.log(
testCase.fullName,
'in',
testCase.module.moduleId,
'failed'
);
console.log(testCase.result().errors);
}
}
} else {
console.log('test run was interrupted, skipping report');
}
}
}
export default new MyReporter();
非推奨
このメソッドはVitest 3で追加され、onFinished
を置き換えました。これは現在非推奨です。
onCoverage
function onCoverage(coverage: unknown): Awaitable<void>;
このフックは、カバレッジ結果が処理された後に呼び出されます。カバレッジプロバイダーのレポーターは、このフックの後に呼び出されます。coverage
の型はcoverage.provider
に依存します。Vitestのデフォルトの組み込みプロバイダーの場合、istanbul-lib-coverage
パッケージから型をインポートできます。
import type { CoverageMap } from 'istanbul-lib-coverage';
declare function onCoverage(coverage: CoverageMap): Awaitable<void>;
Vitestがカバレッジを実行しなかった場合、このフックは呼び出されません。
onTestModuleQueued
function onTestModuleQueued(testModule: TestModule): Awaitable<void>;
このメソッドは、Vitestがセットアップファイルとテストモジュール自体をインポートする直前に呼び出されます。これは、testModule
にはまだchildren
がないことを意味しますが、次の実行テストとして報告を開始できます。
onTestModuleCollected
function onTestModuleCollected(testModule: TestModule): Awaitable<void>;
このメソッドは、ファイル内のすべてのテストが収集されたときに呼び出されます。つまり、testModule.children
コレクションが設定されますが、テストにはまだ結果がありません。
onTestModuleStart
function onTestModuleStart(testModule: TestModule): Awaitable<void>;
このメソッドは、onTestModuleCollected
の直後に呼び出されます。ただし、Vitestが収集モード(CLIのvitest.collect()
またはvitest collect
)で実行されている場合は、実行するテストがないため、呼び出されません。
onTestModuleEnd
function onTestModuleEnd(testModule: TestModule): Awaitable<void>;
このメソッドは、モジュール内のすべてのテストの実行が終了したときに呼び出されます。つまり、testModule.children
内のすべてのテストは、pending
ではないtest.result()
を持つことになります。
onHookStart
function onHookStart(context: ReportedHookContext): Awaitable<void>;
このメソッドは、以下のいずれかのフックの実行が開始されたときに呼び出されます。
beforeAll
afterAll
beforeEach
afterEach
beforeAll
またはafterAll
が開始された場合、entity
はTestSuite
またはTestModule
のいずれかになります。
beforeEach
またはafterEach
が開始された場合、entity
は常にTestCase
になります。
WARNING
onHookStart
メソッドは、フックがテスト実行中に実行されなかった場合は呼び出されません。
onHookEnd
function onHookEnd(context: ReportedHookContext): Awaitable<void>;
このメソッドは、以下のいずれかのフックの実行が終了したときに呼び出されます。
beforeAll
afterAll
beforeEach
afterEach
beforeAll
またはafterAll
が終了した場合、entity
はTestSuite
またはTestModule
のいずれかになります。
beforeEach
またはafterEach
が終了した場合、entity
は常にTestCase
になります。
WARNING
onHookEnd
メソッドは、フックがテスト実行中に実行されなかった場合は呼び出されません。
onTestSuiteReady
function onTestSuiteReady(testSuite: TestSuite): Awaitable<void>;
このメソッドは、スイートがテストの実行を開始する前に呼び出されます。このメソッドは、スイートがスキップされた場合にも呼び出されます。
ファイルにスイートがない場合、このメソッドは呼び出されません。このユースケースをカバーするには、onTestModuleStart
の使用を検討してください。
onTestSuiteResult
function onTestSuiteResult(testSuite: TestSuite): Awaitable<void>;
このメソッドは、スイートがテストの実行を終了した後に呼び出されます。このメソッドは、スイートがスキップされた場合にも呼び出されます。
ファイルにスイートがない場合、このメソッドは呼び出されません。このユースケースをカバーするには、onTestModuleEnd
の使用を検討してください。
onTestCaseReady
function onTestCaseReady(testCase: TestCase): Awaitable<void>;
このメソッドは、テストが実行を開始する前、またはスキップされたときに呼び出されます。beforeEach
およびafterEach
フックは、結果に影響を与える可能性があるため、テストの一部と見なされることに注意してください。
WARNING
onTestCaseReady
が呼び出された時点で、testCase.result()
がすでにpassed
またはfailed
の状態になっている可能性があることに注意してください。これは、テストの実行が速すぎて、onTestCaseReady
とonTestCaseResult
の両方が同じマイクロタスクで実行されるようにスケジュールされた場合に発生する可能性があります。
onTestCaseResult
function onTestCaseResult(testCase: TestCase): Awaitable<void>;
このメソッドは、テストの実行が終了したとき、またはスキップされたときに呼び出されます。これは、afterEach
フックがある場合、それが終了した後に呼び出されることに注意してください。
この時点で、testCase.result()
は保留中ではない状態になります。
onTestAnnotate 3.2.0+
function onTestAnnotate(
testCase: TestCase,
annotation: TestAnnotation
): Awaitable<void>;
onTestAnnotate
フックは、context.annotate
メソッドに関連付けられています。annotate
が呼び出されると、Vitestはそれをシリアル化し、同じアタッチメントをメインスレッドに送信し、レポーターがそれと対話できるようにします。
パスが指定されている場合、Vitestはそれを別のディレクトリ(attachmentsDir
で設定)に保存し、path
プロパティを変更してそれを参照するようにします。