swift-code-reviewer-skill 1.2.0 → 1.3.0

package/skills/swift-testing/references/dump-snapshot-testing.md

@@ -0,0 +1,265 @@
+# Dump Snapshot Testing
+
+Dump snapshot testing captures text-based representations of data structures, perfect for testing models, state objects, and non-visual components.
+
+## Setup
+
+Use [SnapshotTesting](https://github.com/pointfreeco/swift-snapshot-testing):
+
+```swift
+// Package.swift
+.package(url: "https://github.com/pointfreeco/swift-snapshot-testing", from: "1.15.0")
+```
+
+## Basic Usage
+
+```swift
+import SnapshotTesting
+import Testing
+@testable import Domain
+
+@Suite("PersonalRecord Snapshots")
+struct PersonalRecordSnapshotTests {
+
+    @Test("captures record structure correctly")
+    func recordStructure() {
+        let record = PersonalRecord.fixture(
+            liftType: .snatch,
+            weight: 120.0,
+            date: Date(timeIntervalSince1970: 1704067200) // Fixed date
+        )
+
+        assertSnapshot(of: record, as: .dump)
+    }
+}
+```
+
+## When to Use Dump Snapshots
+
+| Use Case | Why Dump Snapshots |
+|----------|-------------------|
+| **Data models** | Verify all properties without writing assertions for each |
+| **API responses** | Catch unexpected changes in decoded structures |
+| **State objects** | Track complex state transitions |
+| **Transformations** | Verify mapping/conversion logic output |
+| **Configuration** | Ensure settings objects are correctly constructed |
+
+## Parameterized Dump Snapshots
+
+Test multiple configurations:
+
+```swift
+@Test("captures different lift types", arguments: LiftType.allCases)
+func liftTypeSnapshots(liftType: LiftType) {
+    let record = PersonalRecord.fixture(
+        liftType: liftType,
+        weight: 100.0
+    )
+
+    assertSnapshot(of: record, as: .dump, named: "\(liftType)")
+}
+```
+
+## Complex Object Snapshots
+
+```swift
+@Test("captures workout session state")
+func workoutSessionState() {
+    let session = WorkoutSession(
+        id: UUID(uuidString: "550e8400-e29b-41d4-a716-446655440000")!,
+        exercises: [
+            Exercise.fixture(name: "Snatch", sets: 5, reps: 3),
+            Exercise.fixture(name: "Clean & Jerk", sets: 4, reps: 2)
+        ],
+        startedAt: Date(timeIntervalSince1970: 1704067200),
+        status: .inProgress
+    )
+
+    assertSnapshot(of: session, as: .dump)
+}
+```
+
+## Collections and Arrays
+
+```swift
+@Test("captures record history")
+func recordHistory() {
+    let records = [
+        PersonalRecord.fixture(liftType: .snatch, weight: 100.0),
+        PersonalRecord.fixture(liftType: .snatch, weight: 105.0),
+        PersonalRecord.fixture(liftType: .snatch, weight: 110.0)
+    ]
+
+    assertSnapshot(of: records, as: .dump)
+}
+```
+
+## Nested Structures
+
+```swift
+@Test("captures user profile with nested data")
+func userProfileSnapshot() {
+    let profile = UserProfile(
+        user: User.fixture(name: "Alice"),
+        settings: Settings.fixture(
+            notifications: true,
+            theme: .dark
+        ),
+        recentRecords: [
+            PersonalRecord.fixture(liftType: .snatch)
+        ]
+    )
+
+    assertSnapshot(of: profile, as: .dump)
+}
+```
+
+## Comparing Dump vs Custom Dump
+
+SnapshotTesting provides two text strategies:
+
+```swift
+// Standard Swift dump - uses Mirror API
+assertSnapshot(of: object, as: .dump)
+
+// Custom dump - more readable output (recommended)
+assertSnapshot(of: object, as: .customDump)
+```
+
+**Prefer `.customDump`** for better readability with:
+- Sorted dictionary keys
+- Condensed output for simple values
+- Better enum representation
+
+## Recording Mode
+
+First run records baselines. To re-record:
+
+```swift
+// Re-record this snapshot
+assertSnapshot(of: record, as: .dump, record: true)
+```
+
+Or use environment variable:
+
+```bash
+SNAPSHOT_TESTING_RECORD=1 swift test
+```
+
+## Deterministic Snapshots
+
+Ensure consistent output by controlling variable data:
+
+```swift
+@Test("captures record with deterministic values")
+func deterministicSnapshot() {
+    // Use fixed UUID
+    let id = UUID(uuidString: "550e8400-e29b-41d4-a716-446655440000")!
+
+    // Use fixed date
+    let date = Date(timeIntervalSince1970: 1704067200) // 2024-01-01
+
+    let record = PersonalRecord(
+        id: id,
+        liftType: .snatch,
+        weight: 120.0,
+        date: date
+    )
+
+    assertSnapshot(of: record, as: .dump)
+}
+```
+
+## Organization
+
+```
+Tests/
+└── DomainTests/
+    ├── Snapshots/
+    │   ├── PersonalRecordSnapshotTests.swift
+    │   └── __Snapshots__/
+    │       └── PersonalRecordSnapshotTests/
+    │           ├── recordStructure.txt
+    │           └── liftTypeSnapshots-snatch.txt
+```
+
+## Best Practices
+
+### Use Fixtures with Fixed Values
+
+```swift
+// Good - deterministic
+let record = PersonalRecord.fixture(
+    id: UUID(uuidString: "00000000-0000-0000-0000-000000000001")!,
+    date: Date(timeIntervalSince1970: 0)
+)
+
+// Bad - non-deterministic
+let record = PersonalRecord.fixture() // Random UUID, current date
+```
+
+### Name Parameterized Snapshots
+
+```swift
+// Good - clear file names
+assertSnapshot(of: record, as: .dump, named: "snatch-120kg")
+
+// Avoid - generic names
+assertSnapshot(of: record, as: .dump)
+```
+
+### Review Diffs Carefully
+
+Dump snapshots capture all properties. When reviewing:
+1. Verify intentional changes
+2. Catch unintended side effects
+3. Update baselines only after careful review
+
+### Combine with Unit Tests
+
+Dump snapshots complement, not replace, unit tests:
+
+```swift
+@Test("validates and snapshots transformation")
+func transformRecord() {
+    let input = APIResponse.fixture()
+    let output = RecordMapper.map(input)
+
+    // Unit assertion for critical behavior
+    #expect(output.weight == input.weightKg)
+
+    // Snapshot for complete structure
+    assertSnapshot(of: output, as: .dump)
+}
+```
+
+## Troubleshooting
+
+### Non-Deterministic Failures
+
+If snapshots fail intermittently:
+- Check for `UUID()` or `Date()` without fixed values
+- Ensure dictionary ordering is consistent
+- Use `.customDump` for sorted keys
+
+### Large Snapshots
+
+For objects with many properties:
+
+```swift
+// Snapshot specific parts
+assertSnapshot(of: session.exercises, as: .dump, named: "exercises")
+assertSnapshot(of: session.metadata, as: .dump, named: "metadata")
+```
+
+### Unreadable Output
+
+Switch to custom dump for cleaner output:
+
+```swift
+// Before: standard dump
+assertSnapshot(of: complex, as: .dump)
+
+// After: cleaner formatting
+assertSnapshot(of: complex, as: .customDump)
+```

package/skills/swift-testing/references/fixtures.md

@@ -0,0 +1,193 @@
+# Fixtures
+
+Fixtures are factory methods that simplify creating test objects with sensible defaults.
+
+## Fixture Placement
+
+Place fixtures **close to the model**, not in test targets:
+
+```swift
+// In Sources/Models/PersonalRecord.swift
+
+public struct PersonalRecord: Equatable, Sendable {
+    public let id: UUID
+    public let liftType: LiftType
+    public let weight: Double
+    public let reps: Int
+    public let date: Date
+    public let isPersonalBest: Bool
+
+    public init(
+        id: UUID,
+        liftType: LiftType,
+        weight: Double,
+        reps: Int,
+        date: Date,
+        isPersonalBest: Bool = false
+    ) {
+        self.id = id
+        self.liftType = liftType
+        self.weight = weight
+        self.reps = reps
+        self.date = date
+        self.isPersonalBest = isPersonalBest
+    }
+}
+
+// Fixture lives alongside the model
+#if DEBUG
+extension PersonalRecord {
+    public static func fixture(
+        id: UUID = UUID(),
+        liftType: LiftType = .snatch,
+        weight: Double = 100.0,
+        reps: Int = 1,
+        date: Date = Date(),
+        isPersonalBest: Bool = false
+    ) -> PersonalRecord {
+        PersonalRecord(
+            id: id,
+            liftType: liftType,
+            weight: weight,
+            reps: reps,
+            date: date,
+            isPersonalBest: isPersonalBest
+        )
+    }
+}
+#endif
+```
+
+## Benefits
+
+1. **Tests show relevant data**: Only specify properties that matter
+2. **Reduces boilerplate**: Defaults for unimportant properties
+3. **Consistent test data**: Same defaults across suite
+4. **Auto-available**: No imports beyond model's module
+5. **Zero production overhead**: `#if DEBUG` strips from release
+
+## Usage Patterns
+
+### Minimal Specification
+
+```swift
+@Test("returns nickname when present")
+func returnsNicknameWhenPresent() {
+    // Only specify what matters for THIS test
+    let user = User.fixture(nickname: "Johnny")
+    let sut = ProfileViewModel(user: user)
+
+    let displayName = sut.getUserName()
+
+    #expect(displayName == "Johnny")
+}
+```
+
+### Multiple Fixtures
+
+```swift
+@Test("sorts records by date")
+func sortsRecordsByDate() {
+    let oldRecord = PersonalRecord.fixture(
+        date: Date().addingTimeInterval(-86400)
+    )
+    let newRecord = PersonalRecord.fixture(
+        date: Date()
+    )
+
+    let sorted = sut.sort([oldRecord, newRecord])
+
+    #expect(sorted.first?.id == newRecord.id)
+}
+```
+
+### Fixture Collections
+
+```swift
+#if DEBUG
+extension PersonalRecord {
+    public static func fixtures(count: Int) -> [PersonalRecord] {
+        (0..<count).map { _ in .fixture() }
+    }
+
+    public static var sampleCollection: [PersonalRecord] {
+        [
+            .fixture(liftType: .snatch, weight: 80),
+            .fixture(liftType: .cleanAndJerk, weight: 100),
+            .fixture(liftType: .squat, weight: 150),
+        ]
+    }
+}
+#endif
+```
+
+### Nested Fixtures
+
+```swift
+#if DEBUG
+extension User {
+    public static func fixture(
+        id: UUID = UUID(),
+        profile: Profile = .fixture(),
+        settings: Settings = .fixture()
+    ) -> User {
+        User(id: id, profile: profile, settings: settings)
+    }
+}
+
+extension Profile {
+    public static func fixture(
+        name: String = "Test User",
+        email: String = "test@example.com"
+    ) -> Profile {
+        Profile(name: name, email: email)
+    }
+}
+#endif
+```
+
+## Fixture Guidelines
+
+### Do
+
+- Provide sensible defaults for all properties
+- Make defaults representative of typical data
+- Use `#if DEBUG` to exclude from production
+- Make fixture method `public static`
+- Mirror initializer parameter order
+
+### Don't
+
+- Use random values (breaks repeatability)
+- Include fixtures in production builds
+- Create fixtures in test targets (harder to share)
+- Use dates like `Date()` without allowing override
+
+## Date Handling
+
+```swift
+#if DEBUG
+extension PersonalRecord {
+    public static func fixture(
+        // Use a fixed reference date, not Date()
+        date: Date = Date(timeIntervalSince1970: 1704067200)  // 2024-01-01
+    ) -> PersonalRecord {
+        // ...
+    }
+}
+#endif
+```
+
+Or use a test clock dependency:
+
+```swift
+@Dependency(\.date) var date
+
+// In test
+let fixedDate = Date(timeIntervalSince1970: 1704067200)
+withDependencies {
+    $0.date = .constant(fixedDate)
+} operation: {
+    // Tests use fixed date
+}
+```

package/skills/swift-testing/references/integration-testing.md

@@ -0,0 +1,189 @@
+# Integration Testing
+
+Integration tests verify module interactions - the 15% of your testing pyramid.
+
+## When to Write Integration Tests
+
+- Testing component boundaries (use case -> repository -> storage)
+- Verifying workflows across multiple components
+- Testing real implementations with in-memory storage
+- Validating data flows end-to-end within a module
+
+## Basic Structure
+
+```swift
+import Testing
+@testable import PersonalRecordsCore
+
+@Suite("PersonalRecords Integration Tests")
+struct PersonalRecordsIntegrationTests {
+
+    @Test("save and retrieve workflow completes successfully")
+    func saveAndRetrieveWorkflow() async throws {
+        // Use real implementations with in-memory storage
+        let storage = InMemoryStorageService()
+        let repository = PersonalRecordsRepository(storage: storage)
+        let saveUseCase = SavePRUseCase(repository: repository)
+        let loadUseCase = LoadPRUseCase(repository: repository)
+
+        let record = PersonalRecord.fixture(weight: 120.0)
+
+        // Save
+        try await saveUseCase.dispatch(record)
+
+        // Retrieve and verify
+        let loaded = try await loadUseCase.dispatch()
+
+        #expect(loaded.count == 1)
+        #expect(loaded.first?.weight == 120.0)
+    }
+}
+```
+
+## In-Memory Implementations
+
+Create fakes for external dependencies:
+
+```swift
+final class InMemoryStorageService: StorageServiceProtocol {
+    private var storage: [String: Data] = [:]
+    private let lock = NSLock()
+
+    func save(_ data: Data, forKey key: String) async throws {
+        lock.lock()
+        defer { lock.unlock() }
+        storage[key] = data
+    }
+
+    func load(forKey key: String) async throws -> Data? {
+        lock.lock()
+        defer { lock.unlock() }
+        return storage[key]
+    }
+
+    func delete(forKey key: String) async throws {
+        lock.lock()
+        defer { lock.unlock() }
+        storage.removeValue(forKey: key)
+    }
+}
+```
+
+## Testing Workflows
+
+### Multi-Step Operations
+
+```swift
+@Test("complete user registration workflow")
+func registrationWorkflow() async throws {
+    // Setup real components with test dependencies
+    let userStorage = InMemoryUserStorage()
+    let tokenStorage = InMemoryTokenStorage()
+    let userService = UserService(storage: userStorage)
+    let authService = AuthService(tokenStorage: tokenStorage)
+
+    let sut = RegistrationWorker(
+        userService: userService,
+        authService: authService
+    )
+
+    // Execute workflow
+    let result = try await sut.register(
+        username: "testuser",
+        password: "SecurePass123"
+    )
+
+    // Verify end state
+    #expect(result.isSuccess)
+    #expect(userStorage.users.contains { $0.username == "testuser" })
+    #expect(tokenStorage.hasToken)
+}
+```
+
+### Error Propagation
+
+```swift
+@Test("propagates storage errors through use case")
+func errorPropagation() async throws {
+    let failingStorage = FailingStorageService()
+    let repository = PersonalRecordsRepository(storage: failingStorage)
+    let sut = LoadPRUseCase(repository: repository)
+
+    #expect(throws: PRError.storageUnavailable) {
+        try await sut.dispatch()
+    }
+}
+```
+
+## Tagging Integration Tests
+
+Use tags to filter tests:
+
+```swift
+extension Tag {
+    @Tag static var integration: Self
+}
+
+@Suite("Integration Tests", .tags(.integration))
+struct PersonalRecordsIntegrationTests {
+    // ...
+}
+```
+
+Run only integration tests:
+
+```bash
+swift test --filter integration
+```
+
+## Integration Test Guidelines
+
+### Do
+
+- Test component boundaries
+- Use in-memory implementations for storage
+- Test complete workflows
+- Verify data flows correctly
+- Tag tests for filtering
+
+### Don't
+
+- Test UI (use snapshot/UI tests)
+- Use real network calls
+- Use real databases
+- Test third-party libraries
+- Write too many (15% of pyramid)
+
+## Test Organization
+
+```
+Tests/
+└── PersonalRecordsCoreTests/
+    ├── Unit/
+    │   ├── UseCases/
+    │   └── Repositories/
+    ├── Integration/
+    │   ├── WorkflowTests.swift
+    │   └── DataFlowTests.swift
+    └── Helpers/
+        └── InMemoryStorage.swift
+```
+
+## Performance Considerations
+
+Integration tests are slower than unit tests:
+
+```swift
+@Test("bulk import performance", .timeLimit(.minutes(1)))
+func bulkImportPerformance() async throws {
+    let storage = InMemoryStorageService()
+    let repository = PersonalRecordsRepository(storage: storage)
+    let sut = BulkImportUseCase(repository: repository)
+
+    let records = PersonalRecord.fixtures(count: 1000)
+
+    try await sut.dispatch(records)
+
+    #expect(storage.count == 1000)
+}
+```