Bun のコードカバレッジ

Bun のテストランナーは、組み込みのコードカバレッジレポート機能をサポートしています。これにより、コードベースのどの程度がテストでカバーされているかを確認し、現在十分にテストされていない領域を見つけることが簡単になります。

カバレッジの有効化

bun:test は、テストでカバーされているコードの行を確認できます。この機能を使用するには、CLI に --coverage を渡します。コンソールにカバレッジレポートを出力します。

bash

bun test --coverage

-------------|---------|---------|-------------------
File         | % Funcs | % Lines | Uncovered Line #s
-------------|---------|---------|-------------------
All files    |   38.89 |   42.11 |
 index-0.ts  |   33.33 |   36.84 | 10-15,19-24
 index-1.ts  |   33.33 |   36.84 | 10-15,19-24
 index-10.ts |   33.33 |   36.84 | 10-15,19-24
 index-2.ts  |   33.33 |   36.84 | 10-15,19-24
 index-3.ts  |   33.33 |   36.84 | 10-15,19-24
 index-4.ts  |   33.33 |   36.84 | 10-15,19-24
 index-5.ts  |   33.33 |   36.84 | 10-15,19-24
 index-6.ts  |   33.33 |   36.84 | 10-15,19-24
 index-7.ts  |   33.33 |   36.84 | 10-15,19-24
 index-8.ts  |   33.33 |   36.84 | 10-15,19-24
 index-9.ts  |   33.33 |   36.84 | 10-15,19-24
 index.ts    |  100.00 |  100.00 |
-------------|---------|---------|-------------------

デフォルトで有効化

デフォルトでカバレッジレポートを常に有効にするには、bunfig.toml に次の行を追加します。

toml

[test]
# 常にカバレッジを有効にする
coverage = true

デフォルトでは、カバレッジレポートにはテストファイルが含まれ、ソースマップは除外されます。これは通常望ましい動作ですが、bunfig.toml でそれ以外に設定できます。

toml

[test]
coverageSkipTestFiles = true  # デフォルト false

カバレッジしきい値

bunfig.toml でカバレッジしきい値を指定できます。テストスイートがこのしきい値に達しない場合、bun test は失敗を示すために 0 以外の終了コードで終了します。

単純なしきい値

toml

[test]
# 行レベルと関数レベルの 90% カバレッジを要求する場合
coverageThreshold = 0.9

詳細なしきい値

toml

[test]
# 行と関数の異なるしきい値を設定する場合
coverageThreshold = { lines = 0.9, functions = 0.9, statements = 0.9 }

これらのいずれかを設定すると fail_on_low_coverage が有効になり、カバレッジがしきい値を下回るとテスト実行が失敗します。

カバレッジレポーター

デフォルトでは、カバレッジレポートはコンソールに出力されます。

CI 環境や他のツールのための永続的なカバレッジレポートについては、--coverage-reporter=lcov CLI オプションまたは bunfig.toml の coverageReporter オプションを渡すことができます。

toml

[test]
coverageReporter = ["text", "lcov"]  # デフォルト ["text"]
coverageDir = "path/to/somewhere"    # デフォルト "coverage"

利用可能なレポーター

レポーター	説明
`text`	カバレッジのテキスト要約をコンソールに出力
`lcov`	カバレッジを lcov 形式で保存

LCOV カバレッジレポーター

lcov レポートを生成するには、lcov レポーターを使用できます。これにより、coverage ディレクトリに lcov.info ファイルが生成されます。

toml

[test]
coverageReporter = "lcov"

bash

# または CLI 経由
bun test --coverage --coverage-reporter=lcov

LCOV 形式は、さまざまなツールやサービスで広くサポートされています。

コードエディター: VS Code 拡張機能でインラインカバレッジを表示
CI/CD サービス: GitHub Actions、GitLab CI、CircleCI
カバレッジサービス: Codecov、Coveralls
IDE: WebStorm、IntelliJ IDEA

GitHub Actions での LCOV の使用

yaml

name: Test with Coverage
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test --coverage --coverage-reporter=lcov
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info

カバレッジからのファイルの除外

テストファイルのスキップ

デフォルトでは、テストファイル自体がカバレッジレポートに含まれます。次を使用して除外できます。

toml

[test]
coverageSkipTestFiles = true  # デフォルト false

これにより、テストパターン（例：*.test.ts、*.spec.js）に一致するファイルがカバレッジレポートから除外されます。

