レポーター
Vitest は、テスト出力を様々な形式で表示するための組み込みレポーターを複数提供しており、さらにカスタムレポーターの使用も可能です。レポーターは、--reporter コマンドラインオプションを使用するか、設定ファイルの reporters プロパティに含めることで選択できます。レポーターが指定されていない場合、Vitest は後述の default レポーターを使用します。
コマンドラインでのレポーター使用例：
npx vitest --reporter=verbosevitest.config.ts でのレポーター使用例：
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
reporters: ['verbose'],
},
});一部のレポーターは、追加オプションを渡すことでカスタマイズできます。レポーター固有のオプションについては、以下のセクションで説明します。
export default defineConfig({
test: {
reporters: ['default', ['junit', { suiteName: 'UI tests' }]],
},
});レポーター出力
デフォルトでは、Vitest のレポーターは出力をターミナルに表示します。json、html、または junit レポーターを使用する場合、Vite 設定ファイルまたは CLI で outputFile 設定オプションを含めることで、テスト出力をファイルに書き出すことができます。
npx vitest --reporter=json --outputFile=./test-output.jsonexport default defineConfig({
test: {
reporters: ['json'],
outputFile: './test-output.json',
},
});レポーターの組み合わせ
複数のレポーターを同時に使用して、テスト結果を異なる形式で出力できます。例：
npx vitest --reporter=json --reporter=defaultexport default defineConfig({
test: {
reporters: ['json', 'default'],
outputFile: './test-output.json',
},
});上記の例では、テスト結果をデフォルトのスタイルでターミナルに表示するとともに、指定された出力ファイルに JSON 形式で書き込みます。
複数のレポーターを使用する場合、次のように複数の出力ファイルを指定することも可能です。
export default defineConfig({
test: {
reporters: ['junit', 'json', 'verbose'],
outputFile: {
junit: './junit-report.xml',
json: './json-report.json',
},
},
});この例では、個別の JSON および XML レポートを書き出し、さらに詳細なレポートをターミナルに表示します。
組み込みレポーター
デフォルトレポーター
デフォルトでは（つまり、レポーターが指定されていない場合）、Vitest は実行中のテストとそのステータスの概要を画面下部に表示します。スイートが合格すると、そのステータスは概要の上部に表示されます。
レポーターを設定することで、概要を無効にできます。
export default defineConfig({
test: {
reporters: [['default', { summary: false }]],
},
});テスト実行中の出力例：
✓ test/example-1.test.ts (5 tests | 1 skipped) 306ms
✓ test/example-2.test.ts (5 tests | 1 skipped) 307ms
❯ test/example-3.test.ts 3/5
❯ test/example-4.test.ts 1/5
Test Files 2 passed (4)
Tests 10 passed | 3 skipped (65)
Start at 11:01:36
Duration 2.00sテスト完了後の最終出力：
✓ test/example-1.test.ts (5 tests | 1 skipped) 306ms
✓ test/example-2.test.ts (5 tests | 1 skipped) 307ms
✓ test/example-3.test.ts (5 tests | 1 skipped) 307ms
✓ test/example-4.test.ts (5 tests | 1 skipped) 307ms
Test Files 4 passed (4)
Tests 16 passed | 4 skipped (20)
Start at 12:34:32
Duration 1.26s (transform 35ms, setup 1ms, collect 90ms, tests 1.47s, environment 0ms, prepare 267ms)基本レポーター
basic レポーターは、summary 機能を持たない default レポーターと同等です。
npx vitest --reporter=basicexport default defineConfig({
test: {
reporters: ['basic'],
},
});基本レポーターを使用した出力例：
✓ __tests__/file1.test.ts (2) 725ms
✓ __tests__/file2.test.ts (2) 746ms
Test Files 2 passed (2)
Tests 4 passed (4)
Start at 12:34:32
Duration 1.26s (transform 35ms, setup 1ms, collect 90ms, tests 1.47s, environment 0ms, prepare 267ms)詳細レポーター
詳細レポーターは default レポーターと同様ですが、スイートが完了した後に個々のテストも表示します。また、slowTestThreshold よりも長くかかっている現在実行中のテストも表示します。default レポーターと同様に、レポーターを設定することで概要を無効にできます。
npx vitest --reporter=verboseexport default defineConfig({
test: {
reporters: [['verbose', { summary: false }]],
},
});slowTestThreshold がデフォルト値の 300 に設定されている場合のテスト実行中の出力例：
✓ __tests__/example-1.test.ts (2) 725ms
✓ first test file (2) 725ms
✓ 2 + 2 should equal 4
✓ 4 - 2 should equal 2
❯ test/example-2.test.ts 3/5
↳ should run longer than three seconds 1.57s
❯ test/example-3.test.ts 1/5
Test Files 2 passed (4)
Tests 10 passed | 3 skipped (65)
Start at 11:01:36
Duration 2.00s合格したテストスイートの最終ターミナル出力例：
✓ __tests__/file1.test.ts (2) 725ms
✓ first test file (2) 725ms
✓ 2 + 2 should equal 4
✓ 4 - 2 should equal 2
✓ __tests__/file2.test.ts (2) 746ms
✓ second test file (2) 746ms
✓ 1 + 1 should equal 2
✓ 2 - 1 should equal 1
Test Files 2 passed (2)
Tests 4 passed (4)
Start at 12:34:32
Duration 1.26s (transform 35ms, setup 1ms, collect 90ms, tests 1.47s, environment 0ms, prepare 267ms)ドットレポーター
完了した各テストに対して単一のドットを出力し、実行されたすべてのテストを表示しながら最小限の出力を提供します。詳細は失敗したテストのみに提供され、スイートの basic レポーターの概要と共に表示されます。
npx vitest --reporter=dotexport default defineConfig({
test: {
reporters: ['dot'],
},
});合格したテストスイートのターミナル出力例：
....
Test Files 2 passed (2)
Tests 4 passed (4)
Start at 12:34:32
Duration 1.26s (transform 35ms, setup 1ms, collect 90ms, tests 1.47s, environment 0ms, prepare 267ms)JUnit レポーター
テスト結果のレポートを JUnit XML 形式で出力します。ターミナルに表示することも、outputFile 設定オプションを使用して XML ファイルに書き出すことも可能です。
npx vitest --reporter=junitexport default defineConfig({
test: {
reporters: ['junit'],
},
});JUnit XML レポートの例：
<?xml version="1.0" encoding="UTF-8" ?>
<testsuites name="vitest tests" tests="2" failures="1" errors="0" time="0.503">
<testsuite name="__tests__/test-file-1.test.ts" timestamp="2023-10-19T17:41:58.580Z" hostname="My-Computer.local" tests="2" failures="1" errors="0" skipped="0" time="0.013">
<testcase classname="__tests__/test-file-1.test.ts" name="first test file > 2 + 2 should equal 4" time="0.01">
<failure message="expected 5 to be 4 // Object.is equality" type="AssertionError">
AssertionError: expected 5 to be 4 // Object.is equality
❯ __tests__/test-file-1.test.ts:20:28
</failure>
</testcase>
<testcase classname="__tests__/test-file-1.test.ts" name="first test file > 4 - 2 should equal 2" time="0">
</testcase>
</testsuite>
</testsuites>出力される XML には、ネストされた testsuites および testcase タグが含まれています。これらは、レポーターオプション suiteName および classnameTemplate によってカスタマイズすることもできます。classnameTemplate は、テンプレート文字列または関数として指定できます。
classnameTemplate オプションでサポートされているプレースホルダーは次のとおりです。
- filename
- filepath
export default defineConfig({
test: {
reporters: [
[
'junit',
{
suiteName: 'custom suite name',
classnameTemplate: 'filename:{filename} - filepath:{filepath}',
},
],
],
},
});JSON レポーター
Jest の --json オプションと互換性のある JSON 形式でテスト結果のレポートを生成します。ターミナルに表示することも、outputFile 設定オプションを使用してファイルに書き込むこともできます。
npx vitest --reporter=jsonexport default defineConfig({
test: {
reporters: ['json'],
},
});JSON レポートの例：
{
"numTotalTestSuites": 4,
"numPassedTestSuites": 2,
"numFailedTestSuites": 1,
"numPendingTestSuites": 1,
"numTotalTests": 4,
"numPassedTests": 1,
"numFailedTests": 1,
"numPendingTests": 1,
"numTodoTests": 1,
"startTime": 1697737019307,
"success": false,
"testResults": [
{
"assertionResults": [
{
"ancestorTitles": ["", "first test file"],
"fullName": " first test file 2 + 2 should equal 4",
"status": "failed",
"title": "2 + 2 should equal 4",
"duration": 9,
"failureMessages": ["expected 5 to be 4 // Object.is equality"],
"location": {
"line": 20,
"column": 28
},
"meta": {}
}
],
"startTime": 1697737019787,
"endTime": 1697737019797,
"status": "failed",
"message": "",
"name": "/root-directory/__tests__/test-file-1.test.ts"
}
],
"coverageMap": {}
}INFO
Vitest 3 以降、カバレッジが有効になっている場合、JSON レポーターは coverageMap にカバレッジ情報を含めるようになりました。
HTML レポーター
インタラクティブな GUI を介してテスト結果を表示するための HTML ファイルを生成します。ファイルが生成された後、Vitest はローカル開発サーバーを起動し続け、ブラウザでレポートを表示するためのリンクを提供します。
出力ファイルは、outputFile 設定オプションを使用して指定できます。outputFile オプションが指定されていない場合、新しい HTML ファイルが作成されます。
npx vitest --reporter=htmlexport default defineConfig({
test: {
reporters: ['html'],
},
});TIP
このレポーターには、@vitest/ui パッケージのインストールが必要です。
TAP レポーター
Test Anything Protocol (TAP) に従ってレポートを出力します。
npx vitest --reporter=tapexport default defineConfig({
test: {
reporters: ['tap'],
},
});TAP レポートの例：
TAP version 13
1..1
not ok 1 - __tests__/test-file-1.test.ts # time=14.00ms {
1..1
not ok 1 - first test file # time=13.00ms {
1..2
not ok 1 - 2 + 2 should equal 4 # time=11.00ms
---
error:
name: "AssertionError"
message: "expected 5 to be 4 // Object.is equality"
at: "/root-directory/__tests__/test-file-1.test.ts:20:28"
actual: "5"
expected: "4"
...
ok 2 - 4 - 2 should equal 2 # time=1.00ms
}
}TAP フラットレポーター
TAP フラットレポートを出力します。tap レポーターと同様に、テスト結果は TAP 標準に従ってフォーマットされますが、テストスイートはネストされた階層ではなくフラットなリストとしてフォーマットされます。
npx vitest --reporter=tap-flatexport default defineConfig({
test: {
reporters: ['tap-flat'],
},
});TAP フラットレポートの例：
TAP version 13
1..2
not ok 1 - __tests__/test-file-1.test.ts > first test file > 2 + 2 should equal 4 # time=11.00ms
---
error:
name: "AssertionError"
message: "expected 5 to be 4 // Object.is equality"
at: "/root-directory/__tests__/test-file-1.test.ts:20:28"
actual: "5"
expected: "4"
...
ok 2 - __tests__/test-file-1.test.ts > first test file > 4 - 2 should equal 2 # time=0.00msハングプロセスレポーター
Vitest が安全に終了するのを妨げているハングプロセスがある場合、そのリストを表示します。hanging-process レポーター自体はテスト結果を表示しませんが、テスト実行中にプロセスを監視するために他のレポーターと組み合わせて利用できます。このレポーターの使用はリソースを大量に消費する可能性があるため、Vitest が一貫してプロセスを終了できない状況でのデバッグ目的に限定して使用することが推奨されます。
npx vitest --reporter=hanging-processexport default defineConfig({
test: {
reporters: ['hanging-process'],
},
});Github Actions レポーター
テスト失敗のアノテーションを提供するワークフローコマンドを出力します。このレポーターは、process.env.GITHUB_ACTIONS === 'true' の場合、default レポーターと同時に自動的に有効になります。
デフォルト以外のレポーターを設定する場合、github-actions を明示的に追加する必要があります。
export default defineConfig({
test: {
reporters: process.env.GITHUB_ACTIONS ? ['dot', 'github-actions'] : ['dot'],
},
});onWritePath オプションを使用すると、GitHub のアノテーションコマンド形式で出力されるファイルパスをカスタマイズすることが可能です。これは、Vitest を Docker などのコンテナ化された環境で実行する場合に、ファイルパスが GitHub Actions 環境のパスと一致しない場合に有用です。
export default defineConfig({
test: {
reporters: process.env.GITHUB_ACTIONS
? [
'default',
[
'github-actions',
{
onWritePath(path) {
return path.replace(
/^\/app\//,
`${process.env.GITHUB_WORKSPACE}/`
);
},
},
],
]
: ['default'],
},
});Blob レポーター
テスト結果をマシンに保存し、後で --merge-reports コマンドを使用してマージできるようにします。 デフォルトでは、すべての結果を .vitest-reports フォルダーに保存しますが、これは --outputFile または --outputFile.blob フラグで上書き可能です。
npx vitest --reporter=blob --outputFile=reports/blob-1.json--shard フラグを使用して異なるマシンで Vitest を実行している場合は、このレポーターの利用を推奨します。 すべての blob レポートは、CI パイプラインの最後に --merge-reports コマンドを使用して他の任意のレポート形式にマージ可能です。
npx vitest --merge-reports=reports --reporter=json --reporter=defaultTIP
--reporter=blob と --merge-reports の両方は、ウォッチモードでは動作しません。
カスタムレポーター
NPM からインストールされたサードパーティのカスタムレポーターは、レポーターオプションでパッケージ名を指定することで利用できます。
npx vitest --reporter=some-published-vitest-reporterexport default defineConfig({
test: {
reporters: ['some-published-vitest-reporter'],
},
});さらに、独自の カスタムレポーターを定義し、ファイルパスを指定して使用することもできます。
npx vitest --reporter=./path/to/reporter.tsカスタムレポーターは、Reporter インターフェースを実装する必要があります。