# Xcode 不穩定測試 {#xcode-flaky-tests}

> [!IMPORTANT]
> **必要條件**
>
> - 已設定 <.localized_link href="/guides/features/test-insights/xcode">Xcode 測試洞察</.localized_link>。Tuist 會從每次測試執行上傳的測試洞察事件中偵測不穩定測試。

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


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

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

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

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

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

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

```sh
tuist xcodebuild test \
  -scheme 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。預設為**手動操作**：你可以在儀表板的測試案例詳情頁面中，將測試案例加入隔離、解除隔離，並切換模式。你也可以在**設定 → 自動化**下將其連接至**自動化警示**，讓測試在超過不穩定門檻時自動靜音（或略過），並在恢復後解除隔離。每次轉換（無論手動或自動化）都會記錄在測試案例的稽核日誌中。

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


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

- **靜音**：測試仍會執行，但 `tuist xcodebuild test` 會遮蔽失敗結果。失敗結果仍會提供給不穩定測試偵測器，因此你可以持續觀察該測試而不會導致建置失敗。當你正在積極調查某個測試時，請選擇此模式。
- **略過**：xcodebuild 會收到 `-skip-testing <identifier>`，因此測試永遠不會啟動。它不會產生任何新結果，並會從不穩定測試儀表板中移除，直到你重新啟用為止。當測試損壞、執行緩慢，或因持續不穩定而導致執行只是浪費 CI 分鐘數時，請選擇此模式。

### 為何隔離測試可能顯示為通過 {#quarantined-passing}

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


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

`tuist xcodebuild test` 是一個自動支援兩種模式的直通包裝器。使用方式與呼叫 xcodebuild 相同：

```sh
tuist xcodebuild test -scheme MyScheme
```

被略過的測試會以 `-skip-testing <identifier>` 的形式附加到你的 xcodebuild 叫用中，且永遠不會啟動。靜音測試會正常執行；如果它們失敗，失敗結果會在最終的建置狀態中被遮蔽。

#### 繞過隔離 {#bypassing-quarantine}

`tuist xcodebuild test` 接受 `--skip-quarantine` 以執行所有內容，包括靜音和略過的測試：

```sh
tuist xcodebuild test --skip-quarantine -scheme MyScheme
```

#### 直接呼叫 xcodebuild {#calling-xcodebuild-directly}

如果你無法透過 `tuist xcodebuild test` 執行，請使用 `tuist test case list` 自行將被隔離的測試展開為 `-skip-testing` 引數：

```sh
xcodebuild test \
  -scheme MyScheme \
  $(tuist test case list --quarantined --skip-testing)
```

這是在 `tuist xcodebuild test` 之外的安全預設值：靜音測試的失敗遮蔽僅在你透過該命令執行時才會發生，因此略過這兩種模式可以避免虛假的 CI 失敗。如果你需要更細緻的控制，請改為透過 `tuist xcodebuild test` 執行。

## 壓力測試新測試 {#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` 會攔截哪些項目。


將其傳遞至直通引數之前，或設定 `TUIST_TEST_STRESS_NEW_TESTS` 以針對每個 CI 管道變更模式：

```sh
tuist xcodebuild test --stress-new-tests report -scheme MyScheme
```

### 每個測試的重試次數 {#stress-reruns}

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

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

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


重新執行會重複使用第一次執行所建置的內容。

### 閘道未執行時 {#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 工具完成。

