# 已生成嘅 Xcode 專案 {#generated-xcode-project-flaky-tests}

> [!IMPORTANT]
> **必要條件**
>
> - 已設定 <.localized_link href="/guides/features/test-insights/xcode">Xcode 測試洞察</.localized_link>（自動生成嘅 scheme 會包含 `tuist inspect test` post-action；自訂 scheme 需要手動加入）。

不穩定測試係指用同一份代碼多次執行時，會產生唔同結果（通過或失敗）嘅測試。呢啲測試會削弱你對測試套件嘅信任，亦會浪費開發人員排查虛假失敗嘅時間。Tuist 會自動偵測不穩定測試，並幫你持續追蹤。


![不穩定測試頁面](/images/guides/features/test-insights/flaky-tests-page.png)

## 不穩定測試偵測運作方式 {#how-it-works}

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

### 測試重試 {#test-retries}

當你執行帶有重試功能嘅測試時，Tuist 會分析每次嘗試嘅結果。如果一個測試案例喺某啲嘗試中失敗，但喺其他嘗試中通過，就會被標記為不穩定。

透過 `tuist test` 傳遞 `-retry-tests-on-failure` 或 `-test-iterations`：

```sh
tuist test MyScheme -- -retry-tests-on-failure -test-iterations 3
```

![不穩定測試案例詳情](/images/guides/features/test-insights/flaky-test-case-detail.png)

### 跨執行檢測 {#cross-run-detection}

即使沒有測試重試，Tuist 仍可透過比較相同提交、scheme 及回報目的地（裝置名稱、平台與作業系統版本）下不同 CI 執行的結果，偵測不穩定測試。如果某項測試在一個相符的 CI 執行中通過，但在另一個中失敗，則該次失敗的執行會被標記為不穩定。無論哪個結果先到達，此機制皆有效。

同一項測試在不同 scheme 或目的地上的表現可能持續不同。例如，在 iOS 26 上通過而在 iOS 27 上失敗，並不代表不穩定。來自不同 scheme、裝置、平台或作業系統版本的結果不會互相標記為不穩定。

缺少目的地中繼資料，或涵蓋多個目的地的執行，只會彼此互相比較，因此它們之間的環境差異仍可能被回報為不穩定。基於重試的偵測仍然適用。

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


## 管理不穩定測試 {#managing-flaky-tests}

### 自動清除 {#automatic-clearing}

偵測同清除會透過項目上嘅 **自動化警示** 執行。每個項目都會有一個預設嘅「不穩定測試偵測」自動化，佢嘅 *觸發條件* 會將測試標記為不穩定，而佢嘅 *恢復機制* 會在測試通過設定嘅恢復時間窗口（預設 **14 日**）而冇再觸發之後，清除該標記。你可以喺 **設定 → 自動化** 入面編輯它，以更改恢復時間窗口、更改恢復動作（例如，同時將測試從隔離中釋放），或者完全禁用恢復，令測試保持標記為不穩定，直到你手動清除它們。

### 手動管理 {#manual-management}

你亦可以喺測試案例詳情頁面手動標記或取消標記測試為不穩定。以下情況會有用：
- 你想喺修復期間確認已知嘅不穩定測試
- 測試因為基礎設施問題而被錯誤標記


## 隔離不穩定測試 {#quarantining}

隔離會將不穩定測試案例獨立出來，令佢喺你修復期間唔會阻塞 CI。預設情況下，呢個係 **手動操作**：你可以從儀表板嘅測試案例詳情頁面隔離測試案例、解除隔離，同埋切換模式。你亦都可以將佢設定為 **Settings → Automations** 底下嘅 **自動化警示**，當測試案例跨越不穩定閾值時自動靜音（或跳過），並於恢復時解除隔離。每次轉換，無論係手動定自動化，都會記錄喺測試案例嘅審核日誌中。

預設情況下，恢復會等待觸發條件不再成立，因此測試案例會保持隔離狀態，直到舊有嘅不穩定執行離開觸發視窗。如需更快恢復，請將 **Recover when** 設定為 **No new flaky runs**：一旦恢復視窗（以日數或執行次數計算）內沒有新嘅不穩定執行，測試案例就會恢復；每次出現新嘅不穩定執行都會重新開始等待，而恢復後只有新嘅不穩定執行會再次將其隔離。


被隔離嘅測試處於以下兩種模式之一：

- **靜音**：測試仍然會執行，但 `tuist test` 會隱藏失敗結果。失敗記錄仍會提供俾不穩定測試偵測器，因此你可以繼續監察該測試而唔會導致建構失敗。適用於你積極調查中嘅測試。
- **略過**：xcodebuild 會收到 `-skip-testing <identifier>`，因此測試永遠唔會啟動。佢唔會產生新結果，並會從不穩定測試儀表板中移除，直到你重新啟用為止。當測試損壞、緩慢，或者持續不穩定到執行只係浪費 CI 分鐘數時，請選擇此模式。

