@mmerterden/multi-agent-pipeline 8.6.0

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

@@ -0,0 +1,504 @@
+# Swift Testing Patterns Reference
+
+## Contents
+- Basic Tests and Traits
+- Expectations and Requirements
+- Suite Organization
+- Parameterized Tests
+- Confirmation and Known Issues
+- Tags
+- TestScoping and Test Organization
+- 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
+- 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")
+}
+
+@Test(.tags(.validation, .email))
+func validatesEmailFormat() { /* ... */ }
+```
+
+## Expectations and Requirements
+
+```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
+
+```swift
+@Suite("User Authentication")
+struct AuthTests {
+    let service: AuthService
+    let mockRepo: MockUserRepository
+
+    // init() replaces setUp() -- runs before each test
+    init() {
+        mockRepo = MockUserRepository()
+        service = AuthService(repository: mockRepo)
+    }
+
+    @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 loginFailsWithBadPassword() async {
+        #expect(throws: AuthError.invalidCredentials) {
+            try await service.login(email: "test@test.com", password: "wrong")
+        }
+    }
+}
+```
+
+Suites can nest for logical grouping:
+
+```swift
+@Suite("Payments")
+struct PaymentTests {
+    @Suite("Subscriptions")
+    struct SubscriptionTests {
+        @Test func renewsAutomatically() { /* ... */ }
+    }
+    @Suite("One-Time")
+    struct OneTimeTests {
+        @Test func chargesCorrectAmount() { /* ... */ }
+    }
+}
+```
+
+## Parameterized Tests
+
+```swift
+@Test("Email validation", arguments: [
+    ("user@example.com", true),
+    ("user@", false),
+    ("@example.com", false),
+    ("", false),
+])
+func validateEmail(email: String, isValid: Bool) {
+    #expect(EmailValidator.isValid(email) == isValid)
+}
+
+// From CaseIterable
+@Test(arguments: Currency.allCases)
+func currencyHasSymbol(currency: Currency) {
+    #expect(currency.symbol.isEmpty == false)
+}
+
+// Two collections: cartesian product
+@Test(arguments: [1, 2, 3], ["a", "b"])
+func combinations(number: Int, letter: String) {
+    #expect(number > 0)
+}
+
+// Use zip for 1:1 pairing
+@Test(arguments: zip(["USD", "EUR"], ["$", "€"]))
+func currencySymbols(code: String, symbol: String) {
+    #expect(Currency(code: code).symbol == symbol)
+}
+```
+
+Each argument combination runs as an independent test case reported separately.
+
+## Confirmation and Known Issues
+
+### Confirmation (Async Event Testing)
+
+```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)
+}
+
+// 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)
+}
+```
+
+### Known Issues
+
+```swift
+// Known failing test -- does not count as failure
+withKnownIssue("Propane tank is empty") {
+    #expect(truck.grill.isHeating)
+}
+
+// Intermittent / flaky
+withKnownIssue(isIntermittent: true) {
+    #expect(service.isReachable)
+}
+
+// Conditional
+withKnownIssue {
+    #expect(foodTruck.grill.isHeating)
+} when: {
+    !hasPropane
+}
+
+// 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
+}
+```
+
+If no known issues are recorded, Swift Testing records a distinct issue notifying you the problem may be resolved.
+
+## 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
+}
+
+@Test(.tags(.critical, .networking))
+func apiCallReturnsData() async throws { /* ... */ }
+```
+
+Filter tests by tag in Xcode test plans or CLI (`swift test --filter tag:critical`).
+
+## TestScoping and Test Organization
+
+`TestScoping` consolidates per-test setup/teardown into reusable fixtures:
+
+```swift
+struct DatabaseFixture: TestScoping {
+    let db: TestDatabase
+
+    func provideScope(
+        for test: Test, testCase: Test.Case?,
+        performing body: @Sendable () async throws -> Void
+    ) async throws {
+        let db = try await TestDatabase.create()
+        try await body()
+        try await db.destroy()
+    }
+}
+
+// Use with @Test trait
+@Test(.tags(.database))
+func insertsRecord() async throws {
+    // DatabaseFixture.provideScope wraps this test
+}
+```
+
+## Mocking and Test Doubles
+
+Define testable boundaries with protocols:
+
+```swift
+protocol UserRepository: Sendable {
+    func fetch(id: String) async throws -> User
+    func save(_ user: User) async throws
+}
+
+struct MockUserRepository: UserRepository {
+    var users: [String: User] = [:]
+    var fetchError: Error?
+    var savedUsers: [User] = []
+
+    func fetch(id: String) async throws -> User {
+        if let error = fetchError { throw error }
+        guard let user = users[id] else { throw NotFoundError() }
+        return user
+    }
+
+    mutating func save(_ user: User) async throws {
+        savedUsers.append(user)
+        users[user.id] = user
+    }
+}
+```
+
+**Pattern:** Mocks conform to protocols, never subclass concrete types. Store call counts and arguments for verification.
+
+## Testable Architecture
+
+Inject dependencies through initializers for testability:
+
+```swift
+@Observable
+class ProfileViewModel {
+    var user: User?
+    var error: Error?
+    private let repository: UserRepository
+
+    init(repository: UserRepository) {
+        self.repository = repository
+    }
+
+    func load() async {
+        do {
+            user = try await repository.fetch(id: "current")
+        } catch {
+            self.error = 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 viewModelHandlesError() async {
+    var mock = MockUserRepository()
+    mock.fetchError = URLError(.notConnectedToInternet)
+    let vm = ProfileViewModel(repository: mock)
+    await vm.load()
+    #expect(vm.user == nil)
+    #expect(vm.error != nil)
+}
+```
+
+## Async and Concurrent Tests
+
+```swift
+@Test @MainActor func viewModelUpdatesOnMainActor() async {
+    let vm = ProfileViewModel(repository: MockUserRepository())
+    await vm.load()
+    #expect(vm.user != nil)
+}
+
+// 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)
+}
+
+// Error path testing
+@Test func fetchThrowsOnNetworkError() async {
+    var mock = MockUserRepository()
+    mock.fetchError = URLError(.notConnectedToInternet)
+    #expect(throws: URLError.self) {
+        try await mock.fetch(id: "1")
+    }
+}
+```
+
+## XCTest UI Tests — Page Object Pattern
+
+Swift Testing does not support UI testing. Use XCTest with XCUITest for all UI tests.
+
+```swift
+class LoginUITests: XCTestCase {
+    let app = XCUIApplication()
+
+    override func setUpWithError() throws {
+        continueAfterFailure = false
+        app.launch()
+    }
+
+    func testLoginFlow() throws {
+        let loginPage = LoginPage(app: app)
+        let homePage = loginPage.login(email: "test@test.com", password: "password")
+        XCTAssertTrue(homePage.welcomeLabel.exists)
+    }
+}
+```
+
+### Page Object Pattern
+
+Encapsulate UI element queries in page objects for reusable, readable UI tests:
+
+```swift
+struct LoginPage {
+    let app: XCUIApplication
+    var emailField: XCUIElement { app.textFields["Email"] }
+    var passwordField: XCUIElement { app.secureTextFields["Password"] }
+    var signInButton: XCUIElement { app.buttons["Sign In"] }
+
+    @discardableResult
+    func login(email: String, password: String) -> HomePage {
+        emailField.tap(); emailField.typeText(email)
+        passwordField.tap(); passwordField.typeText(password)
+        signInButton.tap()
+        return HomePage(app: app)
+    }
+}
+
+struct HomePage {
+    let app: XCUIApplication
+    var welcomeLabel: XCUIElement { app.staticTexts["Welcome"] }
+}
+```
+
+## Performance Testing
+
+```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)
+        }
+    }
+}
+```
+
+Performance tests require XCTest — not available in Swift Testing.
+
+## Snapshot Testing
+
+Use swift-snapshot-testing (pointfreeco) for visual regression. Requires XCTest:
+
+```swift
+import SnapshotTesting
+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")
+
+        // Large Dynamic Type
+        assertSnapshot(of: view.environment(\.dynamicTypeSize, .accessibility3),
+                       as: .image(layout: .device(config: .iPhone13)), named: "largeText")
+    }
+}
+```
+
+Always test Dark Mode and large Dynamic Type in snapshots.
+
+## Test Attachments
+
+Attach diagnostic data to test results for debugging failures:
+
+```swift
+@Test func generateReport() async throws {
+    let report = try generateReport()
+    // Attach the output for later inspection
+    Attachment(report.data, named: "report.json").record()
+    #expect(report.isValid)
+}
+
+// Attach from a file URL
+@Test func processImage() async throws {
+    let output = try processImage()
+    try await Attachment(contentsOf: output.url, named: "result.png")
+        .record()
+}
+```
+
+Attachments support any `Attachable` type and images via `AttachableAsImage`.
+
+## Exit Testing
+
+Test code that calls `exit()`, `fatalError()`, or `preconditionFailure()`:
+
+```swift
+@Test func invalidInputCausesExit() async {
+    await #expect(processExitsWith: .failure) {
+        processInvalidInput()  // calls fatalError()
+    }
+}
+```
+
+Exit testing runs the closure in a subprocess. The test passes if the process exits with the expected status.
+
+## Test File Organization
+
+```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
+```
+
+Name test files `<TypeUnderTest>Tests.swift`. Describe behavior in function names: `fetchUserReturnsNilOnNetworkError()` not `testFetchUser()`. Name mocks `Mock<ProtocolName>`.
+
+### What to Test
+
+**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 view body layout (use snapshots), simple property forwarding, Apple framework behavior, private methods (test through public API).
+
+## 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`.
+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. **Mixing XCTest and Swift Testing in one file.** Keep them in separate files.
+9. **Non-Sendable test helpers shared across tests.** Ensure test helper types are Sendable when shared across concurrent test cases.
+
+### 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
+- [ ] Cancellation tested for cancellable async operations