特定のパスとパターンの無視

coveragePathIgnorePatterns を使用して、カバレッジレポートから特定のファイルまたはファイルパターンを除外できます。

toml

[test]
# 単一パターン
coveragePathIgnorePatterns = "**/*.spec.ts"

# 複数のパターン
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js"
]

このオプションは glob パターンを受け入れ、Jest の collectCoverageFrom 無視パターンと同様に機能します。これらのパターンのいずれかに一致するファイルは、テキストと LCOV 出力の両方でカバレッジ計算とレポートから除外されます。

一般的な使用例

toml

[test]
coveragePathIgnorePatterns = [
  # ユーティリティファイルを除外
  "src/utils/**",

  # 設定ファイルを除外
  "*.config.js",
  "webpack.config.ts",
  "vite.config.ts",

  # 特定のテストパターンを除外
  "**/*.spec.ts",
  "**/*.e2e.ts",

  # ビルド成果物を除外
  "dist/**",
  "build/**",

  # 生成されたファイルを除外
  "src/generated/**",
  "**/*.generated.ts",

  # ベンダー/サードパーティコードを除外
  "vendor/**",
  "third-party/**"
]

ソースマップ

内部的には、Bun はデフォルトですべてのファイルをトランスパイルするため、Bun は元のソースコードの行を Bun の内部表現にマッピングする内部ソースマップを自動的に生成します。何らかの理由でこれを無効にしたい場合は、test.coverageIgnoreSourcemaps を true に設定します。これは高度な使用例以外ではほとんど望ましくありません。

toml

[test]
coverageIgnoreSourcemaps = true  # デフォルト false

カバレッジのデフォルト

デフォルトでは、カバレッジレポートは以下を行います。

除外 node_modules ディレクトリ
除外非 JS/TS ローダーを介して読み込まれたファイル（例：.css、.txt）。カスタム JS ローダーが指定されていない場合
含むテストファイル自体（coverageSkipTestFiles = true で無効に可能）
coveragePathIgnorePatterns で追加ファイルを除外可能

高度な設定

カスタムカバレッジディレクトリ

toml

[test]
coverageDir = "coverage-reports"  # デフォルト "coverage"

複数のレポーター

toml

[test]
coverageReporter = ["text", "lcov"]

特定のテストパターンでのカバレッジ

bash