### 點解隔離測試會顯示為通過 {#quarantined-passing}

- **靜音測試**仍然會執行。如果靜音測試失敗，會在測試案例執行中記錄為**失敗**並標記為不穩定；單一測試的狀態不會被改寫。被覆蓋的是**整體測試執行**：如果執行中所有失敗的測試案例都已被靜音，則整個執行會被報告為通過，因此靜音失敗不會導致 CI 中斷。
- **跳過測試**完全不會執行，因此儀表板會繼續顯示該測試最後一次實際執行的狀態。該快照可能已過時數週。


### 執行測試 {#running-tests}

`tuist test` 會自動遵循兩種模式：

```sh
tuist test
```

略過嘅測試會以 `-skip-testing` 形式傳遞俾 xcodebuild 且永遠唔會啟動。靜音測試會正常執行；如果失敗，失敗結果會喺最終建構狀態中被隱藏。

要完全繞過隔離並執行所有內容（包括靜音同略過嘅測試）：

```sh
tuist test --skip-quarantine
```

## 壓力測試新測試 {#stress-testing-new-tests}

壓力閘會喺全新進程中多次重新執行你分支新增嘅測試用例，並回報出現不穩定情況嘅用例。你會喺引入該問題嘅拉取請求上即時見到新發現嘅不穩定測試，而唔係幾星期後先至發現。


如果一個測試案例喺過去 90 日內未喺專案嘅預設分支上執行過 CI，或者未喺已合併至該分支嘅提交中執行過，則會被視為新測試案例。使用合併佇列時，佇列執行過嘅測試案例喺佇列提交合併後會被識別，如果佇列將其丟棄，則保持為新測試案例。提交係透過 Tuist 喺 CI 上收集嘅 <.localized_link href="/guides/features/test-insights/xcode#git-history">Git 歷史記錄</.localized_link> 進行匹配。

### 啟用功能 {#enabling-stress-testing}

預設情況下此閘門處於關閉狀態。請設定模式：

- **`report`**：針對每個不穩定的測試案例發出警告。運行仍會根據其自身結果結束。
- **`enforce`**：不穩定的測試案例會導致運行失敗，退出代碼與測試失敗時相同。

先使用 `report` 幾星期，以了解 `enforce` 會攔截什麼情況。


喺兩種模式下，<.localized_link href="/guides/features/selective-testing/generated-xcode-project">選擇性測試</.localized_link> 都唔會喺下一次運行中略過包含不穩定新測試案例嘅測試目標。該目標會再次運行，閘門會再次對該測試案例進行壓力測試，直到其通過所有重試為止。

將佢放喺透傳參數之前，或者設定 `TUIST_TEST_STRESS_NEW_TESTS` 以根據每個 CI 流程變更模式：

```sh
tuist test --stress-new-tests report
```

### 每個測試重新執行嘅次數 {#stress-reruns}

取決於測試案例喺第一次執行時所花嘅時間：

| 第一次執行 | 重新執行次數 |
| --- | --- |
| 最多 5 秒 | 10 |
| 最多 10 秒 | 5 |
| 最多 30 秒 | 3 |
| 最多 5 分鐘 | 2 |
| 超過 5 分鐘 | 唔會重新執行 |

當達到 200 個測試案例或 10 分鐘時，執行就會停止（以較早者為準），並顯示觸發咗邊個限制。


重試會重用第一次構建所產生嘅內容。

### 當閘門未執行 {#when-the-gate-does-not-run}

- 第一輪已失敗。請先修復該等測試。
- 專案沒有預設分支，或尚未在 CI 上執行任何內容。
- 超過 30% 的專案測試案例看似新增。重新執行咁多會耗時過長，得不償失。當專案剛開始向 Tuist 回報，或進行重新命名而一次過移動大量測試時，就會出現此情況。


## Slack 通知 {#slack-notifications}

喺你嘅 Slack 整合入面設定 <.localized_link href="/guides/integrations/slack#flaky-test-alerts">不穩定測試警報</.localized_link>，就可以喺測試變得不穩定時收到通知。


## 查詢不穩定及隔離狀態 {#querying}

### CLI {#querying-cli}

`tuist test case` 指令樹公開 Tuist 追蹤測試案例的所有資料：

```sh
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 {#querying-rest-api}

同樣的資料可透過 HTTP 取得。請參閱 API 參考文件中的[測試案例端點](https://tuist.dev/api/docs#tag/test-cases)，以獲取完整的路由、篩選器及回應欄位清單。要更改測試案例的狀態（標記或取消標記為不穩定、靜音、跳過），請發送 `PATCH /api/projects/{account_handle}/{project_handle}/tests/test-cases/{test_case_id}` 並附上 `is_flaky` 或 `state`。相同的更改亦可透過 `tuist test case update` 及 `update_test_case` MCP 工具進行。

