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 --output genhtml "$(bazel info output_path)/_coverage/_coverage_report.dat"
請注意,genhtml
也會讀取原始碼,為這些檔案缺少涵蓋範圍加上註解。為此,genhtml
應在 bazel 專案的根目錄中執行。
如要查看結果,只要在任何網路瀏覽器中開啟 genhtml
目錄中產生的 index.html
檔案即可。
如需 genhtml
工具或 lcov
涵蓋範圍格式的進一步協助和資訊,請參閱 lcov 專案。
遠端執行
透過遠端測試執行作業執行目前有一些注意事項:
- 報表組合動作目前無法遠端執行。這是因為 Bazel 不會將涵蓋率輸出檔案視為圖表的一部分 (請參閱這個問題),因此無法將其正確視為組合動作的輸入。如要解決這個問題,請使用
--strategy=CoverageReport=local
。- 注意:如果 Bazel 因 Bazel 解析策略,而設定為嘗試使用
local,remote
,則可能需要指定--strategy=CoverageReport=local,remote
這類的內容。
- 注意:如果 Bazel 因 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
涵蓋範圍文件。