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

問題を報告する ソースを表示

Bazel は、bazel coverage でテストできるリポジトリにコード カバレッジ レポートを作成するための coverage サブコマンドを備えています。さまざまな言語エコシステムの特異性により、特定のプロジェクトでこれを実現するのは簡単なことではありません。

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

多くのカスタマイズが可能ですが、このドキュメントでは lcov レポートの作成と利用方法を中心に説明します。

カバレッジ レポートの作成

Preparation

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

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

最初の 2 つは言語に特化しており、ほとんどが簡単ですが、複雑なプロジェクトでは後者の方が難しい場合があります。

この場合の「インストルメンテーション」は、特定のターゲットに使用されるカバレッジ ツールを指します。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 がカバレッジ出力ファイルをグラフの一部として考慮しないため(問題を参照)、組み合わせアクションの入力として正しく処理できません。この問題を回避するには、--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 カバレッジ ドキュメントをご覧ください。