跳至內容

Gradle 不穩定測試

必要條件

不穩定測試是指使用相同程式碼多次執行時,會產生不同結果(通過或失敗)的測試。它們會削弱你對測試套件的信任,並浪費開發人員調查誤報失敗的時間。Tuist 會自動偵測不穩定測試,並協助你長期追蹤這些測試。

不穩定測試頁面

不穩定偵測的運作方式#

Tuist 透過兩種方式偵測不穩定測試:

測試重試#

當你執行具備重試功能的測試時,Tuist 會分析每次嘗試的結果。如果某個測試在某些嘗試中失敗,但在其他嘗試中通過,就會被標記為不穩定。

你可以使用Test Retry 外掛程式或類似機制來重新執行失敗的測試。Tuist 會偵測到那些在某些嘗試中通過、但在其他嘗試中失敗的測試。

將外掛程式加入你的 build.gradle.kts:

kotlin
plugins {
id("org.gradle.test-retry") version "1.6.2"
}
tasks.test {
retry {
maxRetries = 3
maxFailures = 5
failOnPassedAfterRetry = false
}
}

不穩定測試案例詳細資訊

跨執行偵測#

即使沒有測試重試,Tuist 也能透過比較同一個提交與同一個 Gradle 專案在不同 CI 執行中的結果,來偵測不穩定測試。如果某個測試在一次 CI 執行中通過,但在相同提交與專案的另一次執行中失敗,該失敗的執行就會被標記為不穩定。

Gradle 專案是比較鍵的一部分,因為同一個測試在不同專案中可能呈現確定性但不同的行為——例如,一個共用測試類別以不同的相依性編譯,或在不同的模組固定裝置上執行。同一個提交在不同 Gradle 專案上的兩次執行會被視為獨立的執行變體,彼此不會標記為不穩定。

這對於捕捉那些失敗頻率不足以被重試機制抓到、但仍會造成間歇性 CI 失敗的不穩定測試特別有用。

管理不穩定測試#

自動清除#

偵測與清除會透過專案上的 自動化警示 執行。每個專案都會有一個預設的「不穩定測試偵測」自動化,其 觸發條件 會將測試標記為不穩定,而 復原 則會在測試於設定的復原視窗(預設 14 天)內未再次觸發時清除標記。前往 設定 → 自動化 進行編輯,以變更復原視窗、調整復原動作(例如,也將測試從隔離中解除),或完全停用復原,讓測試保持標記為不穩定,直到你手動清除為止。

手動管理#

你也可以從測試案例詳情頁面手動將測試標記為不穩定或取消標記。這在以下情況很有用:

  • 你想在修復已知不穩定測試的同時予以確認
  • 測試因基礎設施問題而被錯誤標記

隔離不穩定測試#

隔離功能會將不穩定測試隔離,使其在修復期間不會阻礙 CI。預設為手動操作:你可以在儀表板的測試案例詳情頁面中,將測試案例加入隔離、解除隔離,並切換模式。你也可以在設定 → 自動化下將其連接至自動化警示,讓測試在超過不穩定門檻時自動靜音(或略過),並在恢復後解除隔離。每次轉換(無論手動或自動化)都會記錄在測試案例的稽核日誌中。

預設情況下,恢復會等待觸發條件不再成立,因此測試會保持隔離狀態,直到其舊有的不穩定執行離開觸發視窗。若要更快恢復,請將恢復時機設為無新的不穩定執行:只要在恢復視窗(天數或執行次數)內沒有新的不穩定執行,測試就會恢復;每次出現新的不穩定執行都會重新開始等待;恢復後,只有新的不穩定執行才會再次將其隔離。

被隔離的測試處於以下兩種模式之一:

  • 靜音:測試仍會執行,但外掛程式會設定 ignoreFailures = true,並且只在出現非隔離失敗時讓建置再次失敗。失敗紀錄仍會提供給不穩定測試偵測器,因此你可以在不破壞建置的情況下持續觀察該測試。若你正在積極調查某個測試,請選擇此模式。
  • 略過:外掛程式會透過 Gradle 的 excludeTestsMatching 將測試過濾掉,因此它永遠不會啟動。它不會產生新的結果,並會從不穩定測試儀表板中移除,直到你重新啟用為止。當測試損壞、執行緩慢,或不穩定情況嚴重到執行只會浪費 CI 分鐘數時,請選擇此模式。

