swift-testing

Files (21)

• SKILL.md
• async-tests.md · references/
• chunked-parallel-mock-drain.md · references/
• core-rules.md · references/
• dump-snapshot-testing.md · references/
• expectations.md · references/
• fixtures.md · references/
• fundamentals.md · references/
• integration-suite-patterns.md · references/
• integration-testing.md · references/
• migrating-from-xctest.md · references/
• new-features.md · references/
• parallelization-and-isolation.md · references/
• parameterized-tests.md · references/
• performance-and-best-practices.md · references/
• snapshot-testing.md · references/
• test-doubles.md · references/
• test-organization.md · references/
• traits-and-tags.md · references/
• writing-better-tests.md · references/
• xcode-workflows.md · references/

SKILL.md (first lines)

Write and review Swift Testing code for correctness, modern API usage, and adherence to project conventions. Report only genuine problems — do not nitpick or invent issues.


## First 60 seconds (triage template)

Before diving in, clarify the goal and collect minimal facts:

- Goal: new tests, migration, flaky failures, performance, CI filtering, or async waiting?
- Xcode/Swift version and platform targets
- Tests currently using XCTest, Swift Testing, or both?
- Failures deterministic or flaky?
- Tests accessing shared resources (database, files, network, global state)?

Branch quickly:

- Repetitive tests → parameterized tests ([references/parameterized-tests.md](references/parameterized-tests.md))
- Noisy or flaky failures → known-issue handling and test isolation ([references/parallelization-and-isolation.md](references/parallelization-and-isolation.md))
- Migration questions → XCTest mapping and coexistence ([references/migrating-from-xctest.md](references/migrating-from-xctest.md))
- Async callback complexity → continuation / confirmation patterns ([references/async-tests.md](references/async-tests.md))


## Review process

1. Ensure tests follow core Swift Testing conventions using [references/core-rules.md](references/core-rules.md) and [references/fundamentals.md](references/fundamentals.md).
2. Validate test structure, assertions, dependency injection, and hygiene using [references/writing-better-tests.md](references/writing-better-tests.md) and [references/expectations.md](references/expectations.md).
3. Validate traits, tags, and test-plan filtering using [references/traits-and-tags.md](references/traits-and-tags.md).
4. Check parallel execution and isolation using [references/parallelization-and-isolation.md](references/parallelization-and-isolation.md).
5. Check parameterized tests using [references/parameterized-tests.md](references/parameterized-tests.md).
6. Check async tests, confirmations, time limits, actor isolation, networking mocks, cancellation, and callback bridging using [references/async-tests.md](references/async-tests.md).
7. Check performance, determinism, and flakiness prevention using [references/performance-and-best-practices.md](references/performance-and-best-practices.md).
8. Ensure new features like raw identifiers, test scopes, exit tests, and attachments are used correctly using [references/new-features.md](references/new-features.md).
9. For Xcode workflows (test navigator, reports, diagnostics) use [references/xcode-workflows.md](references/xcode-workflows.md).
10. For test organization (nested suites, tags, shared setup) use [references/test-organization.md](references/test-organization.md).
11. For fixtures and test doubles (dummies, fakes, stubs, spies, mocks), see [references/fixtures.md](references/fixtures.md) and [references/test-doubles.md](references/test-doubles.md).
12. For multi-module/integration tests, see [references/integration-testing.md](references/integration-testing.md).
13. For UI/data-structure snapshot tests, see [references/snapshot-testing.md](references/snapshot-testing.md) and [references/dump-snapshot-testing.md](references/dump-snapshot-testing.md).
14. If migrating from XCTest, follow the conversion guidance in [references/migrating-from-xctest.md](references/migrating-from-xctest.md).

If doing partial work, load only the relevant reference files.


## Core Instructions

