---
name: testing-ios-code
description: Write tests, add test coverage, unit test, or add missing tests for Bitwarden iOS. Use when asked to "write tests", "add test coverage", "test this", "unit test", "add tests for", "missing tests", or when creating test files for new implementations.
---

# 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:

```swift
@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()`:

```swift
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:
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.