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
などの指定が必要になることがあります。
- 注: Bazel が
- 前者の場合、
--remote_download_minimal
や同様のフラグも使用できません。 - 現在、テストが以前にキャッシュに保存されている場合、Bazel はカバレッジ情報を作成できません。これを回避するために、カバレッジ実行専用に
--nocache_test_results
を設定できますが、もちろんテスト時間の面で大きなコストが発生します。 --experimental_split_coverage_postprocessing
と--experimental_fetch_all_coverage_outputs
- 通常、カバレッジはテスト アクションの一部として実行されるため、デフォルトでは、リモート実行の出力としてすべてのカバレッジが返されるわけではありません。これらのフラグはデフォルトをオーバーライドして、カバレッジ データを取得します。詳しくは、こちらの問題をご覧ください。
言語固有の構成
Java
Java は、デフォルトの構成ですぐに動作するはずです。bazel ツールチェーンには、JUnit など、リモート実行に必要なものがすべて含まれています。
Python
Python でカバレッジ サポートを有効にするために必要な追加の手順については、rules_python
カバレッジのドキュメントをご覧ください。