使用 Bazel 涵蓋程式碼

回報問題 查看原始碼 Nightly · 8.0 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Bazel 提供 coverage 子指令,可針對可透過 bazel coverage 測試的存放區產生程式碼涵蓋率報告。由於各種語言生態系統都有其特點,因此要讓這項功能適用於特定專案,並非易事。

本頁面說明建立及查看涵蓋率報表的一般程序,並針對設定已知的語言提供一些特定語言的附註。建議您先閱讀一般部分,再閱讀特定語言的規定。請注意遠端執行區段,這需要一些額外考量。

雖然可以進行許多自訂設定,但這份文件著重於產生及使用 lcov 報表,這是目前最受支援的路徑。

建立涵蓋率報表

準備

建立涵蓋率報表的基本工作流程需要以下項目:

  • 含有測試目標的基本存放區
  • 已安裝特定語言程式碼涵蓋率工具的工具鍊
  • 正確的「檢測」設定

前兩種方法都與語言相關,且大多相當簡單,但對於複雜的專案而言,後者可能較為困難。

在本例中,「檢測」是指用於特定目標的涵蓋率工具。Bazel 可讓您使用 --instrumentation_filter 標記,為特定檔案子集啟用這項功能,該標記會為啟用檢測功能的目標指定篩選器。如要為測試啟用檢測設備,必須使用 --instrument_test_targets 標記。

根據預設,bazel 會嘗試比對目標套件,並將相關篩選器列印為 INFO 訊息。

執行涵蓋範圍

如要產生涵蓋率報表,請使用 bazel coverage --combined_report=lcov [target]。這會為目標執行測試,並為每個檔案以 lcov 格式產生涵蓋率報告。

完成後,bazel 會執行動作,收集所有產生的涵蓋率檔案,並將這些檔案合併為一個檔案,最後在 $(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 也會讀取原始碼,以便在這些檔案中註解缺少的涵蓋率。為使此功能正常運作,genhtml 應在 Bazel 專案的根目錄中執行。

如要查看結果,只要在任何網路瀏覽器中開啟 genhtml 目錄中產生的 index.html 檔案即可。

如需 genhtml 工具或 lcov 涵蓋率格式的進一步說明和資訊,請參閱 lcov 專案

遠端執行

目前使用遠端測試執行功能執行測試時,有幾項需要注意的事項:

  • 報表組合動作目前無法遠端執行。這是因為 Bazel 不會將涵蓋率輸出檔案視為圖表的一部分 (請參閱這個問題),因此無法正確將這些檔案視為組合動作的輸入內容。如要解決這個問題,請使用 --strategy=CoverageReport=local
    • 注意:如果 Bazel 已設為嘗試 local,remote,則可能需要改為指定 --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 涵蓋率說明文件