swift-testing

name	swift-testing
description	Write, review, or migrate unit tests using Swift Testing (@Test, @Suite, #expect, #require). Use when writing new tests, converting existing Quick+Nimble specs to Swift Testing, reviewing test quality, debugging flaky tests, or improving test structure in this iOS template project. Triggers on: "write test", "add test", "test this", "migrate test", "convert spec", "Swift Testing".

Swift Testing

Overview

Write, review, migrate, and debug tests using Swift Testing for this iOS template project. This project uses Quick + Nimble (*Spec.swift) as the legacy framework and Swift Testing (*Tests.swift) for all new tests.

Agent Behavior Contract

1. Swift Testing for all new unit/integration tests. Retain Quick+Nimble only for existing specs; do not migrate unless asked.
2. Use #expect as the default assertion; use #require only when subsequent lines depend on a prerequisite value.
3. Design tests to run safely in parallel by default. Fix shared state before reaching for .serialized.
4. Use inline private struct / private actor stubs conforming to domain protocols — no generated mocks.
5. Use actor stubs when the protocol requires async or has mutable state; use struct stubs otherwise.
6. Prefer parameterized tests (@Test(arguments:)) over duplicated test methods.
7. Use traits (.enabled, .disabled, .timeLimit, .bug, .tags) instead of ad-hoc comments.
8. Import Testing only in test targets, never in app/library targets.
9. Keep tests deterministic — no real network calls. Use NetworkStubber (OHHTTPStubs) for network-level tests.

Quick Triage

Before writing or reviewing tests, clarify:

1. New or migration? Writing fresh tests vs converting an existing *Spec.swift.
2. Which module? App ({PROJECT_NAME}Tests/), Data (Modules/Data/Tests/), Domain (Modules/Domain/Tests/), or Model (Modules/Model/Tests/).
3. Async? Does the code under test use async/await?
4. Shared resources? Database, network, file system, or singleton state involved?

File Naming & Placement

Framework	Suffix	Placement
Swift Testing	*Tests.swift	Tests/Sources/ mirroring production path (e.g. Repositories/, Entities/)
Quick + Nimble	*Spec.swift	Tests/Sources/Specs/

Canonical Pattern (this project)

import Testing

@testable import Data
import Domain

@Suite("DefaultRemoteConfigRepository")
struct DefaultRemoteConfigRepositoryTests {

    @Test("returns a typed stored value")
    func returnsATypedStoredValue() async {
        let booleanKey = RemoteConfigKey(name: "feature_enabled", defaultValue: false)
        let repository = DefaultRemoteConfigRepository(
            source: StubRemoteConfigSource(values: [
                booleanKey.name: .string("true")
            ])
        )

        let value = await repository.value(for: booleanKey)

        #expect(value == true)
    }
}

private actor StubRemoteConfigSource: RemoteConfigSource {

    private let values: [String: RemoteConfigStoredValue]

    init(values: [String: RemoteConfigStoredValue] = [:]) {
        self.values = values
    }

    func refresh() async throws {}

    func value(forKey key: String) async -> RemoteConfigStoredValue? {
        values[key]
    }
}

Key observations:

• struct suite, not class
• @Suite("DisplayName") with human-readable name matching the type under test
• @Test("description") with lowercase sentence describing behavior
• Function name is camelCase matching the description (no test prefix)
• Arrange / Act / Assert with blank line separations
• Inline private actor stub at bottom of file (actor because protocol has async)
• @testable import for the module under test; regular import for its dependencies

Routing to References

Load the appropriate reference file based on the task:

Task	Reference
Writing new tests, suite structure, naming	references/fundamentals.md
Assertions, error checking, known issues	references/expectations.md
Traits, tags, conditional execution	references/traits-and-tags.md
Data-driven / parameterized tests	references/parameterized-testing.md
Async/await, callbacks, confirmations	references/async-testing.md
Creating stubs, fakes, network mocks	references/test-doubles.md

Verification Checklist

Before finishing, confirm:

• Each test verifies one clear behavior
• #require is used for prerequisites; #expect for everything else
• Parameterized tests replace duplicated test methods
• Tests are parallel-safe (no shared mutable state)
• Async tests use async functions directly (no Task.sleep hacks)
• Stubs are private struct or private actor at bottom of file
• File is named *Tests.swift and placed in the correct module test directory
• No real network calls — NetworkStubber or protocol stubs used