# 特定のテストファイルでのみカバレッジを実行
bun test --coverage src/components/*.test.ts

# 名前でカバレッジを実行
bun test --coverage --test-name-pattern="API"

CI/CD 統合

GitHub Actions の例

yaml

name: Coverage Report
on: [push, pull_request]

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2

      - name: Install dependencies
        run: bun install

      - name: Run tests with coverage
        run: bun test --coverage --coverage-reporter=lcov

      - name: Upload to Codecov
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info
          fail_ci_if_error: true

GitLab CI の例

yaml

test:coverage:
  stage: test
  script:
    - bun install
    - bun test --coverage --coverage-reporter=lcov
  coverage: '/Lines\s*:\s*(\d+.\d+)%/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/lcov.info

カバレッジレポートの解釈

テキスト出力の説明

-------------|---------|---------|-------------------
File         | % Funcs | % Lines | Uncovered Line #s
-------------|---------|---------|-------------------
All files    |   85.71 |   90.48 |
 src/        |   85.71 |   90.48 |
  utils.ts   |  100.00 |  100.00 |
  api.ts     |   75.00 |   85.71 | 15-18,25
  main.ts    |   80.00 |   88.89 | 42,50-52
-------------|---------|---------|-------------------

% Funcs: テスト中に呼び出された関数の割合
% Lines: テスト中に実行された実行可能行の割合
Uncovered Line #s: 実行されなかった特定の行番号

目指すべき目標

全体の 80% 以上のカバレッジ: 一般的に良好と見なされる
重要なパスの 90% 以上: 重要なビジネスロジックは十分にテストされるべき
ユーティリティ関数の 100%: 純粋な関数とユーティリティは完全にテストするのが簡単
UI コンポーネントのカバレッジが低い: 統合テストが必要になる可能性があるため、許容されることが多い

ベストプラクティス

量だけでなく質に焦点を当てる

// 良い: 実際の機能をテスト
test("calculateTax は異なる税率を処理できる", () => {
  expect(calculateTax(100, 0.08)).toBe(8);
  expect(calculateTax(100, 0.1)).toBe(10);
  expect(calculateTax(0, 0.08)).toBe(0);
});

// 避ける: カバレッジのために行をたどるだけ
test("calculateTax が存在する", () => {
  calculateTax(100, 0.08); // アサーションなし！
});

エッジケースをテストする

test("ユーザー入力検証", () => {
  // 通常のケースをテスト
  expect(validateEmail("user@example.com")).toBe(true);

  // カバレッジを有意義に改善するエッジケースをテスト
  expect(validateEmail("")).toBe(false);
  expect(validateEmail("invalid")).toBe(false);
  expect(validateEmail(null)).toBe(false);
});

カバレッジを使用して不足しているテストを見つける

bash

# カバレッジを実行してテストされていないコードを特定
bun test --coverage

# 注意が必要な特定のファイルを確認
bun test --coverage src/critical-module.ts

他の品質指標と組み合わせる

カバレッジは 1 つの指標にすぎません。以下も検討してください。

コードレビューの質
統合テストカバレッジ
エラーハンドリングテスト
パフォーマンステスト
型安全性

トラブルシューティング

一部のファイルにカバレッジが表示されない

ファイルがカバレッジレポートに表示されない場合、テストによってインポートされていない可能性があります。カバレッジは実際に読み込まれたファイルのみを追跡します。

// テストしたいモジュールをインポートする
import { myFunction } from "../src/my-module";

test("my function works", () => {
  expect(myFunction()).toBeDefined();
});

誤ったカバレッジレポート

期待と一致しないカバレッジレポートが表示される場合。

ソースマップが正しく機能しているか確認する
coveragePathIgnorePatterns のファイルパターンを確認する
テストファイルが実際にテストするコードをインポートしていることを確認する

大規模なコードベースでのパフォーマンス問題

大規模なプロジェクトでは、カバレッジ収集によりテストが遅くなる可能性があります。

toml

[test]
# カバレッジが不要な大規模なディレクトリを除外
coveragePathIgnorePatterns = [
  "node_modules/**",
  "vendor/**",
  "generated/**"
]

開発中のすべてのテスト実行ではなく、CI または特定のブランチでのみカバレッジを実行することを検討してください。

カバレッジの有効化 ​

デフォルトで有効化 ​

カバレッジしきい値 ​

単純なしきい値 ​

詳細なしきい値 ​

カバレッジレポーター ​

利用可能なレポーター ​

LCOV カバレッジレポーター ​

GitHub Actions での LCOV の使用 ​

カバレッジからのファイルの除外 ​

テストファイルのスキップ ​

特定のパスとパターンの無視 ​

一般的な使用例 ​

ソースマップ ​

カバレッジのデフォルト ​

高度な設定 ​

カスタムカバレッジディレクトリ ​

複数のレポーター ​

特定のテストパターンでのカバレッジ ​

CI/CD 統合 ​

GitHub Actions の例 ​

GitLab CI の例 ​

カバレッジレポートの解釈 ​

テキスト出力の説明 ​

目指すべき目標 ​

ベストプラクティス ​

量だけでなく質に焦点を当てる ​

エッジケースをテストする ​

カバレッジを使用して不足しているテストを見つける ​

他の品質指標と組み合わせる ​

トラブルシューティング ​

一部のファイルにカバレッジが表示されない ​

誤ったカバレッジレポート ​

大規模なコードベースでのパフォーマンス問題 ​

カバレッジの有効化

デフォルトで有効化

カバレッジしきい値

単純なしきい値

詳細なしきい値

カバレッジレポーター

利用可能なレポーター

LCOV カバレッジレポーター

GitHub Actions での LCOV の使用

カバレッジからのファイルの除外

テストファイルのスキップ

特定のパスとパターンの無視

一般的な使用例

ソースマップ

カバレッジのデフォルト

高度な設定

カスタムカバレッジディレクトリ

複数のレポーター

特定のテストパターンでのカバレッジ

CI/CD 統合

GitHub Actions の例

GitLab CI の例

カバレッジレポートの解釈

テキスト出力の説明

目指すべき目標

ベストプラクティス

量だけでなく質に焦点を当てる

エッジケースをテストする

カバレッジを使用して不足しているテストを見つける

他の品質指標と組み合わせる

トラブルシューティング

一部のファイルにカバレッジが表示されない

誤ったカバレッジレポート

大規模なコードベースでのパフォーマンス問題