ios-testing

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