integration-test-scaffold

What this skill does

# Integration Test Scaffold

Generate test infrastructure for testing multiple modules working together — networking + persistence + business logic — without hitting real servers or databases.

## When This Skill Activates

Use this skill when the user:
- Wants to "test the full stack" or "integration test"
- Needs a mock server or mock API
- Wants to test networking + caching together
- Asks about "end-to-end tests without real servers"
- Needs to test data flow across layers (API → Repository → ViewModel)
- Mentions "test harness" or "test environment"

## Why Integration Tests

```
Unit tests:         Test ONE thing in isolation (fast, focused)
Integration tests:  Test MULTIPLE things together (realistic, catches wiring bugs)

Unit test passes:   PriceCalculator works alone ✅
Integration test:   PriceCalculator + API + Cache work together ✅
                    (Catches: wrong data format, missing mapping, race conditions)
```

## Process

### Phase 1: Map the Integration Boundaries

Identify what modules interact:

```
Grep: "import |@testable import" to find module dependencies
Read: source files to understand data flow
```

Common integration boundaries:
- **Network → Parser → Repository** (API data flow)
- **Repository → ViewModel → View** (UI data flow)
- **UserAction → Service → Storage → Notification** (write flow)

### Phase 2: Configuration Questions

Ask via AskUserQuestion:

1. **What layers to integrate?**
   - Network + Repository
   - Repository + ViewModel
   - Full stack (Network → ViewModel)
   - Custom combination

2. **Mock strategy?**
   - URLProtocol-based mock server (intercepts real URLSession)
   - Protocol-based mock (swap implementation)
   - In-memory database (SwiftData/CoreData)

### Phase 3: Generate Mock Server

#### URLProtocol Mock Server

```swift
// Tests/Infrastructure/MockURLProtocol.swift

final class MockURLProtocol: URLProtocol {
    /// Map of URL path → (status code, response data)
    static var mockResponses: [String: (Int, Data)] = [:]
    /// Captured requests for verification
    static var capturedRequests: [URLRequest] = []
    /// Simulated delay
    static var responseDelay: TimeInterval = 0

    static func reset() {
        mockResponses = [:]
        capturedRequests = []
        responseDelay = 0
    }

    override class func canInit(with request: URLRequest) -> Bool {
        true  // Intercept all requests
    }

    override class func canonicalRequest(for request: URLRequest) -> URLRequest {
        request
    }

    override func startLoading() {
        Self.capturedRequests.append(request)

        let path = request.url?.path ?? ""
        let (statusCode, data) = Self.mockResponses[path] ?? (404, Data())

        let response = HTTPURLResponse(
            url: request.url!,
            statusCode: statusCode,
            httpVersion: nil,
            headerFields: ["Content-Type": "application/json"]
        )!

        if Self.responseDelay > 0 {
            Thread.sleep(forTimeInterval: Self.responseDelay)
        }

        client?.urlProtocol(self, didReceive: response, cacheStoragePolicy: .notAllowed)
        client?.urlProtocol(self, didLoad: data)
        client?.urlProtocolDidFinishLoading(self)
    }

    override func stopLoading() {}
}
```

#### Mock Server Helper

```swift
// Tests/Infrastructure/MockServer.swift

struct MockServer {
    /// Register a successful JSON response for a path
    static func respondWith<T: Encodable>(
        _ value: T,
        for path: String,
        statusCode: Int = 200
    ) {
        let data = try! JSONEncoder().encode(value)
        MockURLProtocol.mockResponses[path] = (statusCode, data)
    }

    /// Register a raw data response
    static func respondWith(
        data: Data,
        for path: String,
        statusCode: Int = 200
    ) {
        MockURLProtocol.mockResponses[path] = (statusCode, data)
    }

    /// Register an error response
    static func respondWithError(
        for path: String,
        statusCode: Int = 500
    ) {
        let error = ["error": "Server Error"]
        let data = try! JSONEncoder().encode(error)
        MockURLProtocol.mockResponses[path] = (statusCode, data)
    }

    /// Create a URLSession configured to use mock responses
    static func session() -> URLSession {
        let config = URLSessionConfiguration.ephemeral
        config.protocolClasses = [MockURLProtocol.self]
        return URLSession(configuration: config)
    }
}
```

### Phase 4: Generate In-Memory Store

#### SwiftData In-Memory

```swift
// Tests/Infrastructure/InMemoryModelContainer.swift

import SwiftData

enum TestModelContainer {
    @MainActor
    static func create(for types: any PersistentModel.Type...) -> ModelContainer {
        let schema = Schema(types)
        let config = ModelConfiguration(isStoredInMemoryOnly: true)
        return try! ModelContainer(for: schema, configurations: config)
    }
}

// Usage in tests:
@Test("saves and fetches items")
@MainActor
func savesAndFetches() async throws {
    let container = TestModelContainer.create(for: Item.self)
    let context = container.mainContext

    let item = Item(title: "Test")
    context.insert(item)
    try context.save()

    let fetched = try context.fetch(FetchDescriptor<Item>())
    #expect(fetched.count == 1)
}
```

#### UserDefaults In-Memory

```swift
// Tests/Infrastructure/MockUserDefaults.swift

final class MockUserDefaults: UserDefaults {
    private var storage: [String: Any] = [:]

    override func object(forKey defaultName: String) -> Any? {
        storage[defaultName]
    }

    override func set(_ value: Any?, forKey defaultName: String) {
        storage[defaultName] = value
    }

    override func removeObject(forKey defaultName: String) {
        storage.removeValue(forKey: defaultName)
    }

    override func bool(forKey defaultName: String) -> Bool {
        storage[defaultName] as? Bool ?? false
    }

    override func string(forKey defaultName: String) -> String? {
        storage[defaultName] as? String
    }

    func reset() {
        storage.removeAll()
    }
}
```

### Phase 5: Generate Test Environment

#### Dependency Container for Tests

```swift
// Tests/Infrastructure/TestEnvironment.swift

@testable import YourApp

struct TestEnvironment {
    let session: URLSession
    let container: ModelContainer
    let defaults: MockUserDefaults
    let apiClient: APIClient
    let repository: ItemRepository
    let viewModel: ItemListViewModel

    @MainActor
    static func create() -> TestEnvironment {
        let session = MockServer.session()
        let container = TestModelContainer.create(for: Item.self)
        let defaults = MockUserDefaults()

        let apiClient = APIClient(session: session)
        let repository = ItemRepository(
            apiClient: apiClient,
            modelContext: container.mainContext
        )
        let viewModel = ItemListViewModel(repository: repository)

        return TestEnvironment(
            session: session,
            container: container,
            defaults: defaults,
            apiClient: apiClient,
            repository: repository,
            viewModel: viewModel
        )
    }
}
```

### Phase 6: Generate Integration Tests

#### Full Stack Test: API → Repository → ViewModel

```swift
import Testing
import SwiftData
@testable import YourApp

@Suite("Integration: Item Data Flow")
struct ItemDataFlowIntegrationTests {

    @Test("fetches items from API and displays in ViewModel")
    @MainActor
    func fetchAndDisplay() async throws {
        // Arrange
        MockURLProtocol.reset()
        let env = TestEnvironment.create()
        let items = [
            APIItem(id: "1", title: "First", description: "Desc 1"),
            APIItem(id: "2", title: "Second", description: "Desc 2")
        ]
        MockServer.respondWith(items, for: "/api/items")

        // Act
        await env.viewModel.loadItems()

        // Assert — verify end-to-end
        #