c8 の使い方 — Node.js 組み込みのV8カバレッジでテストカバレッジを計測する

一言でいうと

c8 は、Node.js に組み込まれた V8 のネイティブカバレッジ機能（NODE_V8_COVERAGE）を利用して、コードカバレッジレポートを生成する CLI ツールです。従来の Istanbul（nyc）のようなコードの変換（instrumentation）が不要で、高速かつ正確なカバレッジ計測が可能です。

どんな時に使う？

1. テストスイートのカバレッジ計測 — Jest・Vitest・Mocha・AVA・Node.js 組み込みテストランナーなど、任意のテストフレームワークと組み合わせてカバレッジを取得したいとき
2. TypeScript / ESM プロジェクトのカバレッジ — nyc では設定が煩雑になりがちな ESM（ES Modules）や TypeScript プロジェクトで、シンプルにカバレッジを取りたいとき
3. CI/CD パイプラインでのカバレッジチェック — カバレッジの閾値を設定し、基準を満たさない場合にビルドを失敗させたいとき

インストール

# npm
npm install -D c8

# yarn
yarn add -D c8

# pnpm
pnpm add -D c8

基本的な使い方

c8 は CLI ツールとして、テスト実行コマンドの前に c8 を付けるだけで使えます。

# Node.js 組み込みテストランナーと組み合わせる例
npx c8 node --test src/**/*.test.ts

# Mocha と組み合わせる例
npx c8 mocha src/**/*.test.ts

# 任意のスクリプトのカバレッジを取る
npx c8 node src/index.js

package.json の scripts に登録するのが一般的です。

{
  "scripts": {
    "test": "node --test src/**/*.test.ts",
    "test:coverage": "c8 node --test src/**/*.test.ts",
    "test:coverage:report": "c8 report --reporter=html"
  }
}

実行すると、ターミナルにテキスト形式のカバレッジサマリーが表示されます。

----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
----------|---------|----------|---------|---------|-------------------
All files |   85.71 |      100 |   66.67 |   85.71 |
 index.ts |   85.71 |      100 |   66.67 |   85.71 | 12-14
----------|---------|----------|---------|---------|-------------------

よく使う API（CLI オプション）

c8 は CLI ツールのため、主要な機能はコマンドラインオプションとして提供されます。

1. --reporter — レポート形式の指定

Istanbul 互換のレポーターを指定できます。複数指定も可能です。

# HTML レポートとテキスト出力を同時に生成
npx c8 --reporter=html --reporter=text --reporter=lcov node --test src/**/*.test.ts

主なレポーター:

• text — ターミナルにテーブル表示（デフォルト）
• html — ブラウザで閲覧できる HTML レポート
• lcov — Codecov / Coveralls などの外部サービス連携用
• json — JSON 形式
• text-summary — サマリーのみのテキスト出力

2. --check-coverage / --lines / --branches / --functions — カバレッジ閾値チェック

カバレッジが指定した閾値を下回ると、終了コード 1 で失敗します。CI での品質ゲートに最適です。

# 行カバレッジ80%、ブランチカバレッジ70%、関数カバレッジ80%を要求
npx c8 --check-coverage --lines 80 --branches 70 --functions 80 node --test src/**/*.test.ts

3. --include / --exclude — 対象ファイルのフィルタリング

カバレッジ計測の対象・除外をグロブパターンで指定します。

# src ディレクトリのみを対象にし、テストファイルは除外
npx c8 --include="src/**/*.ts" --exclude="src/**/*.test.ts" --exclude="src/**/*.spec.ts" node --test src/**/*.test.ts

4. --all — テストで実行されなかったファイルもレポートに含める

デフォルトでは、テスト中に実行（require / import）されたファイルのみがレポートに含まれます。--all を指定すると、--include で指定した範囲のすべてのファイルが対象になり、未テストファイルが 0% として表示されます。

npx c8 --all --include="src/**/*.ts" node --test src/**/*.test.ts

5. --reports-dir / c8 report — レポート出力先とレポート再生成

# カバレッジデータの出力先を指定
npx c8 --reports-dir=./coverage node --test src/**/*.test.ts

# 既存のカバレッジデータから別形式のレポートを再生成
npx c8 report --reporter=html --reports-dir=./coverage

.c8rc.json による設定ファイル

CLI オプションが増えてきたら、設定ファイルにまとめられます。

{
  "all": true,
  "include": ["src/**/*.ts"],
  "exclude": ["src/**/*.test.ts", "src/**/*.spec.ts", "src/types/**"],
  "reporter": ["text", "html", "lcov"],
  "check-coverage": true,
  "lines": 80,
  "branches": 70,
  "functions": 80,
  "reports-dir": "./coverage"
}

package.json 内に "c8" キーで記述することも可能です。

{
  "c8": {
    "all": true,
    "include": ["src/**/*.ts"],
    "reporter": ["text", "html"]
  }
}

類似パッケージとの比較

結論: 新規プロジェクトで nyc を選ぶ理由はほぼありません。Vitest を使っているなら組み込みカバレッジ（内部で c8 / V8 を利用可能）が便利ですが、テストランナーに依存しない汎用的なカバレッジツールとしては c8 が最有力です。

注意点・Tips

1. ソースマップが必要

TypeScript やバンドラーを使っている場合、正確な行番号マッピングにはソースマップが必要です。tsconfig.json で "sourceMap": true を設定してください。

{
  "compilerOptions": {
    "sourceMap": true
  }
}

2. --all を付けないと実態が見えない

デフォルトではテスト中に import されたファイルしかレポートに含まれません。「カバレッジ 100%」と表示されても、実はテストされていないファイルが大量にある可能性があります。本番運用では --all を必ず付けましょう。

3. node_modules は自動的に除外される

デフォルトの除外パターンに node_modules が含まれているため、通常は明示的に除外する必要はありません。

4. Node.js のバージョンに注意

c8 v11 は Node.js 18 以上を要求します（V8 カバレッジ機能の安定性のため）。古い Node.js を使っている場合は、c8 の対応バージョンを確認してください。

※ バージョン要件は c8 v11.0.0 時点の情報です。最新の要件は公式リポジトリを確認してください。

5. coverage ディレクトリを .gitignore に追加

# Coverage reports
coverage/
.c8_output/

c8 は中間データを .c8_output/ に、レポートを coverage/ に出力します。どちらもバージョン管理に含める必要はありません。

6. マージ機能で複数プロセスのカバレッジを統合

E2E テストなど、複数のプロセスにまたがるカバレッジを統合できます。

# 環境変数で V8 カバレッジの出力先を指定して実行
NODE_V8_COVERAGE=./coverage-data node src/server.js &
# テスト実行後にサーバーを停止し、レポートを生成
npx c8 report --temp-directory=./coverage-data --reporter=html

まとめ

c8 は、Node.js の V8 エンジンに組み込まれたネイティブカバレッジ機能を活用することで、コードの変換なしに高速かつ正確なカバレッジレポートを生成できるツールです。ESM・TypeScript との相性が良く、設定もシンプルなため、nyc からの移行先として最適です。テストランナーを問わず c8 <コマンド> と付けるだけで使えるので、まずは既存プロジェクトで試してみてください。