ios-testing

iOS 测试最佳实践

面向 iOS 和 Swift 应用的综合测试指南，达到首席工程师级别。包含 8 个类别、44 条规则，按影响力排序，帮助指导测试架构决策、测试编写模式和 CI 基础设施。

Clinic 架构约定（iOS 26 / Swift 6.2）

本指南中的所有建议都基于 Clinic 模块化 MVVM-C 架构：

• 功能模块仅导入 Domain + DesignSystem（绝不导入 Data，也不导入同级功能模块）
• App 目标是汇合点，并负责管理 DependencyContainer、具体协调器以及 Route Shell 接线
• Domain 保持纯 Swift，并定义模型以及 repository、*Coordinating、ErrorRouting 和 AppError 契约
• Data 负责 SwiftData／网络／同步／重试／后台 I/O，并实现 Domain 协议
• 读写流程默认采用陈旧数据优先、后台重新验证的读取方式，以及乐观排队写入
• ViewModel 直接调用 repository 协议（默认不设 use-case／interactor 层）

适用场景

在以下场景中参考这些指南：

• 为 iOS 应用编写新的单元测试或 UI 测试
• 通过依赖注入设计可测试的架构
• 测试 async/await、actor 和 Combine 发布者
• 设置快照测试或视觉回归测试套件
• 配置 CI 流水线、测试计划和并行执行

按优先级划分的规则类别

优先级	类别	影响	前缀
1	测试架构与可测试性	关键	arch-
2	单元测试基础	关键	unit-
3	测试替身与隔离	高	mock-
4	异步与并发测试	高	async-
5	SwiftUI 测试	中高	swiftui-
6	UI 与验收测试	中	ui-
7	快照与视觉测试	中	snap-
8	测试可靠性与 CI	低中	ci-

快速参考

1. 测试架构与可测试性（关键）

• arch-protocol-dependencies - 依赖协议，而非具体类型
• arch-constructor-injection - 优先使用构造器注入，而非服务定位器
• arch-test-target-separation - 分离单元测试目标和 UI 测试目标
• arch-testable-import - 谨慎使用 @testable import
• arch-single-responsibility-tests - 每个测试聚焦一个断言概念
• arch-arrange-act-assert - 按 Arrange-Act-Assert 结构组织测试

2. 单元测试基础（关键）

• unit-swift-testing-framework - 新测试优先使用 Swift Testing，而非 XCTest
• unit-parameterized-tests - 使用参数化测试覆盖不同输入
• unit-descriptive-test-names - 根据测试验证的行为为测试命名
• unit-expect-over-assert - 优先使用 #expect 和 #require，而非 XCTAssert
• unit-require-preconditions - 使用 #require 检查测试前置条件
• unit-test-suites - 将相关测试整理到测试套件中
• unit-test-tags - 使用标签对横切测试进行分类

3. 测试替身与隔离（HIGH）

• mock-protocol-based-mocks - 基于协议而非子类创建 Mock
• mock-spy-for-verification - 使用 Spy 验证交互
• mock-stub-return-values - 使用 Stub 提供确定的返回值
• mock-avoid-over-mocking - 避免 Mock 值类型和简单逻辑
• mock-fake-for-integration - 使用内存中的 Fake 进行集成测试
• mock-dependency-container - 使用依赖容器配置测试

4. 异步与并发测试（HIGH）

• async-await-directly - 在测试中直接等待异步函数
• async-confirmation - 对基于回调的 API 使用 confirmation()
• async-mainactor-isolation - 在 MainActor 上测试隔离于 MainActor 的代码
• async-actor-testing - 通过异步接口测试 Actor 状态
• async-task-cancellation - 明确测试任务取消路径

5. SwiftUI 测试（MEDIUM-HIGH）

• swiftui-test-observable-models - 将 @Observable 模型作为普通对象进行测试
• swiftui-environment-injection - 为测试注入环境依赖项
• swiftui-preview-as-test - 将预览用作视觉冒烟测试
• swiftui-view-model-extraction - 将视图中的逻辑提取到可测试的模型中
• swiftui-binding-testing - 使用 @Bindable 测试绑定行为

6. UI 与验收测试（MEDIUM）

• ui-accessibility-identifiers - 使用辅助功能标识符查询元素
• ui-page-object-pattern - 使用页面对象封装屏幕
• ui-launch-arguments - 通过启动参数配置测试状态
• ui-wait-for-elements - 等待元素，而不是使用 sleep()
• ui-test-user-journeys - 测试完整的用户旅程，而非单个屏幕
• ui-reset-state-between-tests - 在 UI 测试之间重置应用状态

7. 快照与视觉测试（MEDIUM）

• snap-swift-snapshot-testing - 使用 swift-snapshot-testing 进行视觉回归测试
• snap-device-matrix - 针对不同设备尺寸和特征进行快照测试
• snap-named-references - 使用命名快照参考以提高清晰度
• snap-inline-snapshots - 对非图像断言使用内联快照

8. 测试可靠性与 CI（LOW-MEDIUM）

• ci-test-plans - 使用 Xcode Test Plans 配置环境
• ci-parallel-execution - 启用并行测试执行
• ci-flaky-test-quarantine - 隔离不稳定测试，而不是禁用它们
• ci-deterministic-test-data - 使用确定性测试数据，而非随机生成的数据
• ci-coverage-thresholds - 为关键路径设置覆盖率阈值

使用方法

请阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 分类结构和影响级别
• 规则模板 - 添加新规则的模板

参考文件

文件	描述
references/_sections.md	分类定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息