@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/swift-testing/references/testing-patterns.md

@@ -1,109 +1,73 @@
-# Swift Testing Patterns Reference
+# Swift Testing Patterns
 
-## Contents
-- Basic Tests and Traits
-- Expectations and Requirements
-- Suite Organization
-- Parameterized Tests
-- Execution Model
-- Confirmation and Known Issues
-- Tags
-- TestScoping and Test Organization
-- XCTest Migration Patterns
-- Mocking and Test Doubles
-- Testable Architecture
-- Async and Concurrent Tests
-- XCTest UI Tests  -  Page Object Pattern
-- Performance Testing
-- Snapshot Testing
-- Test Attachments
-- Exit Testing
-- Test File Organization
-- What to Test
-- Common Mistakes and Review Checklist
-
-## Basic Tests and Traits
-
-```swift
-import Testing
-
-@Test("User can update their display name")
-func updateDisplayName() {
-    var user = User(name: "Alice")
-    user.name = "Bob"
-    #expect(user.name == "Bob")
-}
+Companion to the `swift-testing` skill.
 
-@Test(.tags(.validation, .email))
-func validatesEmailFormat() { /* ... */ }
-```
+## Contents
 
-## Expectations and Requirements
+- [Suites](#suites)
+- [Parameterized Tests](#parameterized-tests)
+- [Execution Model](#execution-model)
+- [Confirmations](#confirmations)
+- [Known Issues Limited to Specific Failures](#known-issues-limited-to-specific-failures)
+- [Tags](#tags)
+- [Scoped Setup and Teardown with `TestScoping`](#scoped-setup-and-teardown-with-testscoping)
+- [From XCTest, Step by Step](#from-xctest-step-by-step)
+- [Test Doubles](#test-doubles)
+- [Designing for Tests](#designing-for-tests)
+- [Async and Time](#async-and-time)
+- [UI Tests Stay on XCTest](#ui-tests-stay-on-xctest)
+- [Performance Tests Stay on XCTest](#performance-tests-stay-on-xctest)
+- [Snapshot Tests](#snapshot-tests)
+- [Attachments from Files](#attachments-from-files)
+- [Exit Tests](#exit-tests)
+- [Organising Files](#organising-files)
+- [Readable Arguments](#readable-arguments)
+- [Tests That Need a Newer OS](#tests-that-need-a-newer-os)
+- [More Mistakes to Avoid](#more-mistakes-to-avoid)
+
+## Suites
 
 ```swift
-#expect(result == 42)
-#expect(name.isEmpty == false)
-#expect(items.count > 0, "Items should not be empty")
-
-// Error type checking
-#expect(throws: ValidationError.self) {
-    try validate(email: "not-an-email")
-}
-
-// Specific error matching
-#expect {
-    try validate(email: "")
-} throws: { error in
-    guard let err = error as? ValidationError else { return false }
-    return err == .empty
-}
-
-// #require unwraps or fails the test
-let user = try #require(await fetchUser(id: 1))
-let first = try #require(items.first)
-```
-
-**Rule: Use `#require` when subsequent assertions depend on the value. Use `#expect` for independent checks.**
-
-## Suite Organization
+import Testing
+@testable import Ledger
 
-```swift
-@Suite("User Authentication")
-struct AuthTests {
-    let service: AuthService
-    let mockRepo: MockUserRepository
+@Suite("Sign-in")
+struct SignInTests {
+    let gateway: FakeAuthGateway
+    let session: SessionController
 
-    // init() replaces setUp() -- runs before each test
     init() {
-        mockRepo = MockUserRepository()
-        service = AuthService(repository: mockRepo)
+        gateway = FakeAuthGateway()
+        session = SessionController(gateway: gateway)
     }
 
-    @Test func loginSucceeds() async throws {
-        let user = try await service.login(email: "test@test.com", password: "pass")
-        #expect(user.email == "test@test.com")
+    @Test func acceptsKnownUser() async throws {
+        let user = try await session.signIn(email: "ada@example.com", password: "pw")
+        #expect(user.email == "ada@example.com")
     }
 
-    @Test func loginFailsWithBadPassword() async {
-        #expect(throws: AuthError.invalidCredentials) {
-            try await service.login(email: "test@test.com", password: "wrong")
+    @Test func rejectsWrongPassword() async {
+        await #expect(throws: AuthError.wrongPassword) {
+            try await session.signIn(email: "ada@example.com", password: "nope")
         }
     }
 }
 ```
 
-Suites can nest for logical grouping:
+`init()` takes the place of `setUp()` and runs before every test, because each
+test gets a new instance of the suite. Passing an error value, as in
+`#expect(throws: AuthError.wrongPassword)`, checks for that exact error.
+
+Suites nest for grouping:
 
 ```swift
-@Suite("Payments")
-struct PaymentTests {
-    @Suite("Subscriptions")
-    struct SubscriptionTests {
-        @Test func renewsAutomatically() { /* ... */ }
+@Suite("Currency")
+struct CurrencyTests {
+    @Suite("Parsing") struct Parsing {
+        @Test func parsesEuro() { #expect(Money(parsing: "EUR 5")?.amount == 5) }
     }
-    @Suite("One-Time")
-    struct OneTimeTests {
-        @Test func chargesCorrectAmount() { /* ... */ }
+    @Suite("Rounding") struct Rounding {
+        @Test func roundsHalfEven() { #expect(Money(2.345, "EUR").rounded.amount == 2.34) }
     }
 }
 ```
@@ -111,522 +75,442 @@ struct PaymentTests {
 ## Parameterized Tests
 
 ```swift
-@Test("Email validation", arguments: [
-    ("user@example.com", true),
-    ("user@", false),
-    ("@example.com", false),
+@Test("Postcode validation", arguments: [
+    ("10115", true),
+    ("ABCDE", false),
     ("", false),
 ])
-func validateEmail(email: String, isValid: Bool) {
-    #expect(EmailValidator.isValid(email) == isValid)
+func validatesPostcode(_ input: String, _ isValid: Bool) {
+    #expect(Postcode.isValid(input) == isValid)
 }
 
-// From CaseIterable
-@Test(arguments: Currency.allCases)
-func currencyHasSymbol(currency: Currency) {
-    #expect(currency.symbol.isEmpty == false)
+@Test(arguments: Weekday.allCases)
+func everyWeekdayHasAShortName(_ day: Weekday) {
+    #expect(!day.shortName.isEmpty)
 }
 
-// Two collections: cartesian product
-@Test(arguments: [1, 2, 3], ["a", "b"])
-func combinations(number: Int, letter: String) {
-    #expect(number > 0)
+@Test(arguments: [Plan.basic, .pro], [Region.eu, .us])
+func priceExistsForEveryPlanAndRegion(_ plan: Plan, _ region: Region) {
+    #expect(PriceTable.price(for: plan, in: region) != nil)
 }
 
-// Use zip for 1:1 pairing
-@Test(arguments: zip(["USD", "EUR"], ["$", "€"]))
-func currencySymbols(code: String, symbol: String) {
-    #expect(Currency(code: code).symbol == symbol)
+@Test(arguments: zip(["1", "22", "333"], [1, 2, 3]))
+func digitCount(_ text: String, _ count: Int) {
+    #expect(text.count == count)
 }
 ```
 
-Each argument combination runs as an independent test case reported separately.
+- Two argument collections test every combination (a cartesian product).
+- `zip` pairs them one to one instead.
+- Every combination is its own test case with its own result.
 
 ## Execution Model
 
-Swift Testing uses Swift Concurrency and runs tests in parallel by default. Treat every test as isolated work unless you explicitly serialize a scope.
+Swift Testing schedules tests as concurrent tasks, so many of them execute at
+once.
 
 ```swift
 @Suite(.serialized, .tags(.database))
-struct DatabaseTests {
-    @Test func insertsRecord() async throws { /* ... */ }
-    @Test func removesRecord() async throws { /* ... */ }
+struct MigrationTests {
+    @Test func upgradesV1() throws { }
+    @Test func upgradesV2() throws { }
 }
 ```
 
-Use `.serialized` when tests must not overlap because they touch shared external state like a keychain, database, singleton service, or filesystem location. It does not make unrelated tests outside the serialized scope run one-at-a-time.
-
-Important implications:
-- Each test gets its own suite instance.
-- Declaration order is not a contract.
-- If one logical workflow depends on previous state, keep that workflow inside one test.
-- Prefer isolated fixtures over shared mutable globals.
-
-## Confirmation and Known Issues
+Reach for `.serialized` when tests share something outside the process that
+cannot be isolated: the keychain, a database, a singleton service, a fixed
+location on disk. Even then every test receives a new suite value, the order
+of declarations promises nothing, and fixtures that isolate state remain the
+better default.
 
-### Confirmation (Async Event Testing)
+## Confirmations
 
 ```swift
-// Basic confirmation -- event must fire exactly once
-await confirmation("Received notification") { confirm in
-    let observer = NotificationCenter.default.addObserver(
-        forName: .userLoggedIn, object: nil, queue: .main
-    ) { _ in confirm() }
-    await authService.login()
-    NotificationCenter.default.removeObserver(observer)
-}
+@Test func postsSignedOutNotification() async {
+    let center = NotificationCenter()
+    let session = SessionController(notificationCenter: center)
 
-// Expected count -- event must fire exactly N times
-await confirmation("Received 3 items", expectedCount: 3) { confirm in
-    processor.onItem = { _ in confirm() }
-    await processor.process(items)
+    await confirmation("signed-out posted") { signedOut in
+        let token = center.addObserver(forName: .sessionEnded, object: nil, queue: nil) { _ in
+            signedOut()
+        }
+        await session.signOut()
+        center.removeObserver(token)
+    }
 }
-```
-
-### Known Issues
 
-```swift
-// Known failing test -- does not count as failure
-withKnownIssue("Propane tank is empty") {
-    #expect(truck.grill.isHeating)
+@Test func reportsEveryChunk() async {
+    let uploader = ChunkUploader(chunks: 3)
+    await confirmation("chunk sent", expectedCount: 3) { chunkSent in
+        uploader.onChunk = { _ in chunkSent() }
+        await uploader.run()
+    }
 }
+```
 
-// Intermittent / flaky
-withKnownIssue(isIntermittent: true) {
-    #expect(service.isReachable)
-}
+Without `expectedCount`, the confirmation must fire exactly once. With it, it
+must fire exactly that many times.
 
-// Conditional
-withKnownIssue {
-    #expect(foodTruck.grill.isHeating)
-} when: {
-    !hasPropane
-}
+## Known Issues Limited to Specific Failures
 
-// Match specific issues only
-try withKnownIssue {
-    let level = try #require(foodTruck.batteryLevel)
-    #expect(level >= 0.8)
-} matching: { issue in
-    guard case .expectationFailed(let expectation) = issue.kind else { return false }
-    return expectation.isRequired
+```swift
+@Test func vendorFeedParses() throws {
+    try withKnownIssue {
+        let feed = try #require(VendorFeed(data: Fixtures.brokenFeed))
+        #expect(feed.items.count == 12)
+    } matching: { issue in
+        if case .expectationFailed(let expectation) = issue.kind {
+            return expectation.isRequired
+        }
+        return false
+    }
 }
 ```
 
-If no known issues are recorded, Swift Testing records a distinct issue notifying you the problem may be resolved.
+The `matching:` closure decides which issues count as known. Here only a
+failed `#require` is excused; any other failure still fails the test. The call
+needs `try` because the body uses `#require`.
 
 ## Tags
 
-Tags must be declared as static members in an extension on `Tag`:
-
 ```swift
 extension Tag {
-    @Tag static var critical: Self
-    @Tag static var slow: Self
-    @Tag static var networking: Self
     @Tag static var validation: Self
+    @Tag static var banking: Self
+    @Tag static var slow: Self
 }
-
-@Test(.tags(.critical, .networking))
-func apiCallReturnsData() async throws { /* ... */ }
 ```
 
-Filter tests by tag in Xcode test plans or CLI (tag-based filtering syntax varies by toolchain  -  verify for your Swift version).
+Filter by tag in an Xcode test plan or from the command line. The command-line
+syntax has changed between toolchains, so check it for the Swift version in
+use.
 
-## TestScoping and Test Organization
+## Scoped Setup and Teardown with `TestScoping`
 
-`TestScoping` consolidates per-test setup/teardown into reusable fixtures when attached through a custom trait:
+`TestScoping` (Swift 6.1) wraps a test or suite in custom setup and teardown.
 
 ```swift
-struct DatabaseScope: TestTrait, SuiteTrait, TestScoping {
+struct TemporaryDatabaseTrait: TestTrait, SuiteTrait, TestScoping {
     func provideScope(
         for test: Test,
         testCase: Test.Case?,
-        performing body: @Sendable () async throws -> Void
+        performing function: @Sendable () async throws -> Void
     ) async throws {
-        let db = try await TestDatabase.create()
+        let database = try await TestDatabase.create()
         do {
-            try await body()
-            try await db.destroy()
+            try await function()
         } catch {
-            try? await db.destroy()
+            try? await database.destroy()
             throw error
         }
+        try await database.destroy()
     }
 }
 
-extension Trait where Self == DatabaseScope {
-    static var databaseScope: Self { .init() }
+extension Trait where Self == TemporaryDatabaseTrait {
+    static var temporaryDatabase: Self { Self() }
 }
 
-@Test(.databaseScope, .tags(.database))
-func insertsRecord() async throws {
-    // Test runs inside DatabaseScope.provideScope
-}
+@Test(.temporaryDatabase, .tags(.database))
+func insertsRows() async throws { }
 ```
 
-## XCTest Migration Patterns
+Create the resource, run the test body, then clean up. If the body throws,
+clean up with `try?` and rethrow the original error.
+
+## From XCTest, Step by Step
 
-Swift Testing tests are functions annotated with `@Test`; they do not need `XCTestCase`. Use the smallest shape that needs the fixture:
+Possible shapes after migration:
 
 ```swift
-@Test func validatesTotal() {
-    #expect(Cart(items: [.sample]).total == 9.99)
+@Test func trimsWhitespace() {
+    #expect(" a ".trimmed == "a")
 }
 
-@Suite("Checkout")
-struct CheckoutTests {
-    let calculator = PriceCalculator()
-
-    @Test func appliesDiscount() {
-        #expect(calculator.total(discount: .percent(10)) == 8.99)
-    }
+@Suite struct TaxTests {
+    let calculator = TaxCalculator(rate: 0.2)
+    @Test func addsTax() { #expect(calculator.gross(100) == 120) }
 }
 
-@Suite("Shared Cache")
-actor CacheTests {
-    var cache = TestCache()
-
-    @Test func storesValue() async {
-        await cache.store("value", forKey: "key")
-        #expect(await cache.value(forKey: "key") == "value")
-    }
+@Suite actor ThumbnailCacheTests {
+    var cache = ThumbnailCache()
+    @Test func storesImage() async { await cache.store(Data(), for: "a") }
 }
 
-struct PureHelperTests {
-    @Test static func normalizesInput() {
-        #expect(normalize("  email@example.com ") == "email@example.com")
-    }
+struct SlugTests {
+    @Test static func lowercases() { #expect(Slug("Hello").value == "hello") }
 }
 ```
 
-Common XCTest mappings:
-
 | XCTest | Swift Testing |
-|---|---|
-| `XCTAssertTrue(x)` / `XCTAssert(x)` | `#expect(x)` |
-| `XCTAssertFalse(x)` | `#expect(!x)` |
-| `XCTAssertEqual(a, b)` | `#expect(a == b)` |
-| `XCTAssertThrowsError(try f())` | `#expect(throws: (any Error).self) { try f() }` |
-| `XCTAssertNoThrow(try f())` | `#expect(throws: Never.self) { try f() }` |
-| `try XCTUnwrap(value)` | `try #require(value)` |
-| `XCTFail("message")` | `Issue.record("message")` |
-
-Convert `setUp` into isolated suite `init()` state. Avoid moving fixtures into singletons or shared globals; Swift Testing runs tests in parallel by default. Use actors or per-test fixtures for mutable test doubles, and use `.serialized` only when an external shared resource cannot be isolated.
-
-## Mocking and Test Doubles
-
-Define testable boundaries with protocols:
+|--------|---------------|
+| `XCTAssert(isOpen)` or `XCTAssertTrue(isOpen)` | `#expect(isOpen)` |
+| `XCTAssertFalse(isOpen)` | `#expect(!isOpen)` |
+| `XCTAssertEqual(total, 120)` | `#expect(total == 120)` |
+| `XCTAssertThrowsError(try parse(raw))` | `#expect(throws: (any Error).self) { try parse(raw) }` |
+| `XCTAssertNoThrow(try parse(raw))` | `#expect(throws: Never.self) { try parse(raw) }` |
+| `let user = try XCTUnwrap(maybeUser)` | `let user = try #require(maybeUser)` |
+| `XCTFail("unreachable")` | `Issue.record("unreachable")` |
+
+- Turn `setUp` into the suite's `init()`, one fresh fixture per test.
+- Never move fixtures into singletons or globals to share them.
+- Mutable test doubles belong in an actor or in a fixture created per test.
+- Keep `.serialized` for the case where an outside resource truly cannot be
+  given to each test separately.
+
+## Test Doubles
 
 ```swift
-protocol UserRepository: Sendable {
-    func fetch(id: String) async throws -> User
-    func save(_ user: User) async throws
+protocol ProfileStore: Sendable {
+    func profile(id: UUID) async throws -> Profile
+    func save(_ profile: Profile) async throws
 }
 
-actor MockUserRepository: UserRepository {
-    var users: [String: User] = [:]
-    var fetchError: (any Error)?
-    private(set) var savedUsers: [User] = []
+actor FakeProfileStore: ProfileStore {
+    var stored: Profile?
+    var failure: Error?
+    private(set) var saved: [Profile] = []
 
-    init(users: [String: User] = [:], fetchError: (any Error)? = nil) {
-        self.users = users
-        self.fetchError = fetchError
+    init(stored: Profile? = nil, failure: Error? = nil) {
+        self.stored = stored
+        self.failure = failure
     }
 
-    func fetch(id: String) async throws -> User {
-        if let error = fetchError { throw error }
-        guard let user = users[id] else { throw NotFoundError() }
-        return user
+    func profile(id: UUID) async throws -> Profile {
+        if let failure { throw failure }
+        guard let stored else { throw StoreError.notFound }
+        return stored
     }
 
-    func save(_ user: User) async throws {
-        savedUsers.append(user)
-        users[user.id] = user
+    func save(_ profile: Profile) async throws {
+        saved.append(profile)
     }
 }
 ```
 
-**Pattern:** Mocks conform to protocols, never subclass concrete types. For parallel Swift Testing runs, keep mutable mock state isolated in an actor or another Sendable-safe fixture. Store call counts and arguments for verification behind that isolation boundary.
+Doubles conform to a protocol; they never subclass a concrete type. Keep their
+mutable state, call counts and captured arguments behind an actor or other
+`Sendable` isolation.
 
-## Testable Architecture
-
-Inject dependencies through initializers for testability:
+## Designing for Tests
 
 ```swift
+@MainActor
 @Observable
-class ProfileViewModel {
-    var user: User?
-    var error: Error?
-    private let repository: any UserRepository
+final class ProfileScreenModel {
+    private let store: any ProfileStore
+    private(set) var profile: Profile?
+    private(set) var failure: Error?
 
-    init(repository: any UserRepository) {
-        self.repository = repository
-    }
+    init(store: any ProfileStore) { self.store = store }
 
-    func load() async {
-        do {
-            user = try await repository.fetch(id: "current")
-        } catch {
-            self.error = error
-        }
+    func load(id: UUID) async {
+        do { profile = try await store.profile(id: id) }
+        catch { failure = error }
     }
 }
 
-// Test with mock
-@Test @MainActor func viewModelLoadsUser() async {
-    let mock = MockUserRepository(users: ["current": .preview])
-    let vm = ProfileViewModel(repository: mock)
-    await vm.load()
-    #expect(vm.user?.name == "Alice")
+@Test @MainActor func loadShowsProfile() async {
+    let expected = Profile(id: UUID(), name: "Ada")
+    let model = ProfileScreenModel(store: FakeProfileStore(stored: expected))
+    await model.load(id: expected.id)
+    #expect(model.profile == expected)
 }
 
-@Test @MainActor func viewModelHandlesError() async {
-    let mock = MockUserRepository(fetchError: URLError(.notConnectedToInternet))
-    let vm = ProfileViewModel(repository: mock)
-    await vm.load()
-    #expect(vm.user == nil)
-    #expect(vm.error != nil)
+@Test @MainActor func loadFailureLeavesNoProfile() async {
+    let model = ProfileScreenModel(store: FakeProfileStore(failure: StoreError.offline))
+    await model.load(id: UUID())
+    #expect(model.profile == nil)
+    #expect(model.failure != nil)
 }
 ```
 
-## Async and Concurrent Tests
+Dependencies come in through the initialiser, so tests pass a double.
+
+## Async and Time
+
+Mark a test `@MainActor` when it drives a main-actor model, as above.
+
+For time-based behaviour, inject a `Clock` and drive it by hand in the test.
+The standard library has no manual test clock, so write a small one or use a
+clock library.
 
 ```swift
-@Test @MainActor func viewModelUpdatesOnMainActor() async {
-    let vm = ProfileViewModel(repository: MockUserRepository())
-    await vm.load()
-    #expect(vm.user != nil)
-}
+@Test func debouncerWaitsForQuietPeriod() async {
+    let clock = ManualClock()
+    let search = DebouncedSearch(delay: .seconds(1), clock: clock)
+    search.queryChanged("sw")
 
-// Clock injection for time-dependent logic
-@Test func debounceUsesCorrectDelay() async throws {
-    let clock = TestClock()
-    let debouncer = Debouncer(delay: .seconds(1), clock: clock)
-    debouncer.submit { /* action */ }
-    await clock.advance(by: .milliseconds(500))
-    #expect(!debouncer.hasExecuted)
-    await clock.advance(by: .milliseconds(500))
-    #expect(debouncer.hasExecuted)
+    await clock.advance(by: .milliseconds(600))
+    #expect(await search.requestCount == 0)
+
+    await clock.advance(by: .milliseconds(400))
+    #expect(await search.requestCount == 1)
 }
 
-// Error path testing
-@Test func fetchThrowsOnNetworkError() async {
-    let mock = MockUserRepository(fetchError: URLError(.notConnectedToInternet))
-    #expect(throws: URLError.self) {
-        try await mock.fetch(id: "1")
+@Test func offlineFetchThrows() async {
+    await #expect(throws: URLError.self) {
+        try await FeedClient(session: .offline).latest()
     }
 }
 ```
 
-## XCTest UI Tests  -  Page Object Pattern
+## UI Tests Stay on XCTest
 
-Swift Testing does not support UI testing. Use XCTest with XCUITest for all UI tests.
+Swift Testing has no UI testing support; use XCTest with XCUITest.
 
 ```swift
-class LoginUITests: XCTestCase {
-    let app = XCUIApplication()
+import XCTest
+
+@MainActor
+final class CheckoutUITests: XCTestCase {
+    var app: XCUIApplication!
 
-    override func setUpWithError() throws {
+    override func setUp() async throws {
         continueAfterFailure = false
+        app = XCUIApplication()
         app.launch()
     }
 
-    func testLoginFlow() throws {
-        let loginPage = LoginPage(app: app)
-        let homePage = loginPage.login(email: "test@test.com", password: "password")
-        XCTAssertTrue(homePage.welcomeLabel.exists)
+    func testGuestCanReachPayment() {
+        let payment = SignInPage(app: app).continueAsGuest().addFirstItem().checkout()
+        XCTAssertTrue(payment.payButton.waitForExistence(timeout: 5))
     }
 }
-```
-
-### Page Object Pattern
-
-Encapsulate UI element queries in page objects for reusable, readable UI tests:
 
-```swift
-struct LoginPage {
+@MainActor
+struct SignInPage {
     let app: XCUIApplication
-    var emailField: XCUIElement { app.textFields["Email"] }
-    var passwordField: XCUIElement { app.secureTextFields["Password"] }
-    var signInButton: XCUIElement { app.buttons["Sign In"] }
+    var emailField: XCUIElement { app.textFields["signIn.email"] }
+    var passwordField: XCUIElement { app.secureTextFields["signIn.password"] }
+    var guestButton: XCUIElement { app.buttons["signIn.guest"] }
 
     @discardableResult
-    func login(email: String, password: String) -> HomePage {
-        emailField.tap(); emailField.typeText(email)
-        passwordField.tap(); passwordField.typeText(password)
-        signInButton.tap()
-        return HomePage(app: app)
+    func continueAsGuest() -> CatalogPage {
+        guestButton.tap()
+        return CatalogPage(app: app)
     }
 }
-
-struct HomePage {
-    let app: XCUIApplication
-    var welcomeLabel: XCUIElement { app.staticTexts["Welcome"] }
-}
 ```
 
-## Performance Testing
+Page objects wrap element lookups by accessibility identifier and expose
+actions that return the next page. `XCUIApplication` and `XCUIElement` are
+main-actor types, so under Swift 6 the test class and every page object are
+`@MainActor`, and setup goes in the async `setUp()`: the synchronous
+`setUpWithError()` override stays nonisolated and cannot touch them.
+
+## Performance Tests Stay on XCTest
 
 ```swift
-class FeedPerformanceTests: XCTestCase {
-    func testFeedParsingPerformance() throws {
-        let data = try loadFixture("large-feed.json")
-        let metrics: [XCTMetric] = [XCTClockMetric(), XCTMemoryMetric()]
-        measure(metrics: metrics) {
-            _ = try? FeedParser.parse(data)
+final class ParserPerformanceTests: XCTestCase {
+    func testParseLargeFeed() {
+        measure(metrics: [XCTClockMetric(), XCTMemoryMetric()]) {
+            _ = FeedParser().parse(Fixtures.largeFeed)
         }
     }
 }
 ```
 
-Performance tests require XCTest  -  not available in Swift Testing.
+## Snapshot Tests
 
-## Snapshot Testing
-
-Add Point-Free's `SnapshotTesting` package to the test target via Swift Package Manager, then use it for visual regression. Requires XCTest:
+The open-source swift-snapshot-testing package, added through SwiftPM to the
+test target, is the common choice. It started as an XCTest tool; releases from
+1.17 on also work inside Swift Testing.
 
 ```swift
 import SnapshotTesting
+import SwiftUI
 import XCTest
 
-class ProfileViewSnapshotTests: XCTestCase {
-    func testProfileView() {
-        let view = ProfileView(user: .preview)
-        assertSnapshot(of: view, as: .image(layout: .device(config: .iPhone13)))
-
-        // Dark mode
-        assertSnapshot(of: view.environment(\.colorScheme, .dark),
-                       as: .image(layout: .device(config: .iPhone13)), named: "dark")
+final class ReceiptViewSnapshotTests: XCTestCase {
+    func testReceipt() {
+        let receipt = ReceiptView(receipt: .sample)
+        let phone = SwiftUISnapshotLayout.device(config: .iPhone13)
 
-        // Large Dynamic Type
-        assertSnapshot(of: view.environment(\.dynamicTypeSize, .accessibility3),
-                       as: .image(layout: .device(config: .iPhone13)), named: "largeText")
+        assertSnapshot(of: receipt, as: .image(layout: phone))
+        assertSnapshot(of: receipt.environment(\.colorScheme, .dark),
+                       as: .image(layout: phone), named: "night")
+        assertSnapshot(of: receipt.dynamicTypeSize(.accessibility3),
+                       as: .image(layout: phone), named: "largest-text")
     }
 }
 ```
 
-Always test Dark Mode and large Dynamic Type in snapshots.
-
-## Test Attachments
+Always include a Dark Mode snapshot and one at a large Dynamic Type size.
 
-Attach diagnostic data to test results for debugging failures:
+## Attachments from Files
 
 ```swift
-@Test func generateReport() async throws {
-    let report = try generateReport()
-    // Attach the output for later inspection
-    Attachment.record(report.data, named: "report.json")
-    #expect(report.isValid)
-}
-
-// Attach from a file URL
-@Test func processImage() async throws {
-    let output = try processImage()
-    let attachment = try await Attachment(contentsOf: output.url, named: "result.png")
-    Attachment.record(attachment)
+@Test func archivesLog() async throws {
+    let url = try LogExporter().export()
+    let logFile = try await Attachment(contentsOf: url, named: "session.log")
+    Attachment.record(logFile)
 }
 ```
 
-Attachments support standard `Attachable` values such as `Data`, `[UInt8]`, strings, and Encodable values when Foundation is imported. Image attachments require Swift 6.3 / Xcode 26.4 or newer and support platform image types such as `UIImage`, `CGImage`, `CIImage`, and `NSImage`; pass `as: .png` or another supported format when the filename should be explicit.
-
-## Exit Testing
+`Data`, `[UInt8]` and `String` can be attached directly. With Foundation
+imported, an `Encodable` type (or an `NSSecureCoding` one) gets a default
+implementation once it declares `Attachable` conformance.
 
-Test code that calls `exit()`, `fatalError()`, or `preconditionFailure()`. Exit testing requires Swift 6.2 / Xcode 26.0 or newer and is supported on macOS, Linux, FreeBSD, OpenBSD, and Windows runtime targets, not iOS, tvOS, or watchOS:
-
-```swift
-@Test func invalidInputCausesExit() async {
-    await #expect(processExitsWith: .failure) {
-        processInvalidInput()  // calls fatalError()
-    }
-}
-```
+## Exit Tests
 
-Exit testing runs the closure in a subprocess. The test passes if the process exits with the expected status. Capturing values from the parent process in an exit-test capture list requires the Swift 6.3 compiler.
+An exit test runs its closure in a child process and passes when that process
+ends with the expected status. See the skill for the toolchain and platform
+limits.
 
-## Test File Organization
+## Organising Files
 
 ```text
-Tests/AppTests/          # Swift Testing (Models/, ViewModels/, Services/)
-Tests/AppUITests/        # XCTest UI tests (Pages/, Flows/)
-Tests/Fixtures/          # Test data (JSON, images)
-Tests/Mocks/             # Shared mock implementations
+Tests/
+  AppTests/            Swift Testing
+    Models/
+    ViewModels/
+    Services/
+  AppUITests/          XCTest UI tests
+    Pages/
+    Flows/
+  Fixtures/
+  Mocks/
 ```
 
-Name test files `<TypeUnderTest>Tests.swift`. Describe behavior in function names: `fetchUserReturnsNilOnNetworkError()` not `testFetchUser()`. Name mocks `Mock<ProtocolName>`.
+- Files are named after the type under test: `InvoiceStoreTests.swift`.
+- Test functions describe behaviour.
+- Doubles are named after the protocol: `MockProfileStore` for
+  `ProfileStore` (or `Fake...` when it has working behaviour).
 
-### What to Test
+Always test business rules, validation, view-model state transitions, error
+paths, edge cases (empty input, nil, boundary values), both outcomes of async
+calls, and cancellation of `Task`s.
 
-**Always test:** business logic, validation rules, state transitions in view models, error handling paths, edge cases (empty collections, nil, boundaries), async success and failure, Task cancellation.
+Skip SwiftUI `body` layout (snapshots cover it), trivial forwarding code, the
+behaviour of Apple frameworks, and private methods (test them through the
+public API).
 
-**Skip:** SwiftUI view body layout (use snapshots), simple property forwarding, Apple framework behavior, private methods (test through public API).
+## Readable Arguments
 
-## CustomTestStringConvertible
-
-When parameterized test arguments appear in test output, Swift Testing uses `String(describing:)` by default. Conform to `CustomTestStringConvertible` for better output:
+Parameterized results print each argument with `String(describing:)`. For
+enums, identifiers and models, conform to `CustomTestStringConvertible`:
 
 ```swift
-enum Food: CaseIterable {
-    case paella, oden, ragu
-}
-
-extension Food: CustomTestStringConvertible {
-    var testDescription: String {
-        switch self {
-        case .paella: "paella valenciana"
-        case .oden: "おでん"
-        case .ragu: "ragù alla bolognese"
-        }
-    }
+extension Plan: CustomTestStringConvertible {
+    var testDescription: String { "plan:\(rawValue)" }
 }
-
-@Test(arguments: Food.allCases)
-func isDelicious(_ food: Food) { /* output shows custom descriptions */ }
 ```
 
-Use this for any type passed as a parameterized test argument where the default description is unclear  -  especially enums, IDs, or model types.
-
-## Availability-Conditional Tests
-
-Use `@available` on test functions to run tests only on specific OS versions:
+## Tests That Need a Newer OS
 
 ```swift
-@Test
-@available(iOS 18, macOS 15, *)
-func usesNewAPI() async throws {
-    let result = try await NewFramework.process()
-    #expect(result.isValid)
-}
+@Test @available(macOS 15, iOS 18, *)
+func usesNewMeshGradientAPI() { }
 ```
 
-Swift Testing skips `@available`-gated tests when running on older OS versions. This replaces XCTest's `#available` guard + early return pattern.
-
-Do not put `@available` on a suite type or a type that contains a suite; Swift Testing requires suite types to always be available. Put availability gates on individual `@Test` functions instead.
-
-## Common Mistakes and Review Checklist
-
-1. **Testing implementation, not behavior.** Test what the code does, not how.
-2. **No error path tests.** If a function can throw, test the throw path.
-3. **Flaky async tests.** Use `confirmation` with expected counts, not `sleep` calls.
-4. **Shared mutable state between tests.** Each test sets up its own state via `init()` in `@Suite` or a fixture.
-5. **Missing accessibility identifiers in UI tests.** XCUITest queries rely on them.
-6. **Using `sleep` in tests.** Use `confirmation`, clock injection, or `withKnownIssue`.
-7. **Not testing cancellation.** If code supports `Task` cancellation, verify it cancels cleanly.
-8. **Unclear XCTest migration boundaries.** Apple allows XCTest and Swift Testing in one file during migration; prefer separate files when it keeps imports, ownership, and runner expectations clearer.
-9. **Non-Sendable test helpers shared across tests.** Ensure test helper types are Sendable when shared across concurrent test cases.
-10. **Assuming test order.** Parallel default execution means declaration order and suite nesting do not create a workflow.
-11. **Using `.serialized` as a dependency chain.** Serialized scopes avoid overlap; they do not pass state from one test to the next.
-
-### Review Checklist
-
-- [ ] All new tests use Swift Testing (`@Test`, `#expect`), not XCTest assertions
-- [ ] Test names describe behavior (`fetchUserReturnsNilOnNetworkError` not `testFetchUser`)
-- [ ] Error paths have dedicated tests
-- [ ] Async tests use `confirmation()`, not `Task.sleep`
-- [ ] Parameterized tests used for repetitive variations
-- [ ] Tags applied for filtering (`.critical`, `.slow`)
-- [ ] Mocks conform to protocols, not subclass concrete types
-- [ ] No shared mutable state between tests
-- [ ] Tests do not rely on declaration order or shared suite instances
-- [ ] `.serialized` is reserved for exclusive state, not workflow sequencing
-- [ ] Cancellation tested for cancellable async operations
+Swift Testing skips the test on older systems, which replaces XCTest's
+`#available` check with an early return. Suites must always be available:
+never put `@available` on a suite or on the type that contains it.
+
+## More Mistakes to Avoid
+
+- Neither declaration order nor nesting of suites turns tests into a workflow;
+  they still run in parallel.
+- A serialized suite prevents overlap, but tests in it still do not hand state
+  to each other.