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

Step 2: Determine Test Type

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

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

Assertions

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:

1. Add // sourcery: AutoMockable as a trailing comment on the protocol declaration line
2. Run ./Scripts/generate-mocks.sh <Framework> where <Framework> matches the target (e.g. BitwardenShared, AuthenticatorShared, BitwardenKit, AuthenticatorBridgeKit) — requires BUILD_DIR, see script header
3. 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.