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
也會讀取原始碼,為這些檔案缺少缺少的註解。為使這項作業能正常運作,需在 bazel 專案的根目錄中執行 genhtml
。
如要查看結果,只要在任何網路瀏覽器中開啟 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 可以立即使用預設設定。算繪工具鍊也包含遠端執行作業所需的一切資訊,包括 JUnit。
Python
如需在 Python 中啟用涵蓋率支援功能所需的額外步驟,請參閱 rules_python
涵蓋率說明文件。