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 應能以預設設定運作。Bazel 工具鍊也包含遠端執行所需的一切項目,包括 JUnit。
Python
如需在 Python 中啟用涵蓋範圍支援的額外步驟,請參閱rules_python
涵蓋範圍文件。