Bazel によるコード カバレッジ

問題を報告 ソースを表示

Bazel には、bazel coverage でテストできるリポジトリのコード カバレッジ レポートを生成する coverage サブコマンドがあります。さまざまな言語エコシステムの特異性により、特定のプロジェクトでこれを行うことは必ずしも簡単ではありません。

このページでは、カバレッジ レポートを作成および表示する一般的なプロセスについて説明します。また、構成がよく知られている言語について、言語固有の注意事項についても説明します。最初に一般的なセクションを読んでから、特定の言語の要件を読むことをおすすめします。リモート実行セクションにも注意してください。これには追加の考慮事項がいくつかあります。

さまざまなカスタマイズが可能ですが、このドキュメントでは lcov レポートの作成と使用に重点を置いています。現在、このレポートは最もサポートされている方法です。

カバレッジ レポートを作成する

準備

カバレッジ レポートを作成する基本的なワークフローでは、次のことが必要です。

  • テスト ターゲットを含む基本的なリポジトリ
  • 言語固有のコード カバレッジ ツールがインストールされたツールチェーン
  • 正しい「計測」構成

前者は言語固有でほとんどが単純ですが、後者は複雑なプロジェクトではより難しい場合があります。

この場合の「計測」とは、特定のターゲットに使用されるカバレッジ ツールを指します。Bazel では、--instrumentation_filter フラグを使用して、ファイルのサブセットに対してこの機能を有効にできます。このフラグは、インストルメンテーションを有効にしてテストされたターゲットのフィルタを指定します。テストのインストルメンテーションを有効にするには、--instrument_test_targets フラグが必要です。

デフォルトでは、bazel はターゲット パッケージの照合を試み、関連するフィルタを INFO メッセージとして出力します。

実行中のカバレッジ

カバレッジ レポートを作成するには、bazel coverage --combined_report=lcov [target] を使用します。これにより、ターゲットのテストが実行され、ファイルごとに lcov 形式のカバレッジ レポートが生成されます。

完了すると、Bazel は生成されたすべてのカバレッジ ファイルを収集するアクションを実行して、それらを 1 つにマージします。1 つにマージされた後、最終的に $(bazel info output_path)/_coverage/_coverage_report.dat の下に作成されます。

テストが失敗した場合にもカバレッジ レポートが生成されますが、不合格になったテストは対象になりません。合格したテストのみが報告されます。

カバレッジの表示

カバレッジ レポートは、人間が判読できない lcov 形式でのみ出力されます。ここから、genhtml ユーティリティ（lcov プロジェクトの一部）を使用して、ウェブブラウザで表示できるレポートを生成できます。

genhtml --output genhtml "$(bazel info output_path)/_coverage/_coverage_report.dat"

なお、genhtml はソースコードも読み取り、これらのファイルで欠落しているカバレッジにアノテーションを付けます。これが機能するためには、genhtml が bazel プロジェクトのルートで実行されることが想定されています。

結果を表示するには、任意のウェブブラウザで genhtml ディレクトリで生成された index.html ファイルを開きます。

genhtml ツールまたは lcov カバレッジ形式について詳しくは、lcov プロジェクトをご覧ください。

リモート実行

現在、リモートテスト実行で実行する場合、いくつかの注意点があります。

  • レポートの組み合わせの操作はまだリモートで実行できません。これは、Bazel がカバレッジ出力ファイルをグラフの一部として考慮せず（この問題を参照）、組み合わせアクションへの入力として正しく処理できないためです。この問題を回避するには、--strategy=CoverageReport=local を使用します。
    • 注: Bazel が local,remote を試すように設定されている場合、Bazel によるストラテジーの解決方法により、--strategy=CoverageReport=local,remote などの指定が必要になることがあります。
  • 前者の場合、--remote_download_minimal や同様のフラグも使用できません。
  • テストがすでにキャッシュに保存されている場合、Bazel は現在、カバレッジ情報の作成に失敗します。これを回避するために、カバレッジ実行専用に --nocache_test_results を設定できますが、もちろんテスト時間の面で大きなコストが発生します。
  • --experimental_split_coverage_postprocessing と --experimental_fetch_all_coverage_outputs
    • 通常、カバレッジはテスト アクションの一部として実行されるため、デフォルトでは、すべてのカバレッジがリモート実行の出力として返されるわけではありません。これらのフラグはデフォルトをオーバーライドし、カバレッジ データを取得します。詳しくは、この問題をご覧ください。

言語固有の構成

Java

Java は、デフォルトの構成ですぐに使用できます。Bazel ツールチェーンには、JUnit をはじめ、リモート実行に必要なすべてのものが含まれています。

Python

Python でカバレッジ サポートを有効にするために必要な追加の手順については、rules_python カバレッジのドキュメントをご覧ください。