カバレッジ
Vitest は、v8 を介したネイティブコードカバレッジと、istanbul を介したインストルメントされたコードカバレッジの両方をサポートしています。
カバレッジプロバイダー
v8 と istanbul の両プロバイダーが利用可能で、これらはオプションです。デフォルトでは v8 が使用されます。
test.coverage.provider を v8 または istanbul に設定することで、カバレッジツールを選択できます。
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
coverage: {
provider: 'istanbul', // または 'v8'
},
},
});Vitest プロセスを開始すると、対応するサポートパッケージの自動インストールが提案されます。
手動でインストールする場合は、以下のコマンドを使用します。
npm i -D @vitest/coverage-v8npm i -D @vitest/coverage-istanbulV8 プロバイダー
INFO
以下の V8 カバレッジに関する説明は Vitest に固有のものであり、他のテストランナーには適用されません。 v3.2.0 以降、Vitest は V8 カバレッジに AST ベースのカバレッジ再マッピング を使用しており、Istanbul と同等のカバレッジレポートを生成します。
これにより、ユーザーは V8 カバレッジの速度と Istanbul カバレッジの精度を同時に享受できます。
デフォルトでは、Vitest は 'v8' カバレッジプロバイダーを使用します。 このプロバイダーは、Node.js、Deno、または Google Chrome などの Chromium ベースのブラウザで動作する V8 エンジン 上に実装された Javascript ランタイムを必要とします。
カバレッジ収集は、ランタイム中に V8 に対して行われます。Node.js では node:inspector を使用し、ブラウザでは Chrome DevTools Protocol を使用して指示します。ソースファイルは、事前のインストルメンテーションなしでそのまま実行できます。
- ✅ 推奨されるオプション
- ✅ 事前トランスパイルステップ不要。テストファイルはそのまま実行可能。
- ✅ Istanbul よりも実行速度が速い。
- ✅ Istanbul よりもメモリ使用量が少ない。
- ✅ カバレッジレポートの精度は Istanbul と同等（Vitest
v3.2.0以降、AST ベースの再マッピングによる）。 - ⚠️ 場合によっては Istanbul よりも遅くなることがあります。例えば、多数の異なるモジュールをロードする場合などです。V8 は特定のモジュールへのカバレッジ収集の制限をサポートしていません。
- ⚠️ V8 エンジンに起因するいくつかの軽微な制限がある。
ast-v8-to-istanbul| Limitations を参照。 - ❌ Firefox や Bun など、V8 を使用しない環境では動作しません。また、Cloudflare Workers など、プロファイラー経由で V8 カバレッジを公開しない環境でも動作しません。
Istanbul プロバイダー
Istanbul コードカバレッジツールは 2012 年から存在し、13年以上の実績があり広く使用されています。 このプロバイダーは、カバレッジ追跡がユーザーのソースファイルをインストルメントすることによって行われるため、あらゆる JavaScript ランタイムで動作します。
実際には、ソースファイルをインストルメントするとは、ユーザーのファイルに JavaScript コードを追加することです。
// ブランチと関数カバレッジカウンターの簡略化された例
const coverage = {
branches: { 1: [0, 0] },
functions: { 1: 0 },
}
export function getUsername(id) {
// これが呼び出されると、関数カバレッジが増加する
coverage.functions['1']++;
if (id == null) {
// これが呼び出されると、ブランチカバレッジが増加する
coverage.branches['1'][0]++;
throw new Error('User ID is required');
}
// if文の条件が満たされない場合、暗黙の else カバレッジが増加する
coverage.branches['1'][1]++;
return database.getUser(id);
}
globalThis.__VITEST_COVERAGE__ ||= {};
globalThis.__VITEST_COVERAGE__[filename] = coverage; - ✅ あらゆる JavaScript ランタイムで動作する
- ✅ 13 年以上にわたり広く使用され、高い実績があります。
- ✅ 特定のケースでは V8 より高速。カバレッジインストルメンテーションは特定のファイルに限定できます。これは、V8 がすべてのモジュールをインストルメントするのとは対照的です。
- ❌ 事前インストルメンテーションステップが必要です。
- ❌ インストルメンテーションのオーバーヘッドにより、実行速度が V8 よりも遅くなります。
- ❌ インストルメンテーションによりファイルサイズが増加します。
- ❌ メモリ使用量が V8 よりも高くなります。
カバレッジ設定
TIP
設定ファイルで coverage.include を常に定義することをお勧めします。 これにより、Vitest が coverage.all で選択するファイルの量を減らすことができます。
カバレッジを有効にしてテストを実行するには、CLI で --coverage フラグを渡します。 デフォルトでは、['text', 'html', 'clover', 'json'] のレポーターが使用されます。
{
"scripts": {
"test": "vitest",
"coverage": "vitest run --coverage"
}
}設定するには、設定ファイルで test.coverage オプションを設定します。
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
coverage: {
reporter: ['text', 'json', 'html'],
},
},
});カスタムカバレッジレポーター
test.coverage.reporter にパッケージ名または絶対パスを指定することで、カスタムカバレッジレポーターを使用できます。
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
coverage: {
reporter: [
// NPM パッケージ名を使用してレポーターを指定します。
['@vitest/custom-coverage-reporter', { someOption: true }],
// ローカルパスを使用してレポーターを指定します。
'/absolute/path/to/custom-reporter.cjs',
],
},
},
});カスタムレポーターは Istanbul によってロードされ、そのレポーターインターフェースに準拠している必要があります。参照として 組み込みレポーターの実装 を参照してください。
const { ReportBase } = require('istanbul-lib-report');
module.exports = class CustomReporter extends ReportBase {
constructor(opts) {
super();
// 設定から渡されたオプションはここで利用できます。
this.file = opts.file;
}
onStart(root, context) {
this.contentWriter = context.writer.writeFile(this.file);
this.contentWriter.println('Start of custom coverage report');
}
onEnd() {
this.contentWriter.println('End of custom coverage report');
this.contentWriter.close();
}
};カスタムカバレッジプロバイダー
test.coverage.provider に 'custom' を渡すことで、独自のカスタムカバレッジプロバイダーを指定することもできます。
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
coverage: {
provider: 'custom',
customProviderModule: 'my-custom-coverage-provider',
},
},
});カスタムプロバイダーには customProviderModule オプションが必要です。このオプションには、CoverageProviderModule をロードするモジュール名またはパスを指定します。デフォルトエクスポートとして CoverageProviderModule を実装するオブジェクトをエクスポートする必要があります。
import type {
CoverageProvider,
CoverageProviderModule,
ResolvedCoverageOptions,
Vitest,
} from 'vitest';
const CustomCoverageProviderModule: CoverageProviderModule = {
getProvider(): CoverageProvider {
return new CustomCoverageProvider();
},
// CoverageProviderModule の残りの部分を実装します...
};
class CustomCoverageProvider implements CoverageProvider {
name = 'custom-coverage-provider';
options!: ResolvedCoverageOptions;
initialize(ctx: Vitest) {
this.options = ctx.config.coverage;
}
// CoverageProvider の残りの部分を実装します...
}
export default CustomCoverageProviderModule;詳細については、型定義を参照してください。
デフォルトのカバレッジフォルダの場所を変更する
カバレッジレポートを実行すると、プロジェクトのルートディレクトリに coverage フォルダが作成されます。別のディレクトリに移動したい場合は、vitest.config.js ファイルの test.coverage.reportsDirectory プロパティを使用します。
import { defineConfig } from 'vite';
export default defineConfig({
test: {
coverage: {
reportsDirectory: './tests/unit/coverage',
},
},
});コードの無視
両方のカバレッジプロバイダーには、カバレッジレポートからコードを無視する方法が用意されています。
v8ìstanbulexperimentalAstAwareRemapping: trueを使用するv8の場合は、ast-v8-to-istanbul | Ignoring code を参照してください。
TypeScript を使用する場合、ソースコードは esbuild を使用してトランスパイルされ、すべてのコメントが削除されます (esbuild#516)。 合法的なコメント と見なされるコメントは保持されます。
無視ヒントに @preserve キーワードを含めることができます。 これらの無視ヒントが最終的な本番ビルドにも含まれる可能性があることに注意してください。
-/* istanbul ignore if */
+/* istanbul ignore if -- @preserve */
if (condition) {
-/* v8 ignore if */
+/* v8 ignore if -- @preserve */
if (condition) {その他のオプション
カバレッジのすべての設定可能なオプションについては、カバレッジ設定リファレンス を参照してください。
カバレッジのパフォーマンス
コードカバレッジの生成がプロジェクトで遅い場合は、テストパフォーマンスのプロファイル | コードカバレッジ を参照してください。
Vitest UI
Vitest UI でカバレッジレポートを確認できます。
Vitest UI は、カバレッジレポートが明示的に有効化され、HTML カバレッジレポーターが存在する場合にカバレッジレポートを有効にします。それ以外の場合は利用できません。
- 設定ファイルで
coverage.enabled=trueを有効にするか、--coverage.enabled=trueフラグを付けて Vitest を実行します。 coverage.reporterリストにhtmlを追加します。カバレッジレポートをサブディレクトリに配置するためにsubdirオプションを有効にすることも可能です。
