Xcode 不穩定測試
- 已設定 Xcode 測試洞察。Tuist 會從每次測試執行上傳的測試洞察事件中偵測不穩定測試。
不穩定測試係指用同一份代碼多次執行時,會產生唔同結果(通過或失敗)嘅測試。呢啲測試會削弱你對測試套件嘅信任,亦會浪費開發人員排查虛假失敗嘅時間。Tuist 會自動偵測不穩定測試,並幫你持續追蹤。

不穩定測試偵測如何運作#
Tuist 透過兩種方式偵測不穩定測試:
測試重試#
當你使用重試功能執行測試時,Tuist 會分析每次嘗試的結果。如果測試在某些嘗試中失敗,但在其他嘗試中通過,則會被標記為不穩定。
透過 tuist xcodebuild test 傳遞 -retry-tests-on-failure 或 -test-iterations:
tuist xcodebuild test \
-scheme MyScheme \
-retry-tests-on-failure \
-test-iterations 3

跨執行檢測#
即使沒有測試重試,Tuist 仍可透過比較相同提交、scheme 及回報目的地(裝置名稱、平台與作業系統版本)下不同 CI 執行的結果,偵測不穩定測試。如果某項測試在一個相符的 CI 執行中通過,但在另一個中失敗,則該次失敗的執行會被標記為不穩定。無論哪個結果先到達,此機制皆有效。
同一項測試在不同 scheme 或目的地上的表現可能持續不同。例如,在 iOS 26 上通過而在 iOS 27 上失敗,並不代表不穩定。來自不同 scheme、裝置、平台或作業系統版本的結果不會互相標記為不穩定。
缺少目的地中繼資料,或涵蓋多個目的地的執行,只會彼此互相比較,因此它們之間的環境差異仍可能被回報為不穩定。基於重試的偵測仍然適用。
這對於捕捉那些失敗頻率不足以被重試機制抓到、但仍會導致間歇性 CI 失敗的不穩定測試特別有用。
管理不穩定測試#
自動清除#
偵測同清除會透過項目上嘅 自動化警示 執行。每個項目都會有一個預設嘅「不穩定測試偵測」自動化,佢嘅 觸發條件 會將測試標記為不穩定,而佢嘅 恢復機制 會在測試通過設定嘅恢復時間窗口(預設 14 日)而冇再觸發之後,清除該標記。你可以喺 設定 → 自動化 入面編輯它,以更改恢復時間窗口、更改恢復動作(例如,同時將測試從隔離中釋放),或者完全禁用恢復,令測試保持標記為不穩定,直到你手動清除它們。
手動管理#
你亦可以喺測試案例詳情頁面手動標記或取消標記測試為不穩定。以下情況會有用:
- 你想喺修復期間確認已知嘅不穩定測試
- 測試因為基礎設施問題而被錯誤標記
隔離不穩定測試#
隔離會將不穩定測試案例獨立出來,令佢喺你修復期間唔會阻塞 CI。預設情況下,呢個係 手動操作:你可以從儀表板嘅測試案例詳情頁面隔離測試案例、解除隔離,同埋切換模式。你亦都可以將佢設定為 Settings → Automations 底下嘅 自動化警示,當測試案例跨越不穩定閾值時自動靜音(或跳過),並於恢復時解除隔離。每次轉換,無論係手動定自動化,都會記錄喺測試案例嘅審核日誌中。
預設情況下,恢復會等待觸發條件不再成立,因此測試案例會保持隔離狀態,直到舊有嘅不穩定執行離開觸發視窗。如需更快恢復,請將 Recover when 設定為 No new flaky runs:一旦恢復視窗(以日數或執行次數計算)內沒有新嘅不穩定執行,測試案例就會恢復;每次出現新嘅不穩定執行都會重新開始等待,而恢復後只有新嘅不穩定執行會再次將其隔離。
被隔離的測試處於以下兩種模式之一:
- 靜音:測試仍會執行,但
tuist xcodebuild test會隱藏失敗結果。失敗結果仍會提供給不穩定測試偵測器,因此你可以繼續監控該測試而不會導致建構失敗。如果你正在積極調查某個測試,請選擇此模式。 - 跳過:xcodebuild 會收到
-skip-testing <identifier>,因此測試永遠不會啟動。它不會產生新結果,並會從不穩定測試儀表板中移除,直到你重新啟用為止。當測試損壞、緩慢,或持續不穩定以致於執行它只是浪費 CI 分鐘數時,請選擇此模式。
點解隔離測試會顯示為通過#
- 靜音測試仍然會執行。如果靜音測試失敗,會在測試案例執行中記錄為失敗並標記為不穩定;單一測試的狀態不會被改寫。被覆蓋的是整體測試執行:如果執行中所有失敗的測試案例都已被靜音,則整個執行會被報告為通過,因此靜音失敗不會導致 CI 中斷。
- 跳過測試完全不會執行,因此儀表板會繼續顯示該測試最後一次實際執行的狀態。該快照可能已過時數週。
執行測試#
tuist xcodebuild test 是一個自動支援這兩種模式的直通包裝器。使用方法與呼叫 xcodebuild 相同:
tuist xcodebuild test -scheme MyScheme
跳過的測試會以 -skip-testing <identifier> 的形式附加到你的 xcodebuild 指令中,並且永遠不會啟動。靜音測試會正常執行;如果它們失敗,失敗結果會在最終的建構狀態中被隱藏。
繞過隔離#
tuist xcodebuild test 接受 --skip-quarantine 以執行所有內容,包括靜音和跳過的測試:
tuist xcodebuild test --skip-quarantine -scheme MyScheme
直接呼叫 xcodebuild#
如果你無法透過 tuist xcodebuild test 執行,可以使用 tuist test case list 自行將被隔離的測試展開為 -skip-testing 參數:
xcodebuild test \
-scheme MyScheme \
$(tuist test case list --quarantined --skip-testing)
這是 tuist xcodebuild test 之外的安全預設值:靜音測試的失敗隱藏只有在你透過該命令執行時才會發生,因此跳過這兩種模式可以避免虛假的 CI 失敗。如果你需要更精細的控制,請改用 tuist xcodebuild test。
壓力測試新測試#
壓力閘會喺全新進程中多次重新執行你分支新增嘅測試用例,並回報出現不穩定情況嘅用例。你會喺引入該問題嘅拉取請求上即時見到新發現嘅不穩定測試,而唔係幾星期後先至發現。
當測試案例在過去 90 天內未在專案的預設分支上於 CI 中執行,或未在已合併至該分支的提交上執行時,即視為新測試。使用合併佇列時,佇列執行的測試案例在佇列的提交合併後即被識別,如果佇列將其刪除,則保持為新測試。提交是透過 Tuist 在 CI 上收集的 Git 歷史記錄 進行匹配的。
啟用功能#
預設情況下此閘門處於關閉狀態。請設定模式:
report:針對每個不穩定的測試案例發出警告。運行仍會根據其自身結果結束。enforce:不穩定的測試案例會導致運行失敗,退出代碼與測試失敗時相同。
先使用 report 幾星期,以了解 enforce 會攔截什麼情況。
將其放在直通參數之前傳遞,或設定 TUIST_TEST_STRESS_NEW_TESTS 以根據每個 CI 管道變更模式:
tuist xcodebuild test --stress-new-tests report -scheme MyScheme
每個測試重新執行嘅次數#
取決於測試案例喺第一次執行時所花嘅時間:
| 第一次執行 | 重新執行次數 |
|---|---|
| 最多 5 秒 | 10 |
| 最多 10 秒 | 5 |
| 最多 30 秒 | 3 |
| 最多 5 分鐘 | 2 |
| 超過 5 分鐘 | 唔會重新執行 |
當達到 200 個測試案例或 10 分鐘時,執行就會停止(以較早者為準),並顯示觸發咗邊個限制。
重新執行會重用第一次通行所建構的內容。
當閘門未執行#
- 第一輪已失敗。請先修復該等測試。
- 專案沒有預設分支,或尚未在 CI 上執行任何內容。
- 超過 30% 的專案測試案例看似新增。重新執行咁多會耗時過長,得不償失。當專案剛開始向 Tuist 回報,或進行重新命名而一次過移動大量測試時,就會出現此情況。
Slack 通知#
喺你嘅 Slack 整合入面設定 不穩定測試警報,就可以喺測試變得不穩定時收到通知。
查詢不穩定及隔離狀態#
CLI#
tuist test case 指令樹公開 Tuist 追蹤測試案例的所有資料:
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 工具進行。