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

arch-

unit-

mock-

async-

swiftui-

ui-

snap-

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