Elixir 程式碼涵蓋率
程式碼涵蓋率告訴你測試執行了程式碼中的哪些行。Hex 套件會上傳每次 mix test --cover 執行的行涵蓋率,而 Tuist 會將一個提交的所有執行合併為單一數值,適用於專案、每個 OTP 應用程式以及每個檔案。儀表板的 程式碼涵蓋率 頁面會顯示每個提交的數據,以及每個分支的趨勢。
- 完成 共用的 Elixir 設定,這會讓
mix test透過套件進行路由
設定#
使用涵蓋率執行測試#
傳遞 --cover,就像你在沒有 Tuist 的情況下對 mix test 所做的一樣:
mix test --cover
套件會上傳涵蓋率以及該次執行的測試結果。當測試套件完成時,它也會執行 Mix 涵蓋率工具所做的操作,並使用相同的 test_coverage 選項進行設定:
- 摘要。 它會列印每個模組和總計的涵蓋率。
summary: false會將其關閉。 - 閾值。 當總計低於閾值時,它會以退出狀態 3 使執行失敗,除非你設定了其他值,否則閾值為 90%:
def project do
[
test_coverage: [summary: [threshold: 80]]
]
end
如同在 Mix 中,閾值屬於摘要,因此 summary: false 會同時關閉兩者。若要列印摘要而不使執行失敗,請設定 threshold: 0。列在 test_coverage: [ignore_modules: [...]] 中的模組不會包含在摘要和上傳內容中。
Tuist 會追蹤每個提交的涵蓋率,因此你的專案需要位於 Git 儲存庫中:在非儲存庫環境中的執行會上傳其測試結果,但不會上傳涵蓋率。
涵蓋率依賴於套件上傳的 Git 歷史記錄,這會將提交放置在其分支上。持續整合上的執行總是會上傳它,而 --cover 執行則會在任何機器上上傳它。使用 --cover 時,套件還會找出拉取請求的分叉點:它會抓取基礎分支並根據需要加深淺層克隆。設定 TUIST_GIT_UNSHALLOW_ENABLED=false 以防止其聯絡遠端。
分片執行#
當你 分片測試 時,請使用 --cover 執行每個分片:
MIX_ENV=test TUIST_SHARD_INDEX=0 mix tuist.test --cover
在新的執行器上,使用分片指南中 測試階段 的 bootstrap 命令,這可以防止 Mix 在分片下載其建置之前編譯每個相依性,並將 --cover 加入其中。
分片僅報告其自身的涵蓋率且不檢查閾值,因為它只執行套件的一部分。Tuist 會將一次執行的所有分片合併為單一數值。
每個分片會將涵蓋率計數器添加到其下載的建置中。若要改為只執行一次,請將 --cover 也傳遞給建置階段:
MIX_ENV=test mix tuist.test.build --shard-max 5 --cover
當你在管道執行之間保留建置目錄,並在未收集涵蓋率的執行中重複使用它時,請不要啟用此選項,以便該建置保持沒有計數器的狀態。
在 CI 上完成每個提交#
提交的涵蓋率通常來自多個工作:每個分片、每個資料庫版本或每個應用程式各一個。Tuist 無法判斷最後一個工作何時已報告,因此你需要告訴它。當一個提交的所有測試工作完成後,請在依賴所有這些工作的另一個工作中執行以下命令:
MIX_ENV=test mix tuist.coverage.complete
該任務從 GIT_COMMIT 或檢出的 HEAD 讀取提交;傳遞 --commit <sha> 以指定另一個提交。在提交完成之前,其涵蓋率會顯示為 進行中,且不會包含在其分支的趨勢中。
運作方式#
原生行計數器#
Mix 的涵蓋率工具會在每次執行開始時,為 Erlang 的 cover 重新編譯每個模組,這在大型專案上會變慢。該套件改用執行時的原生行計數器進行計數。它僅重新編譯自上次執行以來由編譯寫入的模組,將執行時切換到這些計數器,並在套件完成時讀取它們。Mix 的涵蓋率工具被排除在外,但其摘要和閾值會被保留。
該套件會在以下情況回退到 Mix 的涵蓋率工具,並使用相同的上傳方式:
- 傘狀專案的根目錄。在每個應用程式內部執行測試以進行原生計數。
- 設定了自己的
test_coverage: [tool: ...]的專案。 - 沒有 JIT 的執行時,無法進行原生計數。
Tuist 測量的內容#
- 應用程式。 每個 OTP 應用程式都是儀表板上的一個目標,擁有自己的涵蓋率。
- 僅產品程式碼。 測試路徑下的檔案是測試程式碼。Tuist 會儲存它們,但將它們排除在所有數值之外。
- 每檔案的行數。 無論一行屬於多少個模組,它在每個檔案中只計算一次。
- 函式。 每一行都屬於其上方最近的子句所屬的函式。編譯器或巨集產生的函式,例如
__info__/1或__schema__/1,不會被列出,但它們的行仍會計入其檔案。
因此,Tuist 的數值與 Mix 自身的涵蓋率報告有幾點不同:它們排除了測試程式碼,並按檔案而非按模組計算行數。原生計數還能看到應用程式啟動時執行的程式碼,並排除編譯器證明永遠不會執行的行,而 Mix 的工具會將這些行報告為從未涵蓋。
跳過的測試#
Tuist 無法延續執行所省略測試的涵蓋率:套件記錄的是整個執行所執行的內容,而不是每個測試執行的內容。因此,當執行的參數省略了測試,例如使用 --only、--exclude、--failed、--stale、--name-pattern、--max-failures,或測試檔案或行時,提交的涵蓋率會是 不完整,除非也執行了未省略任何內容的相同變體執行。兩個各自省略測試的執行,例如 --exclude slow 和 --only slow,即使它們一起執行了所有測試,仍會使提交不完整。
某些測試是故意省略的,不會導致提交不完整:
- 測試輔助工具的排除項。
ExUnit.start(exclude: [...])預設省略的測試是你的專案對於其套件預設執行內容的選擇,因此 Tuist 不會將它們視為缺失。在另一個工作中使用--include或--only執行它們,以將它們的涵蓋率添加到提交中。 - 程式碼中跳過的測試,使用
@tag :skip。 - 隔離跳過的測試。 它們被排除在外,如同已被移除,因此僅由它們涵蓋的行會被計為未涵蓋。
完整與不完整的提交#
儀表板上的每個提交都有一個狀態:
| 狀態 | 意義 |
|---|---|
| 進行中 | 已有執行回報涵蓋率,但尚未針對該提交執行 mix tuist.coverage.complete。 |
| 完整 | 該提交的所有執行中的每個測試都已執行,或是故意省略。 |
| 不完整 | 部分涵蓋率無法確定,因此該數值為下限。 |
| 未測量 | 沒有執行回報該提交的涵蓋率。 |
分支的趨勢僅包含完整的提交。例如,當出現以下情況時,提交即為不完整:
- 某個變體的每次執行都因其自身參數而省略了測試。
- 某個變體的每次執行都缺少部分分片。
- 某個變體的涵蓋率僅來自於具有未提交變更的檢出版本上的 CI 執行。
變體是你透過 --scheme 傳遞的標籤,例如資料庫版本。沒有標籤的執行屬於同一個變體。提交的數值會合併所有執行,但 Tuist 會分別檢查每個變體的完整性,因此每個變體都需要一次未省略任何內容的執行。
效能影響#
收集涵蓋率會增加額外負擔,因此使用 --cover 的執行比不使用的執行耗時更長。第一次執行會使用行計數器重新編譯你的模組;後續執行僅重新編譯變更的部分,因此成本大幅降低。在大型專案中,原生計數也比 Mix 的涵蓋率工具快得多。
限制#
- 無 HTML 報告。 原生計數不會將報告寫入
test_coverage: [output: ...]目錄,且當設定該目錄時,執行會發出警告。儀表板的檔案頁面會改為顯示已涵蓋的行。 - 重試不會增加涵蓋率。 使用 測試重試 時,涵蓋率以第一次嘗試為準。該次嘗試已執行失敗的測試,因此缺少的行僅限於不穩定測試在重試時到達、但在第一次嘗試時未到達的那些行。
- 來自 Fork 的拉取請求無涵蓋率。 涵蓋率僅由向 Tuist 驗證身份的執行上傳,而 CI 通常會對來自 Fork 的拉取請求保留機密與身分令牌,因此這些執行不會回報涵蓋率。一旦合併,該提交便會使用憑證在你的分支上執行,並照常回報其涵蓋率。
查詢涵蓋率#
儀表板的 程式碼涵蓋率 頁面顯示每個提交的數值、其應用程式及其檔案,以及每次執行所涵蓋的行。代理程式也可透過 Model Context Protocol 伺服器 取得相同的資料。