Bazel には、bazel coverage でテストできるリポジトリのコード カバレッジ レポートを生成する coverage サブコマンドがあります。さまざまな言語エコシステムの特性により、特定のプロジェクトでこれを機能させることは必ずしも簡単ではありません。
このページでは、カバレッジ レポートの作成と表示に関する一般的なプロセスについて説明します。また、構成がよく知られている言語については、言語固有の注意事項も記載しています。まず全般に関するセクションを読み、次に特定の言語の要件について読むことをおすすめします。リモート実行のセクションもご覧ください。このセクションでは、追加の考慮事項について説明しています。
多くのカスタマイズが可能ですが、このドキュメントでは、現在最もサポートされている方法である lcov レポートの生成と使用に焦点を当てています。
カバレッジ レポートの作成
準備
カバレッジ レポートを作成する基本的なワークフローには、次のものが必要です。
- テスト ターゲットを含む基本的なリポジトリ
- 言語固有のコード カバレッジ ツールがインストールされたツールチェーン
- 正しい「計測」構成
最初の 2 つは言語固有で、ほとんどの場合簡単ですが、最後の 1 つは複雑なプロジェクトでは難しい場合があります。
ここでいう「計測」とは、特定のターゲットに使用されるカバレッジ ツールを指します。Bazel では、--instrumentation_filter フラグを使用して、特定のファイルのサブセットに対してこれを有効にできます。このフラグは、インストルメンテーションが有効になっているテスト対象のフィルタを指定します。テストのインストルメンテーションを有効にするには、--instrument_test_targets フラグが必要です。
デフォルトでは、bazel はターゲット パッケージを照合し、関連するフィルタを INFO メッセージとして出力します。
カバレッジの実行
カバレッジ レポートを作成するには、bazel coverage
--combined_report=lcov
[target] を使用します。これにより、ターゲットのテストが実行され、各ファイルの lcov 形式のカバレッジ レポートが生成されます。
完了すると、bazel は生成されたすべてのカバレッジ ファイルを収集して 1 つにマージするアクションを実行し、最終的に $(bazel info
output_path)/_coverage/_coverage_report.dat に作成します。
テストが失敗した場合にもカバレッジ レポートが生成されますが、失敗したテストはレポートされず、合格したテストのみがレポートされます。
カバレッジの表示
カバレッジ レポートは、人が読めない lcov 形式でのみ出力されます。ここから、genhtml ユーティリティ（lcov プロジェクトの一部）を使用して、ウェブブラウザで表示できるレポートを生成できます。
genhtml --branch-coverage --output genhtml "$(bazel info output_path)/_coverage/_coverage_report.dat"
genhtml はソースコードも読み取り、これらのファイルで欠落しているカバレッジにアノテーションを付けます。この処理が機能するには、bazel プロジェクトのルートで genhtml が実行されることが想定されています。
結果を表示するには、genhtml ディレクトリに生成された index.html ファイルを任意のウェブブラウザで開きます。
genhtml ツールまたは lcov カバレッジ形式に関するヘルプと詳細については、lcov プロジェクトをご覧ください。
リモート実行
リモート テスト実行には、いくつかの注意点があります。
- レポートの組み合わせアクションは、まだリモートで実行できません。これは、Bazel がカバレッジ出力ファイルをグラフの一部と見なさないため（Bazel の問題 #4685 を参照）、それらを組み合わせアクションの入力として正しく処理できないためです。この問題を回避するには、
--strategy=CoverageReport=localを使用します。- 注: Bazel が
local,remoteを試すように設定されている場合、Bazel が戦略を解決する方法により、代わりに--strategy=CoverageReport=local,remoteのようなものを指定する必要がある場合があります。
- 注: Bazel が
- また、
--remote_download_minimalなどのフラグも、前述の理由により使用できません。 - テストが以前にキャッシュに保存されている場合、Bazel はカバレッジ情報を作成できません。この問題を回避するには、カバレッジ実行用に
--nocache_test_resultsを明示的に設定できますが、テスト時間という点で大きなコストが発生します。 --experimental_split_coverage_postprocessingと--experimental_fetch_all_coverage_outputs- 通常、カバレッジはテスト アクションの一部として実行されるため、デフォルトでは、リモート実行の出力としてすべてのカバレッジが返されるわけではありません。これらのフラグはデフォルトをオーバーライドして、カバレッジ データを取得します。詳しくは、Bazel の問題 #4685 をご覧ください。
言語固有の構成
以降のセクションでは、Bazel でコード カバレッジを設定する際の言語固有の考慮事項について詳しく説明します。
C++
Linux
C++ カバレッジは、デフォルトの構成でそのまま使用できます。
macOS
正しい値は設定によって異なるため、GCOV_PREFIX_STRIP のデフォルト値はほぼ確実に正しくありません。手動で調整する必要があります。
値が正しくない場合、カバレッジ データは見つかりません。
GCOV_PREFIX_STRIP=10
bazel coverage //foo:foo_test --test_env=GCOV_PREFIX_STRIP=10` を設定する例
Java
Java は、デフォルトの構成でそのまま使用できます。bazel ツールチェーンには、JUnit を含むリモート実行に必要なものがすべて含まれています。
Python
Python でカバレッジのサポートを有効にするために必要な追加の手順については、rules_python カバレッジ ドキュメントをご覧ください。