package/pipeline/skills/shared/external/swift-testing-pro/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: swift-testing-pro
+description: Writes, reviews, and improves Swift Testing code using modern APIs and best practices. Use when reading, writing, or reviewing projects that use Swift Testing.
+license: MIT
+metadata:
+  author: Paul Hudson
+  version: "1.0"
+---
+
+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.
+
+Review process:
+
+1. Ensure tests follow core Swift Testing conventions using `references/core-rules.md`.
+1. Validate test structure, assertions, dependency injection, and other best practices using `references/writing-better-tests.md`.
+1. Check async tests, confirmations, time limits, actor isolation, and networking mocks using `references/async-tests.md`.
+1. Ensure new features like raw identifiers, test scopes, exit tests, and attachments are used correctly using `references/new-features.md`.
+1. If migrating from XCTest, follow the conversion guidance in `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.
+- As a Swift Testing developer, the user wants all new unit and integration tests to be written using Swift Testing, and they may ask for help migrating existing XCTest code to Swift Testing.
+- Swift Testing does *not* support UI tests – XCTest must be used there.
+- Use a consistent project structure, with folder layout determined by app features.
+
+Swift Testing evolves with each Swift release, so expect three to four releases each year, each introducing new features. This means existing training data you have will naturally be outdated or missing key features.
+
+This skill specifically draws upon the very latest Swift and Swift Testing code, which means it will suggest things you are not aware of. Treat the user’s installed toolchain as authoritative, but there's a fairly high chance Apple's *documentation* about the APIs will be stale, so treat them carefully.
+
+
+## Output Format
+
+If the user asks for a review, organize findings by file. For each issue:
+
+1. State the file and relevant line(s).
+2. Name the rule being violated.
+3. Show a brief before/after code fix.
+
+Skip files with no issues. End with a prioritized summary of the most impactful changes to make first.
+
+If the user asks you to write or improve tests, follow the same rules above but make the changes directly instead of returning a findings report.
+
+Example output:
+
+### UserTests.swift
+
+**Line 5: Use struct, not class, for test suites.**
+
+```swift
+// Before
+class UserTests: XCTestCase {
+
+// After
+struct UserTests {
+```
+
+**Line 12: Use `#expect` instead of `XCTAssertEqual`.**
+
+```swift
+// Before
+XCTAssertEqual(user.name, "Taylor")
+
+// After
+#expect(user.name == "Taylor")
+```
+
+**Line 30: Use `#require` for preconditions, not `#expect`.**
+
+```swift
+// Before
+#expect(users.isEmpty == false)
+let first = users.first!
+
+// After
+let first = try #require(users.first)
+```
+
+### Summary
+
+1. **Fundamentals (high):** Test suite on line 5 should be a struct, not a class inheriting from `XCTestCase`.
+2. **Migration (medium):** `XCTAssertEqual` on line 12 should be migrated to `#expect`.
+3. **Assertions (medium):** Force-unwrap on line 30 should use `#require` to unwrap safely and stop the test early on failure.
+
+End of example.
+
+
+## References
+
+- `references/core-rules.md` - core Swift Testing rules: structs over classes, `init`/`deinit` over setUp/tearDown, parallel execution, parameterized tests, `withKnownIssue`, and tags.
+- `references/writing-better-tests.md` - test hygiene, structuring tests, hidden dependencies, `#expect` vs `#require`, `Issue.record()`, `#expect(throws:)`, and verification methods.
+- `references/async-tests.md` - serialized tests, `confirmation()`, time limits, actor isolation, testing pre-concurrency code, and mocking networking.
+- `references/new-features.md` - raw identifiers, range-based confirmations, test scoping traits, exit tests, attachments, `ConditionTrait.evaluate()`, and the updated `#expect(throws:)` return value.
+- `references/migrating-from-xctest.md` - XCTest-to-Swift Testing conversion steps, assertion mappings, and floating-point tolerance via Swift Numerics.