@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/external/swift-testing-pro/references/writing-better-tests.md

@@ -0,0 +1,254 @@
+# Writing better tests
+
+This contains suggestions to help you write better tests. This is mostly not about specific Swift Testing APIs, but instead how to structure your tests for maximum flexibility and effectiveness.
+
+
+## Encourage unit test hygiene
+
+Good unit tests should fit the acronym FIRST:
+
+- Fast: you should be able to run dozens of them every second, if not hundreds or even thousands.
+- Isolated: they should not depend on another test having run, or any sort of external state.
+- Repeatable: they should always give the same result when they are run, regardless of how many times or when they are run.
+- Self-verifying: the test must unambiguously say whether it passed or failed, with no room for interpretation.
+- Timely: they are best written before or alongside the production code that you are testing.
+
+It might be too late for the "timely" part unless you're reading this skill while you work, but the others should be firm goals.
+
+
+## Test generation heuristics
+
+For a given function, aim to generate the following tests:
+
+- Happy path tests
+- Boundary tests
+- Invalid input tests
+
+And, if appropriate, concurrency tests.
+
+
+## Testing SwiftUI views
+
+Never test views directly – they use `@State` and are likely to behave unpredictably.
+
+Instead, test view models or similar. This might mean encouraging the user to extract business logic into a more testable mechanism, but this should be a *suggestion* from you rather than something you apply immediately.
+
+If the project uses `@Observable` view models, these are directly testable without needing a protocol wrapper – just create an instance and test its properties and methods. For more help with SwiftUI, suggest the [SwiftUI Pro agent skill](https://github.com/twostraws/swiftui-agent-skill).
+
+
+## Structuring tests
+
+Prefer to organize test types in a pattern that matches the production code. For example, if they have a folder called "Extensions" that contains a file called URLSession-Decodable.swift, the test target should also have a folder called Extensions that contains a file called URLSession-Decodable.swift, and it should test the contents of the original production file.
+
+**If you are writing new tests, follow this rule. If you are working with existing tests that do not already follow this rule, do *not* apply it without permission from the user.**
+
+- Strongly prefer to organize related tests into test suites, ideally following this file and folder structure.
+- If there are test fixtures, put them in a dedicated file. If there are only a handful, a simple Fixtures folder is fine. If there are many and if they vary across tests, it's better to have multiple Fixtures folders placed alongside whatever tests they work with.
+- Use tags to mark up different kinds of work. At the very least this should be a `.networking` tag for network-related tests, even if they are mocked. You might also consider `.slow` for any tests that are unexpectedly slow, `.edgeCase` for tests that must be treated with extra care, `.smoke` for smoke tests, and more.
+- Add user-facing messages to `#expect` and `#require` when they provide value. This is not *always* the case, but it usually is.
+- Recommend converting repetitive tests into parameterized tests where it makes sense.
+- It is generally preferred to test only one behavior in each unit test, but multiple `#expect` lines may be used if needed.
+
+
+## Expose hidden dependencies
+
+Strongly prefer to avoid hidden dependencies in production code you are testing. In Swift apps this is commonly things like `UserDefaults` or `URLSession`.
+
+For example, production code like this is bad because it has a hidden dependency on `URLSession`:
+
+```swift
+struct News {
+    var url: URL
+    var stories = ""
+
+    mutating func fetch() async throws {
+        let (data, _) = try await URLSession.shared.data(from: url)
+        stories = String(decoding: data, as: UTF8.self)
+    }
+}
+```
+
+To remove the hidden dependency, a first step would be to inject the `URLSession` like this:
+
+```swift
+func fetch(using session: URLSession = .shared) async throws {
+    let (data, _) = try await session.data(from: url)
+    stories = String(decoding: data, as: UTF8.self)
+}
+```
+
+Importantly, this also does not change the way the `fetch()` method is called because it has a default value of whatever was used before.
+
+Even better would be to wrap `URLSession` in a protocol, requiring whatever methods are used in the production code, like this:
+
+```swift
+protocol URLSessionProtocol {
+    func data(from url: URL) async throws -> (Data, URLResponse)
+}
+
+extension URLSession: URLSessionProtocol { }
+```
+
+And now the production code can be written like this:
+
+```swift
+func fetch(using session: any URLSessionProtocol = URLSession.shared) async throws {
+    let (data, _) = try await session.data(from: url)
+    stories = String(decoding: data, as: UTF8.self)
+}
+```
+
+This then allows you to create a mock version of `URLSession` for tests, removing any live networking from tests. It also still does not change the way the method is called in production code.
+
+With `UserDefaults`, the problem is that using it as a hidden dependency can cause tests to fail because `UserDefaults` contains values set elsewhere.
+
+So, switch over to dependency injection with a sensible default value of whatever the project was using previously, then in the test pass in a custom `UserDefaults` instance like this:
+
+```swift
+let suite = "suite-\(UUID().uuidString)"
+let userDefaults = UserDefaults(suiteName: suite)
+defer { userDefaults?.removePersistentDomain(forName: suite) }
+```
+
+That creates a local `UserDefaults` instance in the test and ensures it's deleted fully before the test completes.
+
+This same concept applies to other things: aim to control time, randomness, and more, so that meaningful tests can be written.
+
+
+## Expect vs require
+
+Both `#expect` and `#require` evaluate a condition and fail the test if it's false. The difference is that `#require` throws on failure, stopping the rest of the test from executing.
+
+**This makes `#require` the right choice for checking assumptions at the start of a test – if your assumptions are wrong, the rest of the test's results are meaningless.**
+
+Using `#require` requires adding `throws` to your test method. For example, if your test depends on some setup being correct before the real assertion:
+
+```swift
+@Test func outstandingTasksStringIsPlural() throws {
+    let sut = try createTestUser(projects: 3, itemsPerProject: 10)
+    try #require(sut.projects.isEmpty == false)
+    let rowTitle = sut.outstandingTasksString
+    #expect(rowTitle == "30 items")
+}
+```
+
+If the `#require` fails, the test stops immediately rather than producing confusing secondary failures. Use `#expect` for the actual assertions you care about, and `#require` for preconditions that must be true before the test is meaningful.
+
+`#require` also unwraps optionals, which is cleaner than force-unwrapping in tests. Use it like this:
+
+```swift
+let value = try #require(someOptional)
+```
+
+
+## Tracking bug fixes
+
+If you are writing tests related to a specific bug, it is a good idea to use the `.bug` trait to store the bug ID or URL, if there is one. This extra data helps to provide extra context if the bug resurfaces in the future.
+
+For example, if bug #182 is a report that text headings are not italicized correctly, you would use `@Test` like this:
+
+```swift
+@Test("Headings should always be italic", .bug(id: 182))
+```
+
+Or if there is a specific URL:
+
+```swift
+@Test("Headings should always be italic", .bug("https://github.com/you/repo/issues/182"))
+```
+
+
+## Use Issue.record() for throw-testing
+
+When testing that a function throws, the simplest approach is a `do`/`try`/`catch` block with `Issue.record()` as the failure primitive. If no error is thrown, execution continues past `try` and hits `Issue.record()`, failing the test.
+
+```swift
+@Test func playingMinecraftThrows() {
+    let game = Game(name: "Minecraft")
+
+    do {
+        try game.play()
+        Issue.record("Expected an error to be thrown.")
+    } catch GameError.notPurchased {
+        // success
+    } catch {
+        Issue.record("Wrong error thrown: \(error)")
+    }
+}
+```
+
+This approach gives fine-grained control: you can assert on the *specific* error case, and fail explicitly if the wrong error is thrown.
+
+An alternative is using `#expect(throws:)`. Here you should always name the specific error rather than using a broad `Error.self`:
+
+```swift
+// Bad – passes for any error
+#expect(throws: Error.self) {
+    try game.play()
+}
+
+// Good – asserts the exact error case
+#expect(throws: GameError.notInstalled) {
+    try game.play()
+}
+```
+
+To assert that a function does *not* throw, use `Never.self`:
+
+```swift
+#expect(throws: Never.self) {
+    try game.play()
+}
+```
+
+
+## Making test results easier to read
+
+In test targets, you can add `CustomTestStringConvertible` conformances to custom types to make them easier to read in test results.
+
+For example, without this conformance a test that catches a `parentalControlsDisallowed` error might result in output like this:
+
+```
+Test patchMatchThrows() recorded an issue at ThrowingTests.swift:61:6: Caught error: parentalControlsDisallowed
+```
+
+If we add a retroactive conformance to `CustomTestStringConvertible` in the test target, the text can be clarified:
+
+```swift
+extension GameError: @retroactive CustomTestStringConvertible {
+    public var testDescription: String {
+        switch self {
+        case .notPurchased:
+            "This game has not been purchased."
+        case .notInstalled:
+            "This game is not currently installed."
+        case .parentalControlsDisallowed:
+            "This game has been blocked by parental controls."
+        }
+    }
+}
+```
+
+Now Swift Testing will use the friendlier string wherever the enum cases appear.
+
+**Important:** This conformance should not be added in production code.
+
+
+## Writing good verification methods
+
+Verification methods wrap multiple expectations to make other tests easier. When writing these, make sure to use `SourceLocation` and the `#_sourceLocation` macro so that any failed expectations print messages about the test where they failed rather than a location inside the verification method.
+
+**Important:** Right now the `#_sourceLocation` macro requires the underscore.
+
+For example:
+
+```swift
+func verifyDivision(_ result: (quotient: Int, remainder: Int), expectedQuotient: Int, expectedRemainder: Int, sourceLocation: SourceLocation = #_sourceLocation) {
+    #expect(result.quotient == expectedQuotient, sourceLocation: sourceLocation)
+    #expect(result.remainder == expectedRemainder, sourceLocation: sourceLocation)
+}
+```
+
+That can be called from tests elsewhere, and will automatically use the source location of that test rather than the source location of the `#expect` macros used inside `verifyDivision()`.
+
+`#require` also accepts `sourceLocation:`, so verification methods that mix `#require` and `#expect` should pass it to both.

package/pipeline/skills/shared/external/swiftdata/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: swiftdata
+description: "Implement, review, or improve data persistence using SwiftData. Use when defining @Model classes with @Attribute, @Relationship, @Transient, @Unique, or @Index; when querying with @Query, #Predicate, FetchDescriptor, or SortDescriptor; when configuring ModelContainer and ModelContext for SwiftUI or background work with @ModelActor; when planning schema migrations with VersionedSchema and SchemaMigrationPlan; when setting up CloudKit sync with ModelConfiguration; or when coexisting with or migrating from Core Data."
+---
+
+# SwiftData
+
+Persist, query, and manage structured data in iOS 26+ apps using SwiftData
+with Swift 6.2.
+
+## Contents
+
+- [Model Definition](#model-definition)
+- [ModelContainer Setup](#modelcontainer-setup)
+- [CRUD Operations](#crud-operations)
+- [@Query in SwiftUI](#query-in-swiftui)
+- [#Predicate](#predicate)
+- [FetchDescriptor](#fetchdescriptor)
+- [Schema Versioning and Migration](#schema-versioning-and-migration)
+- [Concurrency (@ModelActor)](#concurrency-modelactor)
+- [SwiftUI Integration](#swiftui-integration)
+- [Common Mistakes](#common-mistakes)
+- [Review Checklist](#review-checklist)
+- [References](#references)
+
+## Model Definition
+
+Apply `@Model` to a **class** (not struct). Generates `PersistentModel`, `Observable`, `Sendable`.
+
+```swift
+@Model
+class Trip {
+    var name: String
+    var destination: String
+    var startDate: Date
+    var endDate: Date
+    var isFavorite: Bool = false
+    @Attribute(.externalStorage) var imageData: Data?
+    @Relationship(deleteRule: .cascade, inverse: \LivingAccommodation.trip)
+    var accommodation: LivingAccommodation?
+    @Transient var isSelected: Bool = false  // Always provide default
+
+    init(name: String, destination: String, startDate: Date, endDate: Date) {
+        self.name = name; self.destination = destination
+        self.startDate = startDate; self.endDate = endDate
+    }
+}
+```
+
+**@Attribute options**: `.externalStorage`, `.unique`, `.spotlight`, `.allowsCloudEncryption`, `.preserveValueOnDeletion` (iOS 18+), `.ephemeral`, `.transformable(by:)`. Rename: `@Attribute(originalName: "old_name")`.
+
+**@Relationship**: `deleteRule:` `.cascade`/`.nullify`(default)/`.deny`/`.noAction`. Specify `inverse:` for reliable behavior. Unidirectional (iOS 18+): `inverse: nil`.
+
+**#Unique (iOS 18+)**: `#Unique<Person>([\.firstName, \.lastName])` -- compound uniqueness.
+
+**Inheritance (iOS 26+)**: `@Model class BusinessTrip: Trip { var company: String }`.
+
+Supported types: `Bool`, `Int`/`UInt` variants, `Float`, `Double`, `String`, `Date`, `Data`, `URL`, `UUID`, `Decimal`, `Array`, `Dictionary`, `Set`, `Codable` enums, `Codable` structs (composite, iOS 18+), relationships to `@Model` classes.
+
+## ModelContainer Setup
+
+```swift
+// Basic
+let container = try ModelContainer(for: Trip.self, LivingAccommodation.self)
+
+// Configured
+let config = ModelConfiguration("Store", isStoredInMemoryOnly: false,
+    groupContainer: .identifier("group.com.example.app"),
+    cloudKitDatabase: .private("iCloud.com.example.app"))
+let container = try ModelContainer(for: Trip.self, configurations: config)
+
+// With migration plan
+let container = try ModelContainer(for: SchemaV2.Trip.self,
+    migrationPlan: TripMigrationPlan.self)
+
+// In-memory (previews/tests)
+let container = try ModelContainer(for: Trip.self,
+    configurations: ModelConfiguration(isStoredInMemoryOnly: true))
+```
+
+## CRUD Operations
+
+```swift
+// CREATE
+let trip = Trip(name: "Summer", destination: "Paris", startDate: .now, endDate: .now + 86400*7)
+modelContext.insert(trip)
+try modelContext.save()  // or rely on autosave
+
+// READ
+let trips = try modelContext.fetch(FetchDescriptor<Trip>(
+    predicate: #Predicate { $0.destination == "Paris" },
+    sortBy: [SortDescriptor(\.startDate)]))
+
+// UPDATE -- modify properties directly; autosave handles persistence
+trip.destination = "Rome"
+
+// DELETE
+modelContext.delete(trip)
+try modelContext.delete(model: Trip.self, where: #Predicate { $0.isFavorite == false })
+
+// TRANSACTION (atomic)
+try modelContext.transaction {
+    modelContext.insert(trip); trip.isFavorite = true
+}
+```
+
+## @Query in SwiftUI
+
+```swift
+struct TripListView: View {
+    @Query(filter: #Predicate<Trip> { $0.isFavorite == true },
+           sort: \.startDate, order: .reverse)
+    private var favorites: [Trip]
+
+    var body: some View { List(favorites) { trip in Text(trip.name) } }
+}
+
+// Dynamic query via init
+struct SearchView: View {
+    @Query private var trips: [Trip]
+    init(search: String) {
+        _trips = Query(filter: #Predicate<Trip> { trip in
+            search.isEmpty || trip.name.localizedStandardContains(search)
+        }, sort: [SortDescriptor(\.name)])
+    }
+    var body: some View { List(trips) { trip in Text(trip.name) } }
+}
+
+// FetchDescriptor query
+struct RecentView: View {
+    static var desc: FetchDescriptor<Trip> {
+        var d = FetchDescriptor<Trip>(sortBy: [SortDescriptor(\.startDate)])
+        d.fetchLimit = 5; return d
+    }
+    @Query(RecentView.desc) private var recent: [Trip]
+    var body: some View { List(recent) { trip in Text(trip.name) } }
+}
+```
+
+## #Predicate
+
+```swift
+#Predicate<Trip> { $0.destination.localizedStandardContains("paris") }  // String
+#Predicate<Trip> { $0.startDate > Date.now }                            // Date
+#Predicate<Trip> { $0.isFavorite && $0.destination != "Unknown" }       // Compound
+#Predicate<Trip> { $0.accommodation?.name != nil }                      // Optional
+#Predicate<Trip> { $0.tags.contains { $0.name == "adventure" } }        // Collection
+```
+
+Supported: `==`, `!=`, `<`, `<=`, `>`, `>=`, `&&`, `||`, `!`, `contains()`, `allSatisfy()`, `filter()`, `starts(with:)`, `localizedStandardContains()`, `caseInsensitiveCompare()`, arithmetic, ternary, optional chaining, nil coalescing, type casting. **Not supported**: flow control, nested declarations, arbitrary method calls.
+
+## FetchDescriptor
+
+```swift
+var d = FetchDescriptor<Trip>(predicate: ..., sortBy: [...])
+d.fetchLimit = 20; d.fetchOffset = 0
+d.includePendingChanges = true
+d.propertiesToFetch = [\.name, \.startDate]
+d.relationshipKeyPathsForPrefetching = [\.accommodation]
+let trips = try modelContext.fetch(d)
+let count = try modelContext.fetchCount(d)
+let ids = try modelContext.fetchIdentifiers(d)
+try modelContext.enumerate(d, batchSize: 1000) { trip in trip.isProcessed = true }
+```
+
+## Schema Versioning and Migration
+
+```swift
+enum SchemaV1: VersionedSchema {
+    static var versionIdentifier = Schema.Version(1, 0, 0)
+    static var models: [any PersistentModel.Type] { [Trip.self] }
+    @Model class Trip { var name: String; init(name: String) { self.name = name } }
+}
+
+enum SchemaV2: VersionedSchema {
+    static var versionIdentifier = Schema.Version(2, 0, 0)
+    static var models: [any PersistentModel.Type] { [Trip.self] }
+    @Model class Trip {
+        var name: String; var startDate: Date?  // New property
+        init(name: String) { self.name = name }
+    }
+}
+
+enum TripMigrationPlan: SchemaMigrationPlan {
+    static var schemas: [any VersionedSchema.Type] { [SchemaV1.self, SchemaV2.self] }
+    static var stages: [MigrationStage] { [migrateV1toV2] }
+    static let migrateV1toV2 = MigrationStage.lightweight(
+        fromVersion: SchemaV1.self, toVersion: SchemaV2.self)
+}
+
+// Custom migration for data transformation
+static let migrateV2toV3 = MigrationStage.custom(
+    fromVersion: SchemaV2.self, toVersion: SchemaV3.self,
+    willMigrate: nil,
+    didMigrate: { context in
+        let trips = try context.fetch(FetchDescriptor<SchemaV3.Trip>())
+        for trip in trips { trip.displayName = trip.name.capitalized }
+        try context.save()
+    })
+```
+
+Lightweight handles: adding optional/defaulted properties, renaming (`originalName`), removing properties, adding model types.
+
+## Concurrency (@ModelActor)
+
+```swift
+@ModelActor
+actor DataHandler {
+    func importTrips(_ records: [TripRecord]) throws {
+        for r in records {
+            modelContext.insert(Trip(name: r.name, destination: r.dest,
+                                    startDate: r.start, endDate: r.end))
+        }
+        try modelContext.save()  // Always save explicitly in @ModelActor
+    }
+
+    func process(tripID: PersistentIdentifier) throws {
+        guard let trip = self[tripID, as: Trip.self] else { return }
+        trip.isProcessed = true; try modelContext.save()
+    }
+}
+
+let handler = DataHandler(modelContainer: container)
+try await handler.importTrips(records)
+```
+
+**Rules**: `ModelContainer` is `Sendable`. `ModelContext` is NOT -- use on its creating actor. Pass `PersistentIdentifier` (Sendable) across boundaries. Never pass `@Model` objects across actors.
+
+## SwiftUI Integration
+
+```swift
+@main
+struct MyApp: App {
+    var body: some Scene {
+        WindowGroup { ContentView() }
+            .modelContainer(for: [Trip.self, LivingAccommodation.self])
+    }
+}
+
+struct DetailView: View {
+    @Environment(\.modelContext) private var modelContext
+    let trip: Trip
+    var body: some View {
+        Text(trip.name)
+        Button("Delete") { modelContext.delete(trip) }
+    }
+}
+
+#Preview {
+    let config = ModelConfiguration(isStoredInMemoryOnly: true)
+    let container = try! ModelContainer(for: Trip.self, configurations: config)
+    container.mainContext.insert(Trip(name: "Preview", destination: "London",
+        startDate: .now, endDate: .now + 86400))
+    return TripListView().modelContainer(container)
+}
+```
+
+## Common Mistakes
+
+**1. @Model on struct** -- Use class. `@Model` requires reference semantics.
+
+**2. @Transient without default** -- Always provide default: `@Transient var x: Bool = false`.
+
+**3. Missing .modelContainer** -- @Query returns empty without a container on the view hierarchy.
+
+**4. Passing model objects across actors:**
+```swift
+// WRONG: await handler.process(trip: trip)
+// CORRECT: await handler.process(tripID: trip.persistentModelID)
+```
+
+**5. ModelContext on wrong actor:**
+```swift
+// WRONG: Task.detached { context.fetch(...) }
+// CORRECT: Use @ModelActor for background work
+```
+
+**6. Unsupported #Predicate expressions:**
+```swift
+// WRONG: #Predicate<Trip> { $0.name.uppercased() == "PARIS" }
+// CORRECT: #Predicate<Trip> { $0.name.localizedStandardContains("paris") }
+```
+
+**7. Flow control in #Predicate:**
+```swift
+// WRONG: #Predicate<Trip> { for tag in $0.tags { ... } }
+// CORRECT: #Predicate<Trip> { $0.tags.contains { $0.name == "x" } }
+```
+
+**8. No save in @ModelActor** -- Always call `try modelContext.save()` explicitly.
+
+**9. ObservableObject with @Model** -- Never use `ObservableObject`/`@Published`. `@Model` generates `Observable`. Use `@Query` in views.
+
+**10. Non-optional relationship without default:**
+```swift
+// WRONG: var accommodation: LivingAccommodation  // crashes on reconstitution
+// CORRECT: var accommodation: LivingAccommodation?
+```
+
+**11. Cascade without inverse** -- Specify `inverse:` for reliable cascade delete behavior.
+
+**12. DispatchQueue for background data work:**
+```swift
+// WRONG: DispatchQueue.global().async { ModelContext(container).fetch(...) }
+// CORRECT: @ModelActor actor Handler { func fetch() throws { ... } }
+```
+
+## Review Checklist
+
+- [ ] Every `@Model` is a class with a designated initializer
+- [ ] All `@Transient` properties have default values
+- [ ] Relationships specify `deleteRule` and `inverse`
+- [ ] `.modelContainer` attached at scene/root view level
+- [ ] `@Query` used for reactive data display in SwiftUI
+- [ ] `#Predicate` uses only supported operators
+- [ ] Background work uses `@ModelActor`
+- [ ] `PersistentIdentifier` used across actor boundaries
+- [ ] Schema changes have `VersionedSchema` + `SchemaMigrationPlan`
+- [ ] Large data uses `@Attribute(.externalStorage)`
+- [ ] CloudKit models use optionals and avoid unique constraints
+- [ ] Explicit `save()` in `@ModelActor` methods
+- [ ] Previews use `ModelConfiguration(isStoredInMemoryOnly: true)`
+- [ ] `@Model` classes accessed from SwiftUI views are on `@MainActor` via `@ModelActor` or MainActor isolation
+
+## References
+
+- See `references/swiftdata-advanced.md` for custom data stores, history
+  tracking, CloudKit, Core Data coexistence, composite attributes,
+  model inheritance, undo/redo, and performance patterns.
+- See `references/swiftdata-queries.md` for @Query variants, FetchDescriptor
+  deep dive, sectioned queries, dynamic queries, and background fetch patterns.
+- See `references/core-data-coexistence.md` for standalone Core Data patterns
+  and Core Data to SwiftData migration strategies.
+