Testing Ios Code

Testing iOS Code

Use this skill to write tests following Bitwarden iOS patterns.

Prerequisites

Read Docs/Testing.md — it is the authoritative source for test structure, naming, templates, decision matrix, and simulator configuration.

Step 1: Choose Framework

| Scenario | Framework | Why |

|----------|-----------|-----|

| New test file | Swift Testing | Preferred for all new tests |

| Existing XCTest file | XCTest | Don't mix frameworks in one file |

| ViewInspector tests | XCTest | ViewInspector requires XCTest |

| Snapshot tests | XCTest | SnapshotTesting requires BitwardenTestCase |

Step 2: Determine Test Type

Choose the right test type based on what you're testing:

| What | Test type | XCTest example | Swift Testing example |

|------|-----------|----------------|----------------------|

| Processor actions/effects/state | Unit test | examples/processor-test-example.md | examples/processor-test-swift-testing-example.md |

| Coordinator navigation/routes | Unit test | examples/coordinator-test-example.md | examples/coordinator-test-swift-testing-example.md |

| View interactions (buttons, toggles) | ViewInspector test | examples/view-test-example.md | — (use XCTest) |

| View appearance | Snapshot test (disabletest_ prefix) | examples/view-test-example.md | — (use XCTest) |

| Service/repository business logic | Unit test | examples/service-test-example.md | examples/service-test-swift-testing-example.md |

Step 3: Test Setup Pattern

Swift Testing (new files)

Use a struct with init() — no teardown needed, value types are discarded after each test:

@MainActor
struct FeatureProcessorTests {
    let coordinator: MockCoordinator<FeatureRoute, FeatureEvent>
    let services: MockServiceContainer
    let subject: FeatureProcessor

    init() {
        coordinator = MockCoordinator()
        services = ServiceContainer.withMocks()
        subject = FeatureProcessor(
            coordinator: coordinator.asAnyCoordinator(),
            services: services,
            state: FeatureState(),
        )
    }
}

XCTest (existing files, ViewInspector, snapshots)

Use a class subclassing BitwardenTestCase with setUp()/tearDown():

class FeatureProcessorTests: BitwardenTestCase {
    var coordinator: MockCoordinator<FeatureRoute, FeatureEvent>!
    var services: MockServiceContainer!
    var subject: FeatureProcessor!

    override func setUp() {
        super.setUp()
        coordinator = MockCoordinator()
        services = ServiceContainer.withMocks()
        subject = FeatureProcessor(
            coordinator: coordinator.asAnyCoordinator(),
            services: services,
            state: FeatureState(),
        )
    }

    override func tearDown() {
        super.tearDown()
        coordinator = nil
        services = nil
        subject = nil
    }
}

See examples/ for complete patterns per test type.

Step 4: Write Tests

Naming

| Framework | Pattern | Example |

|-----------|---------|---------|

| Swift Testing | @Test func <functionName>_<behavior>() | @Test func perform_appeared_loadsData() async |

| XCTest | func test_<functionName>_<behavior>() | func test_perform_appeared_loadsData() async |

Assertions

| XCTest | Swift Testing |

|--------|---------------|

| XCTAssertEqual(a, b) | #expect(a == b) |

| XCTAssertTrue(x) | #expect(x == true) or #expect(x) |

| XCTAssertNil(x) | #expect(x == nil) |

| XCTAssertNotNil(x) | #expect(x != nil) |

| XCTUnwrap(x) | try #require(x) |

| XCTAssertThrowsError | #expect(throws:) { ... } |

Test focus areas

Processor tests — test both paths:

• receive(_:) actions: assert subject.state mutations
• perform(_:) effects: await subject.perform(.effect), then assert state or coordinator calls
• Always test error paths, not just happy path

Service tests — test:

• Successful operations
• Error handling and propagation
• Interactions with mocked dependencies

View tests — test (XCTest only):

• Button taps → processor.dispatchedActions.last (sync)
• Async button taps → processor.effects.last
• State-driven UI (disabled buttons, text content)

Step 5: Verify Co-location

Test files must live alongside implementation files:

BitwardenShared/UI/Auth/Login/LoginProcessor.swift
BitwardenShared/UI/Auth/Login/LoginProcessorTests.swift  ← same directory

Step 6: Mock Generation

New protocols need mocks:

• Add // sourcery: AutoMockable as a trailing comment on the protocol declaration line
• Run ./Scripts/generate-mocks.sh <Framework> where <Framework> matches the target (e.g. BitwardenShared, AuthenticatorShared, BitwardenKit, AuthenticatorBridgeKit) — requires BUILD_DIR, see script header
• Or just build — Sourcery runs automatically in pre-build phase

See references/mock-generation.md for full details.

Conventions

• Fixtures live in the shared fixtures file for their area — reusable SDK-model and CipherView fixtures belong in the shared BitwardenSdk+<Area>Fixtures.swift file for the domain the model belongs to (e.g. CipherView.cardFixture()), not co-located inside an individual test file. Pick the file by area and framework: Vault models go in …/UI/Vault/PreviewContent/BitwardenSdk+VaultFixtures.swift, Auth models in …/Core/Auth/Services/TestHelpers/BitwardenSdk+AuthFixtures.swift, Tools models in …/Core/Tools/Extensions/TestHelpers/BitwardenSdk+ToolsFixtures.swift, and so on — under BitwardenShared for Password Manager or the AuthenticatorShared counterpart for Authenticator. Add new reusable fixtures to the matching file (create the area's fixtures file if one doesn't exist yet).
• Split large test files per feature — when a test file grows unwieldy, break it into <Type>Tests+<Feature>.swift extensions (e.g. AddEditItemProcessorTests+DriversLicense.swift), and author the new file in Swift Testing.
• Snapshot tests — pick the approach with the user — there are two valid patterns, and which fits is a human-discretion call. (1) Instantiate the view directly: build it with a MockProcessor/Store in setUp, then assertSnapshot(of: subject.navStackWrapped, as:) per state (all prefixed disabletest_); see AddEditSendItemView+SnapshotTests.swift. This is required for new views, which use #Preview macros that the snapshot harness cannot enumerate. (2) Iterate PreviewProvider._allPreviews, which is sometimes the better path for views that still expose a PreviewProvider. When a view could go either way, use the AskUserQuestion tool to let the user choose rather than deciding unilaterally — offer (a) instantiate the view directly and (b) iterate PreviewProvider._allPreviews, noting that direct instantiation is required if the view only exposes #Preview macros.