ios-testing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

iOS Testing Best Practices

iOS测试最佳实践

Comprehensive testing guide for iOS and Swift applications, written at principal engineer level. Contains 44 rules across 8 categories, prioritized by impact to guide test architecture decisions, test authoring patterns, and CI infrastructure.

这是一份面向iOS和Swift应用的全面测试指南，由资深工程师编写。包含8个类别共44条规则，按影响优先级排序，用于指导测试架构决策、测试编写模式和CI基础设施配置。

Clinic Architecture Contract (iOS 26 / Swift 6.2)

诊所架构约定（iOS 26 / Swift 6.2）

All guidance in this skill assumes the clinic modular MVVM-C architecture:

Feature modules import
```
Domain
```
+
```
DesignSystem
```
only (never
```
Data
```
, never sibling features)
App target is the convergence point and owns
```
DependencyContainer
```
, concrete coordinators, and Route Shell wiring
```
Domain
```
stays pure Swift and defines models plus repository,
```
*Coordinating
```
,
```
ErrorRouting
```
, and
```
AppError
```
contracts
```
Data
```
owns SwiftData/network/sync/retry/background I/O and implements Domain protocols
Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes
ViewModels call repository protocols directly (no default use-case/interactor layer)

本技能中的所有指导均基于诊所模块化MVVM-C架构：

功能模块仅导入
```
Domain
```
+
```
DesignSystem
```
（绝不导入
```
Data
```
，也不导入同级功能模块）
App目标是聚合点，拥有
```
DependencyContainer
```
、具体的coordinator和路由壳层的连接逻辑
```
Domain
```
层保持纯Swift实现，定义模型以及repository、
```
*Coordinating
```
、
```
ErrorRouting
```
和
```
AppError
```
协议
```
Data
```
层负责SwiftData/网络/同步/重试/后台I/O，并实现Domain层协议
默认读写流程为“读取时返回过期数据并后台刷新”的读操作，以及乐观队列式写操作
ViewModel直接调用repository协议（默认不使用用例/交互器层）

When to Apply

适用场景

Reference these guidelines when:

Writing new unit tests or UI tests for iOS apps
Designing testable architecture with dependency injection
Testing async/await, actors, and Combine publishers
Setting up snapshot testing or visual regression suites
Configuring CI pipelines, test plans, and parallel execution

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

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

Rule Categories by Priority

按优先级划分的规则类别


arch-
unit-
mock-
async-
swiftui-
ui-
snap-
ci-

Priority	Category	Impact	Prefix
1	Test Architecture & Testability	CRITICAL	`arch-`
2	Unit Testing Fundamentals	CRITICAL	`unit-`
3	Test Doubles & Isolation	HIGH	`mock-`
4	Async & Concurrency Testing	HIGH	`async-`
5	SwiftUI Testing	MEDIUM-HIGH	`swiftui-`
6	UI & Acceptance Testing	MEDIUM	`ui-`
7	Snapshot & Visual Testing	MEDIUM	`snap-`
8	Test Reliability & CI	LOW-MEDIUM	`ci-`


arch-
unit-
mock-
async-
swiftui-
ui-
snap-
ci-

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

Quick Reference

快速参考

1. Test Architecture & Testability (CRITICAL)

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

```
arch-protocol-dependencies
```
- Depend on protocols, not concrete types
```
arch-constructor-injection
```
- Use constructor injection over service locators
```
arch-test-target-separation
```
- Separate unit and UI test targets
```
arch-testable-import
```
- Use @testable import sparingly
```
arch-single-responsibility-tests
```
- One assertion concept per test
```
arch-arrange-act-assert
```
- Structure tests as Arrange-Act-Assert

```
arch-protocol-dependencies
```
- 依赖协议而非具体类型
```
arch-constructor-injection
```
- 使用构造函数注入而非服务定位器
```
arch-test-target-separation
```
- 分离单元测试和UI测试目标
```
arch-testable-import
```
- 谨慎使用@testable import
```
arch-single-responsibility-tests
```
- 每个测试仅验证一个行为概念
```
arch-arrange-act-assert
```
- 按照“准备-执行-断言”结构编写测试

