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.

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

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