OpenParable
Skip to content
← Back to skills

Testing IOS Code

Testing & Quality
testing-ios-code

Testing IOS Code is an Agent Skill for testing & quality published in the bitwarden/ios repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/bitwarden/ios/blob/HEAD/.claude/skills/testing-ios-code/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/testing-ios-code, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

ScenarioFrameworkWhy
New test fileSwift TestingPreferred for all new tests
Existing XCTest fileXCTestDon't mix frameworks in one file
ViewInspector testsXCTestViewInspector requires XCTest
Snapshot testsXCTestSnapshotTesting requires BitwardenTestCase

Step 2: Determine Test Type

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

WhatTest typeXCTest exampleSwift Testing example
Processor actions/effects/stateUnit testexamples/processor-test-example.mdexamples/processor-test-swift-testing-example.md
Coordinator navigation/routesUnit testexamples/coordinator-test-example.mdexamples/coordinator-test-swift-testing-example.md
View interactions (buttons, toggles)ViewInspector testexamples/view-test-example.md— (use XCTest)
View appearanceSnapshot test (disabletest_ prefix)examples/view-test-example.md— (use XCTest)
Service/repository business logicUnit testexamples/service-test-example.mdexamples/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

FrameworkPatternExample
Swift Testing@Test func <functionName>_<behavior>()@Test func perform_appeared_loadsData() async
XCTestfunc test_<functionName>_<behavior>()func test_perform_appeared_loadsData() async

Assertions

XCTestSwift 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.