iOS Testing Best Practices

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.

Clinic Architecture Contract (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)

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

Rule Categories by Priority

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-

Quick Reference

1. Test Architecture & Testability (CRITICAL)

• 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

2. Unit Testing Fundamentals (CRITICAL)

• 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

3. Test Doubles & Isolation (HIGH)

• 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

4. Async & Concurrency Testing (HIGH)

• 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

5. SwiftUI Testing (MEDIUM-HIGH)

• 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

6. UI & Acceptance Testing (MEDIUM)

• 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

7. Snapshot & Visual Testing (MEDIUM)

• 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

8. Test Reliability & CI (LOW-MEDIUM)

• 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

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