Swift Testing Expert

Swift Testing Expert

Swift Testing as the default, XCTest where it is still required, and the test-design judgement that outlives both.

Agent Behavior Contract

When this skill is active, follow these rules strictly:

1. Default to Swift Testing for new tests. Match the project's existing framework when adding to a suite that already exists; both can live in the same test target.
2. Name the test after the behavior, not the type — CacheFeedUseCaseTests, not LocalFeedLoaderTests. The method name states the condition and the expected outcome.
3. Every suite gets a makeSUT() factory — it centralizes construction, tracks leaks, and forwards source location. Never share a SUT across tests, and never construct it inline in a test body. One nuance: because Swift Testing creates a fresh suite instance per test, stored let properties initialized in init() are also per-test state — acceptable for trivial construction, but the moment a test needs different construction parameters, leak tracking, or call-site failure reporting, that's makeSUT().
4. Hand-roll test doubles. No mocking frameworks. A spy records messages in an enum array; a stub returns canned values. Keep them separate — see test-doubles-and-strategy.md.
5. Assert observable behavior, not interactions. Prefer "given this input, this output" over "this method was called with these arguments in this order" — except where call order is the contract.
6. Never sleep to wait. Poll for an observable state change with a timeout, or await something real. A fixed delay is either too slow or too short.
7. Prove a test can fail. Before trusting a green test — and always when fixing a bug — see it red first.
8. Do not add production code to satisfy a test. No Equatable conformance, no widened access, no test-only hooks. If a behavior is hard to observe, that's a design signal.
9. Forward source location through helpers so failures report at the call site: sourceLocation: SourceLocation = #_sourceLocation (Swift Testing) or file:/line: (XCTest).
10. Tests are code. Refactor, rename and deduplicate them to the same standard as production.

Testing Diagnostic Table

Gotchas

• Swift Testing runs tests in parallel by default. Anything sharing a store URL, an on-disk artifact, or a registered URLProtocol stub needs .serialized on the suite. XCTest ran serially; this is the single most common migration surprise.
• Tests are not main-actor isolated by default. XCTest ran synchronous test methods on the main thread; Swift Testing runs every test on an arbitrary task. UIKit/SwiftUI suites need @MainActor — and a target compiled with default main-actor isolation (SE-0466 / "Approachable Concurrency") silently flips this. See isolation-and-sendability.md.
• @Test(arguments:) values must be Sendable; the suite type itself need not be. A non-Sendable argument type errors at the attribute — pass a Sendable descriptor and construct inside the test.
• #expect continues; #require stops. Use try #require when the rest of the test is meaningless without the value.
• XCTestExpectation and XCTWaiter are not bridged into Swift Testing and cannot be used safely in a Swift concurrency context. Use confirmation or a continuation.
• #expect(throws:) returns the thrown error (ST-0006), so you can inspect it instead of asserting twice.
• A struct suite gets a fresh instance per test; deinit is only available on a final class or actor suite.
• Task does not cancel on deinit the way AnyCancellable did — async work started by a test can outlive it and produce false memory-leak failures.
• Swift Testing shows sub-expression values on failure — (feed.items.isEmpty → true) == false — so you rarely need a custom assertion message just to see what the value was.
• .serialized on a suite makes its tests run serially, not exclusively — other suites still run in parallel alongside it.

Choosing a level

Measured per-test averages from the source codebase — the reason the pyramid has the shape it does:

Integration test count grows combinatorially with the number of participating components, while unit tests grow linearly. That is the whole argument: test edge cases where they are cheap, and prove collaboration once.

Full reasoning, and why the source codebase deleted its UI-test target entirely: test-doubles-and-strategy.md.

Guardrails

• Do not use a mocking framework — hand-roll the double you need
• Do not assert on interactions when you can assert on outcomes
• Do not add Equatable, widen access, or add hooks to production for a test's benefit
• Do not use Task.sleep or a fixed delay to wait for anything
• Do not leave a waiting helper without a timeout — a stuck job costs CI money
• Do not test logic with snapshot tests
• Do not keep a test for an invariant the compiler now enforces
• Do not chase a coverage number — coverage shows which lines ran, never that behavior is correct
• Do not migrate a whole suite at once; #expect works inside XCTestCase (see xctest-migration.md)

Verification Checklist

1. Every suite has a makeSUT(); no test constructs the SUT inline
2. Test names state a condition and an expected outcome
3. Reference-type SUTs and collaborators are tracked for leaks
4. Suites sharing external state are .serialized
5. No Task.sleep, no fixed delays, and every waiting helper has a timeout
6. Assertion helpers forward #_sourceLocation (or file:/line:)
7. Async tests cancel their pending work in teardown
8. Deliberately break the production code and confirm the relevant test goes red

Reference Router

Open the smallest reference that matches the question:

• Strategy
  • test-doubles-and-strategy.md — dummy/stub/spy/fake/mock, stubbing vs spying, classicist vs mockist, testing network requests, choosing a level
• Craft
  • test-design.md — naming, makeSUT, message-enum spies, DSLs, one assertion per test, snapshots, localization, isolation
• Async
  • async-testing.md — deterministic async tests, async spies, waiting without sleeping, implicit tasks, cancellation and test leaks
• Concurrency & Swift 6
  • isolation-and-sendability.md — @MainActor in tests, default isolation, Sendable requirements for suites/spies/arguments, @Observable view models
• Syntax
  • swift-testing-syntax.md — @Test, @Suite, #expect, #require, confirmation, parameterized tests, traits, tags
• Migration
  • xctest-migration.md — the API translation table, interop modes, trackForMemoryLeaks as a scoping trait, what stays XCTest
• Process
  • tdd-process.md — red/green/refactor, commit discipline, legacy-code extraction, measuring test times