nyc の使い方 — JavaScriptコードカバレッジ計測の定番CLI

一言でいうと

nyc は、JavaScript/TypeScriptのコードカバレッジ（テストがコードのどの部分を実行したか）を計測するコマンドラインツールです。内部でIstanbulのカバレッジ計測エンジンを使用し、任意のテストランナーと組み合わせてカバレッジレポートを生成できます。

---

どんな時に使う？

1. テストのカバレッジ率を可視化したい時 — Mocha、AVA、tap などのテストランナーと組み合わせて、行・関数・分岐のカバレッジを計測する
2. CI/CDでカバレッジしきい値を強制したい時 — カバレッジが一定の割合を下回ったらビルドを失敗させる品質ゲートとして利用する
3. サブプロセスを含むカバレッジを統合したい時 — child_process.fork() で生成されたサブプロセスのカバレッジも自動的に収集・統合できる

---

インストール

# npm
npm install --save-dev nyc

# yarn
yarn add --dev nyc

# pnpm
pnpm add --save-dev nyc

---

基本的な使い方

nyc は任意のコマンドの前に nyc を付けるだけで、そのプロセスのカバレッジを計測します。

Mocha と組み合わせる例

// package.json
{
  "scripts": {
    "test": "nyc mocha"
  }
}

npm test

実行すると、テスト結果の後にカバレッジサマリーが表示されます。

----------|---------|----------|---------|---------|-------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
----------|---------|----------|---------|---------|-------------------
All files |   85.71 |      75  |     100 |   85.71 |
 index.js |   85.71 |      75  |     100 |   85.71 | 12-13
----------|---------|----------|---------|---------|-------------------

TypeScript プロジェクトでの使い方

TypeScript で使う場合は、@istanbuljs/nyc-config-typescript と ts-node を併用します。

npm install --save-dev @istanbuljs/nyc-config-typescript ts-node source-map-support

// .nycrc.json
{
  "extends": "@istanbuljs/nyc-config-typescript",
  "all": true,
  "include": ["src/**/*.ts"],
  "exclude": ["src/**/*.spec.ts"],
  "reporter": ["text", "html", "lcov"]
}

// package.json
{
  "scripts": {
    "test": "nyc mocha --require ts-node/register 'src/**/*.spec.ts'"
  }
}

---

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

nyc はCLIツールのため、主にコマンドラインオプションまたは設定ファイル（.nycrc、.nycrc.json、package.json の nyc フィールド）で制御します。

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

nyc --reporter=text --reporter=html --reporter=lcov mocha

// .nycrc.json
{
  "reporter": ["text", "html", "lcov", "cobertura"]
}

主なレポーター:

2. --check-coverage / --branches / --lines / --functions — カバレッジしきい値の強制

nyc --check-coverage --branches 80 --lines 90 --functions 85 mocha

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

// .nycrc.json
{
  "check-coverage": true,
  "branches": 80,
  "lines": 90,
  "functions": 85,
  "statements": 90
}

3. --include / --exclude — 計測対象の制御

nyc --include='src/**' --exclude='src/**/*.spec.js' mocha

// .nycrc.json
{
  "include": ["src/**/*.js", "src/**/*.ts"],
  "exclude": [
    "**/*.spec.js",
    "**/*.test.js",
    "**/test/**",
    "**/node_modules/**"
  ]
}

Tips: --all フラグを付けると、テストで一度も require / import されなかったファイルもカバレッジ 0% として計上されます。実態を正確に把握するために推奨です。

nyc --all --include='src/**' mocha

4. nyc report — 既存のカバレッジデータからレポートを再生成

# まずカバレッジデータだけ収集
nyc --reporter=none mocha

# 後からレポートを生成
nyc report --reporter=html --reporter=text

これは、テスト実行とレポート生成を分離したい場合に便利です。例えば、複数のテストスイートのカバレッジを統合してからレポートを出す場合に使います。

5. nyc merge — 複数のカバレッジデータを統合

# 複数のカバレッジJSONを1つに統合
nyc merge ./coverage-results ./merged-coverage.json

# 統合したデータからレポート生成
nyc report --temp-dir ./merged-coverage --reporter=html

マイクロサービスや複数テストスイートのカバレッジを1つのレポートにまとめたい場合に使います。

---

類似パッケージとの比較

補足: ESM（ES Modules）を主体とするプロジェクトでは、V8ネイティブカバレッジを使う c8 の方がセットアップが簡単です。CommonJSベースのプロジェクトでは nyc が依然として堅実な選択肢です。

---

注意点・Tips

1. .nyc_output ディレクトリを .gitignore に追加する

nyc はカバレッジの生データを .nyc_output/ に保存します。coverage/ ディレクトリと合わせて .gitignore に追加しましょう。

# .gitignore
.nyc_output/
coverage/

2. --all フラグは必ず付ける

デフォルトでは、テスト中に require / import されたファイルしかカバレッジに含まれません。--all を付けないと、テストされていないファイルがレポートから完全に消え、カバレッジ率が実態より高く見えてしまいます。

3. キャッシュの問題に注意

カバレッジ結果がおかしい場合、キャッシュが原因のことがあります。

# キャッシュと出力をクリーンアップ
nyc clean
rm -rf .nyc_output coverage

4. 設定ファイルの優先順位

nyc は以下の順序で設定を読み込みます（先に見つかったものが優先）:

1. コマンドライン引数
2. package.json の "nyc" フィールド
3. .nycrc / .nycrc.json / .nycrc.yml / nyc.config.js

設定が散在すると混乱するため、.nycrc.json に一元化するのがおすすめです。

5. per-file オプションでファイル単位のしきい値を強制

// .nycrc.json
{
  "check-coverage": true,
  "per-file": true,
  "lines": 80
}

per-file: true にすると、プロジェクト全体ではなく各ファイルが個別にしきい値を満たす必要があります。一部のファイルだけカバレッジが極端に低い状態を防げます。

6. ESM プロジェクトでの制限

nyc は内部で require フックを使ってコードを変換（instrument）するため、純粋なESM（"type": "module"）プロジェクトではうまく動作しないことがあります。ESM主体のプロジェクトでは c8 への移行を検討してください。

---

まとめ

nyc は Istanbul ベースのコードカバレッジ計測CLIとして長年の実績があり、Mocha・AVA・tap など任意のテストランナーと組み合わせて使える汎用性が最大の強みです。サブプロセスのカバレッジ自動収集や柔軟なしきい値設定など、CI/CD パイプラインでの品質管理に必要な機能が一通り揃っています。ただし、ESM 主体の新規プロジェクトでは c8 も有力な選択肢となるため、プロジェクトのモジュール形式に応じて使い分けるのが良いでしょう。