2. Unit Testing Fundamentals (CRITICAL)

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

```
unit-swift-testing-framework
```
- Use Swift Testing over XCTest for new tests
```
unit-parameterized-tests
```
- Use parameterized tests for input variations
```
unit-descriptive-test-names
```
- Name tests after the behavior they verify
```
unit-expect-over-assert
```
- Use #expect and #require over XCTAssert
```
unit-require-preconditions
```
- Use #require for test preconditions
```
unit-test-suites
```
- Organize related tests into suites
```
unit-test-tags
```
- Use tags to categorize cross-cutting tests

```
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. Test Doubles & Isolation (HIGH)

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

```
mock-protocol-based-mocks
```
- Create mocks from protocols, not subclasses
```
mock-spy-for-verification
```
- Use spies to verify interactions
```
mock-stub-return-values
```
- Use stubs for deterministic return values
```
mock-avoid-over-mocking
```
- Avoid mocking value types and simple logic
```
mock-fake-for-integration
```
- Use in-memory fakes for integration tests
```
mock-dependency-container
```
- Use a dependency container for test configuration

```
mock-protocol-based-mocks
```
- 基于协议创建模拟对象，而非子类
```
mock-spy-for-verification
```
- 使用间谍对象验证交互
```
mock-stub-return-values
```
- 使用存根对象提供确定的返回值
```
mock-avoid-over-mocking
```
- 避免对值类型和简单逻辑进行模拟
```
mock-fake-for-integration
```
- 集成测试使用内存中的伪实现
```
mock-dependency-container
```
- 使用依赖容器配置测试环境

4. Async & Concurrency Testing (HIGH)

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

```
async-await-directly
```
- Await async functions directly in tests
```
async-confirmation
```
- Use confirmation() for callback-based APIs
```
async-mainactor-isolation
```
- Test MainActor-isolated code on MainActor
```
async-actor-testing
```
- Test actor state through async interface
```
async-task-cancellation
```
- Test task cancellation paths explicitly

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

5. SwiftUI Testing (MEDIUM-HIGH)

5. SwiftUI测试（中高）

```
swiftui-test-observable-models
```
- Test @Observable models as plain objects
```
swiftui-environment-injection
```
- Inject environment dependencies for tests
```
swiftui-preview-as-test
```
- Use previews as visual smoke tests
```
swiftui-view-model-extraction
```
- Extract logic from views into testable models
```
swiftui-binding-testing
```
- Test binding behavior with @Bindable

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

6. UI & Acceptance Testing (MEDIUM)

6. UI与验收测试（中）

```
ui-accessibility-identifiers
```
- Use accessibility identifiers for element queries
```
ui-page-object-pattern
```
- Encapsulate screens in page objects
```
ui-launch-arguments
```
- Configure test state via launch arguments
```
ui-wait-for-elements
```
- Wait for elements instead of using sleep()
```
ui-test-user-journeys
```
- Test complete user journeys, not individual screens
```
ui-reset-state-between-tests
```
- Reset app state between UI tests

```
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. Snapshot & Visual Testing (MEDIUM)

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

```
snap-swift-snapshot-testing
```
- Use swift-snapshot-testing for visual regression
```
snap-device-matrix
```
- Snapshot across device sizes and traits
```
snap-named-references
```
- Use named snapshot references for clarity
```
snap-inline-snapshots
```
- Use inline snapshots for non-image assertions

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

8. Test Reliability & CI (LOW-MEDIUM)

8. 测试可靠性与CI（中低）

```
ci-test-plans
```
- Use Xcode Test Plans for environment configurations
```
ci-parallel-execution
```
- Enable parallel test execution
```
ci-flaky-test-quarantine
```
- Quarantine flaky tests instead of disabling them
```
ci-deterministic-test-data
```
- Use deterministic test data over random generation
```
ci-coverage-thresholds
```
- Set coverage thresholds for critical paths

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

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件以获取详细说明和代码示例：

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

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

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