跳至内容

生成的 Xcode 项目

要求
  • 已配置 Xcode 测试洞察(自动生成的 Scheme 包含 tuist inspect test 后置操作;自定义 Scheme 需要手动添加)。

不稳定测试是指使用相同代码多次运行时产生不同结果(通过或失败)的测试。它们会削弱你对测试套件的信任,并浪费开发人员排查误报失败的时间。Tuist 会自动检测不稳定测试,并帮助你持续跟踪它们。

不稳定测试页面

不稳定检测的工作原理#

Tuist 通过两种方式检测不稳定测试:

测试重试#

当你运行带有重试功能的测试时,Tuist 会分析每次尝试的结果。如果某次测试在某些尝试中失败而在其他尝试中通过,则会被标记为不稳定。

通过 tuist test 传递 -retry-tests-on-failure 或 -test-iterations:

bash
tuist test MyScheme -- -retry-tests-on-failure -test-iterations 3

不稳定测试用例详情

跨运行检测#

即使不启用测试重试,Tuist 也能通过比较同一提交、同一 Scheme 和同一报告目标(设备名称、平台和操作系统版本)下不同 CI 运行的结果来检测不稳定测试。如果某个测试在一次匹配的 CI 运行中通过,而在另一次中失败,则将该失败的执行标记为不稳定。无论哪个结果先到达,此机制均有效。

同一测试在不同 Scheme 或目标上的表现可能始终不同。例如,在 iOS 26 上通过而在 iOS 27 上失败并不构成不稳定。来自不同 Scheme、设备、平台或操作系统版本的结果不会相互标记为不稳定。

缺少目标元数据的运行,或涵盖多个目标的运行,仅彼此之间进行比较,因此它们之间的环境差异仍可能被报告为不稳定。基于重试的检测仍然适用。

这对于捕获那些因失败不够一致而无法通过重试发现、但仍会导致 CI 间歇性失败的不稳定测试尤为有用。

管理不稳定测试#

自动清除#

检测与清除通过项目上的自动化提醒执行。每个项目都会获得一个默认的“不稳定测试检测”自动化,其触发器会将测试标记为不稳定,而一旦测试在配置恢复窗口(默认14 天)内未再次触发,其恢复就会清除该标记。在设置 → 自动化中编辑它,可以更改恢复窗口、更改恢复操作(例如,同时将测试从隔离中释放),或完全禁用恢复,以便测试保持标记为不稳定状态,直到你手动清除它们。

手动管理#

你还可以在测试用例详情页面手动将测试标记或取消标记为不稳定。这在以下情况下很有用:

  • 希望在修复已知不稳定测试时予以确认
  • 由于基础设施问题导致测试被错误标记

隔离不稳定测试#

隔离会将不稳定测试单独处理,使其在你修复期间不会阻塞 CI。默认情况下,这是一个手动操作:你可以在仪表板的测试用例详情页中隔离测试、解除隔离并切换模式。你也可以在设置 → 自动化下将其接入自动化警报,这样当测试超过不稳定阈值时会自动静音(或跳过),并在恢复后解除隔离。每次状态变更,无论是手动还是自动,都会记录在测试用例的审计日志中。

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

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

  • 跳过:xcodebuild 会收到 tuist test,因此测试永远不会启动。它不会产生新的结果,并从不稳定测试仪表板中消失,直到你重新启用它。当测试损坏、缓慢或不稳定程度极高,以至于运行它只会浪费 CI 分钟数时,请选择此模式。
  • 跳过:xcodebuild 会收到 -skip-testing <identifier>,因此该测试永远不会启动。它不会产生新的结果,并从 unstable-tests 仪表板中移除,直到你重新启用它。当测试损坏、缓慢或持续不稳定以至于运行它只是浪费 CI 分钟数时,请选择此选项。

为何隔离的测试可能显示为通过#

  • 静音测试仍会执行。失败的静音测试会在测试用例运行中被记录为失败并标记为不稳定;单个测试的状态不会被改写。被覆盖的是整体测试运行:如果运行中所有失败的测试用例都被静音,则整个运行会被报告为通过,因此静音的失败不会导致 CI 中断。
  • 跳过的测试根本不会运行,因此仪表板会继续显示该测试最后一次实际执行的状态。该快照可能已有数周之久。

{#running-tests} 会自动遵循这两种模式:#

跳过的测试会以 tuist test 的形式传递给 xcodebuild,且永远不会启动。静音测试正常运行;如果它们失败,失败结果会在最终的构建状态中被屏蔽。

bash
tuist test

跳过的测试会以 -skip-testing 的形式传递给 xcodebuild,并且永远不会启动。静音测试正常运行;如果它们失败,失败信息会在最终的构建状态中被屏蔽。

要完全绕过隔离并运行所有内容,包括静音和跳过的测试:

bash
tuist test --skip-quarantine

对新测试进行压力测试#

压力测试门会多次在全新进程中重新运行你的分支新增的测试用例,并报告其中不稳定的用例。你可以在引入该问题的拉取请求上立即看到新的不稳定测试,而不是几周后才发现。

在这两种模式下,选择性测试都不会在下一次运行时跳过包含不稳定新测试用例的测试目标。该目标会再次运行,门禁会再次对该测试用例进行压力测试,直到其通过所有重试。

启用该功能#

默认情况下,此开关处于关闭状态。请设置一种模式:

  • report:针对每个不稳定测试用例发出警告。运行仍将根据其自身结果退出。
  • enforce:不稳定测试用例会导致运行失败,退出代码与失败的测试相同。

先使用 report 几周,以了解 enforce 会拦截哪些内容。

在这两种模式下,选择性测试 不会在下一次运行时跳过包含不稳定新测试用例的测试目标。该目标会再次运行,门禁会再次对该测试用例进行压力测试,直到它通过所有重运行为止。

将其放在透传参数之前,或设置 TUIST_TEST_STRESS_NEW_TESTS 以针对每个 CI 通道调整模式:

bash
tuist test --stress-new-tests report

每个测试用例的重试次数#

取决于测试用例在首次运行时的耗时:

首次运行重试次数
不超过 5 秒10
不超过 10 秒5
不超过 30 秒3
不超过 5 分钟2
超过 5 分钟不重试

当达到 200 个测试用例或 10 分钟时(以先到达者为准),本轮运行将停止,并提示触发了哪个限制。

重运行会复用第一次构建的内容。

门禁未运行时#

  • 首轮执行已失败。请先修复这些测试。
  • 项目没有默认分支,或者尚未在 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 工具完成。