為何隔離測試可能顯示為通過#

  • 靜音測試仍會執行。若靜音測試失敗,該測試案例執行會被記錄為失敗並標記為不穩定;單一測試的狀態不會被覆寫。被覆寫的是整體測試執行:如果執行中所有失敗的測試案例皆為靜音狀態,則整個執行會被回報為通過,因此靜音失敗不會導致 CI 中斷。
  • 跳過的測試完全不會執行,因此儀表板會持續顯示該測試上次實際執行的狀態。該快照可能已過時數週。

啟用隔離#

隔離會在 CI 環境中自動啟用(當設定 CI 環境變數時),並在本機建置中停用。外掛程式會在每個測試任務之前從 Tuist 伺服器取得隔離測試清單;靜音測試會正常執行並遮蔽其失敗,略過的測試則會被過濾掉。

你可以在 settings.gradle.kts 中明確控制此行為:

kotlin
tuist {
testQuarantine {
enabled = true // or false to disable
}
}

當未設定 enabled 時,預設為自動偵測:在 CI 中啟用,在本機中停用。

對新測試進行壓力測試#

壓力閘道會以全新行程多次重新執行你分支新增的測試案例,並回報結果為不穩定的案例。你可以在引入該問題的拉取請求上立即看到新的不穩定測試,而非數週後才察覺。

當測試案例在過去 90 天內未在專案的預設分支上於 CI 中執行,或未在已合併至該分支的提交上執行時,即視為新測試案例。使用合併佇列時,佇列執行的測試案例會在佇列的提交合併後被識別,若佇列將其移除,則仍維持為新測試。提交會透過 Tuist 在 CI 上收集的Git 歷史記錄進行比對。

啟用#

預設關閉此閘道。請設定模式:

  • report:針對每個不穩定測試案例發出警告。執行仍會依據其自身結果結束。
  • enforce:若存在不穩定測試案例,則使執行失敗,並使用與測試失敗相同的結束碼。

先以 report 執行數週,觀察 enforce 會攔截哪些項目。

在 settings.gradle.kts 中宣告,或設定 TUIST_TEST_STRESS_NEW_TESTS 以針對不同 CI 管道調整模式:

kotlin
tuist {
stressNewTests {
mode = "report" // or "enforce"
}
}

與隔離不同,此閘道沒有感知 CI 的預設值。若未設定 mode,則不會在任何地方執行。

每個測試的重試次數#

取決於測試案例在首次執行時的耗時:

首次執行 重試次數
最多 5 秒 10
最多 10 秒 5
最多 30 秒 3
最多 5 分鐘 2
超過 5 分鐘 不重試

當達到 200 個測試案例或 10 分鐘時, whichever comes first,執行就會停止,並顯示觸發了哪項限制。

每次重新執行都是一個巢狀 Gradle 建置,並過濾至該單一測試案例,因此每次重新執行都會獲得全新的測試 JVM。

閘道未執行時#

  • 第一輪已失敗。請先修正這些測試。
  • 專案沒有預設分支,或尚未在 CI 上執行過任何任務。
  • 超過 30% 的專案測試案例看起來是新的。重新執行這麼多測試會得不償失。當專案才剛開始向 Tuist 回報資料,或因重新命名而一次移動大量測試時,就會出現這種情況。

Slack 通知#

在 Slack 整合中設定 不穩定測試警示,即可在測試變得不穩定時收到通知。

查詢不穩定與隔離狀態#

CLI#

tuist test case 命令樹公開 Tuist 針對測試案例追蹤的所有資訊:

bash
tuist test case list --flaky # only flaky test cases
tuist test case list --quarantined # only muted or skipped test cases
tuist test case show <test_case_id> # detail: flakiness rate, last status, run counts
tuist test case events <test_case_id> # audit log: marked_flaky, muted, skipped, ...
tuist test case run list <test_case_id> # run history with status and duration
tuist test case run show <test_case_run_id> # single run, including failure breakdown

這些指令皆支援 --json,方便撰寫腳本。

REST API#

相同資料可透過 HTTP 取得。請參閱 API 參考文件中的 測試案例端點,以取得完整的路由、篩選器與回應欄位清單。若要變更測試案例的狀態(標記或取消標記為不穩定、靜音、略過),請傳送 PATCH /api/projects/{account_handle}/{project_handle}/tests/test-cases/{test_case_id} 並附上 is_flaky 或 state。相同的變更也可透過 tuist test case update 以及 update_test_case MCP 工具完成。