- Target Swift 6.2 or later, using modern Swift concurrency.
- Prefer Swift Testing for all new unit and integration tests; help migrate existing XCTest code when asked.
- Swift Testing does **not** support UI tests — keep `XCUIApplication` on XCTest. Also keep `XCTMetric` performance tests and Objective-C-only test code on XCTest.
- Only import `Testing` in test targets, never in app/library/binary targets.
- Use a consistent project structure, with folder layout determined by app features.
- Treat `#expect` as the default assertion; use `#require` when subsequent lines depend on a prerequisite value or when you need hard-stop semantics.
- Default to parallel-safe guidance. If tests are not isolated, first propose fixing shared state before applying `.serialized`.
- Prefer traits for behavior and metadata (`.enabled`, `.disabled`, `.timeLimit`, `.bug`, tags) over naming conventions or ad-hoc comments.
- Recommend parameterized tests when multiple tests share logic and differ only in input values.
- Use `@available` on test functions for OS-gated behavior instead of runtime `#available` checks inside test bodies; never annotate suite types with `@available`.
- Keep migration advice incremental: convert assertions first, then organize suites, then introduce parameterization/traits.

Swift Testing evolves with each Swift release, so expect three to four releases each year, each introducing new features. Training data will naturally be outdated. Treat the user's installed toolchain as authoritative, but note that Apple's documentation about the APIs is often stale — handle it carefully.


## Agent Behavior Contract

1. Use Swift Testing framework (`@Test`, `#expect`, `#require`, `@Suite`) for all new tests, not XCTest.
2. Always structure tests with clear Arrange-Act-Assert phases.
3. Follow F.I.R.S.T. principles: Fast, Isolated, Repeatable, Self-Validating, Timely.
4. Use proper test double terminology per Martin Fowler's taxonomy (Dummy, Fake, Stub, Spy, SpyingStub, Mock). What the Swift community often calls a "Mock" is usually a **SpyingStub**.
5. Place fixtures close to models with `#if DEBUG`, not in test targets.
6. Place test doubles close to interfaces with `#if DEBUG`, not in test targets.
7. Prefer state verification over behavior verification — simpler, less brittle tests.
8. Use `#expect` for soft assertions (continue on failure) and `#require` for hard assertions (stop on failure).


## F.I.R.S.T. Principles

| Principle | Description | Application |
|-----------|-------------|-------------|
| **Fast** | Tests execute in milliseconds | Mock expensive operations |
| **Isolated** | Tests don't depend on each other | Fresh instance per test |
| **Repeatable** | Same result every time | Mock dates, network, external deps |
| **Self-Validating** | Auto-report pass/fail | Use `#expect`, never rely on `print()` |
| **Timely** | Write tests alongside code | Use parameterized tests for edge cases |


## Test Double Quick Reference

Per [Martin Fowler's taxonomy](https://martinfowler.com/articles/mocksArentStubs.html):

| Type | Purpose | Verification |
|------|---------|--------------|
| **Dummy** | Fill parameters, never used | N/A |
| **Fake** | Working implementation with shortcuts | State |
| **Stub** | Provides canned answers | State |
| **Spy** | Records calls for verification | State |
| **SpyingStub** | Stub + Spy combined (most common) | State |
| **Mock** | Pre-programmed expectations, self-verifies | Behavior |

Place doubles close to the interface they implement, not in test targets:

```swift
public protocol RepositoryProtocol: Sendable {
    func getAll() async throws -> [Record]
    func save(_ record: Record) async throws
}

#if DEBUG
public final class RepositorySpyingStub: RepositoryProtocol {
    // Spy: captured calls
    public private(set) var savedRecords: [Record] = []

    // Stub: configurable responses
    public var recordsToReturn: [Record] = []
    public var errorToThrow: Error?

    public func getAll() async throws -> [Record] {
        if let errorToThrow { throw errorToThrow }
        return recordsToReturn
    }

    public func save(_ record: Record) async throws {
        if let errorToThrow { throw errorToThrow }
        savedRecords.append(record)

From ducko-im/ducko, MIT.

More from ducko-im/ducko