# 生成的 Xcode 项目 {#generated-xcode-project-flaky-tests}

> [!IMPORTANT]
> **要求**
>
> - 已配置 <.localized_link href="/guides/features/test-insights/xcode">Xcode 测试洞察</.localized_link>（自动生成的 Scheme 包含 `tuist inspect test` 后置操作；自定义 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。默认情况下，这是**手动操作**：你可以在仪表盘的测试用例详情页面对测试进行隔离、解除隔离并切换模式。你也可以将其接入**设置 → 自动化**下的**自动化告警**，使测试在超过不稳定阈值时自动静音（或跳过），并在恢复后解除隔离。每次状态变更，无论是手动还是自动，都会记录在测试用例的审计日志中。

默认情况下，恢复会等待触发条件不再满足，因此测试会保持隔离状态，直到其旧的不稳定运行离开触发窗口。若要更快恢复，请将**恢复条件**设置为**无新的不稳定运行**：在恢复窗口（天数或运行次数）内没有新的不稳定运行时，测试即恢复；每次出现新的不稳定运行都会重置等待；恢复后，只有新的不稳定运行才会再次将其隔离。


被隔离的测试处于以下两种模式之一：

- **静默**：测试仍然运行，但 `tuist test` 会屏蔽失败结果。失败结果仍会提供给不稳定测试检测器，因此你可以在不中断构建的情况下继续观察该测试。对于正在积极调查的测试，请选择此模式。
- **跳过**：xcodebuild 会收到 `-skip-testing <identifier>`，因此测试永远不会启动。它不会产生新的结果，并从 unstable-tests 仪表板中移除，直到你重新启用它。当测试损坏、运行缓慢或不稳定程度极高以至于运行它只会浪费 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)，以获取完整的路由、过滤器和响应字段列表。要更改测试用例的状态（标记或取消标记为不稳定、静音、跳过），请使用 `is_flaky` 或 `state` 发送 `PATCH /api/projects/{account_handle}/{project_handle}/tests/test-cases/{test_case_id}` 请求。同样的更改也可以通过 `tuist test case update` 以及 `update_test_case` MCP 工具来完成。

