Test Contract Skill | Agent Skills

Test Contract

Define behavioral contracts as test suites. Any class conforming to a protocol must pass the contract tests. Ensures consistent behavior across implementations — human-written, AI-generated, or mock.

When This Skill Activates

Use this skill when the user:

Designs a protocol and wants to ensure conformance quality
Has multiple implementations of the same interface (e.g., real + mock + in-memory)
Says "test the protocol" or "contract test"
Wants to swap implementations safely (e.g., CoreData → SwiftData)
Wants to ensure AI-generated implementations meet the spec

Why Contract Tests

Protocol: DataStore
  ├── SQLiteDataStore  → must pass contract tests
  ├── InMemoryDataStore → must pass contract tests
  ├── MockDataStore    → must pass contract tests
  └── CloudDataStore   → must pass contract tests

Write the contract once. Every implementation proves it works by passing the same tests.

Process

Phase 1: Identify the Protocol

Grep: "protocol.*\\{" to find protocols
Read: protocol definition

Understand:

[ ] All required methods and properties
[ ] Expected behavior for each method
[ ] Error conditions and edge cases
[ ] Thread safety requirements
[ ] State invariants (e.g., count matches items.count)

Phase 2: Define Contract Behaviors

For each protocol method, define required behaviors:

## DataStore Contract

### save(_ item:)
- Saving a new item increases count by 1
- Saving an existing item (same ID) updates it, count unchanged
- Saved item is retrievable by ID
- Throws on invalid item (empty title)

### fetch(id:)
- Returns item when it exists
- Returns nil when item doesn't exist
- Returns most recently saved version

### delete(id:)
- Deleting existing item decreases count by 1
- Deleting non-existent item does nothing (no throw)
- Deleted item is no longer fetchable

### fetchAll()
- Returns all saved items
- Returns empty array when store is empty
- Items are in consistent order (insertion or specified)

### Invariants
- count == fetchAll().count (always)
- save then fetch returns same item
- delete then fetch returns nil

Phase 3: Generate Contract Test Suite

Pattern: Generic Test Suite

import Testing

/// Contract tests for any DataStore implementation.
/// Subclass or call with your concrete implementation.
struct DataStoreContractTests<Store: DataStore> {

    let makeStore: () -> Store

    init(makeStore: @escaping () -> Store) {
        self.makeStore = makeStore
    }

    // MARK: - save(_ item:)

    @Test("save increases count")
    func saveIncreasesCount() async throws {
        let store = makeStore()
        let item = Item(id: "1", title: "Test")

        try await store.save(item)

        #expect(store.count == 1)
    }

    @Test("save then fetch returns same item")
    func saveAndFetch() async throws {
        let store = makeStore()
        let item = Item(id: "1", title: "Test")

        try await store.save(item)
        let fetched = try await store.fetch(id: "1")

        #expect(fetched?.title == "Test")
    }

    @Test("save existing item updates it")
    func saveUpdates() async throws {
        let store = makeStore()
        try await store.save(Item(id: "1", title: "Original"))
        try await store.save(Item(id: "1", title: "Updated"))

        let fetched = try await store.fetch(id: "1")

        #expect(fetched?.title == "Updated")
        #expect(store.count == 1)
    }

    @Test("save throws on invalid item")
    func saveInvalidThrows() async {
        let store = makeStore()
        let invalid = Item(id: "1", title: "")

        await #expect(throws: DataStoreError.invalidItem) {
            try await store.save(invalid)
        }
    }

    // MARK: - fetch(id:)

    @Test("fetch returns nil for non-existent ID")
    func fetchNonExistent() async throws {
        let store = makeStore()

        let result = try await store.fetch(id: "nonexistent")

        #expect(result == nil)
    }

    // MARK: - delete(id:)

    @Test("delete removes item")
    func deleteRemoves() async throws {
        let store = makeStore()
        try await store.save(Item(id: "1", title: "Test"))

        try await store.delete(id: "1")

        #expect(store.count == 0)
        let fetched = try await store.fetch(id: "1")
        #expect(fetched == nil)
    }

    @Test("delete non-existent does nothing")
    func deleteNonExistent() async throws {
        let store = makeStore()

        try await store.delete(id: "nonexistent")

        #expect(store.count == 0)
    }

    // MARK: - fetchAll()

    @Test("fetchAll returns all items")
    func fetchAll() async throws {
        let store = makeStore()
        try await store.save(Item(id: "1", title: "A"))
        try await store.save(Item(id: "2", title: "B"))

        let all = try await store.fetchAll()

        #expect(all.count == 2)
    }

    @Test("fetchAll returns empty when store is empty")
    func fetchAllEmpty() async throws {
        let store = makeStore()

        let all = try await store.fetchAll()

        #expect(all.isEmpty)
    }

    // MARK: - Invariants

    @Test("count matches fetchAll count")
    func countInvariant() async throws {
        let store = makeStore()
        try await store.save(Item(id: "1", title: "A"))
        try await store.save(Item(id: "2", title: "B"))
        try await store.delete(id: "1")

        let all = try await store.fetchAll()

        #expect(store.count == all.count)
    }
}

Running Contract Tests Per Implementation

@Suite("InMemoryDataStore Contract")
struct InMemoryDataStoreContractTests {
    let contract = DataStoreContractTests { InMemoryDataStore() }

    @Test("save increases count")
    func saveIncreasesCount() async throws {
        try await contract.saveIncreasesCount()
    }

    @Test("save then fetch returns same item")
    func saveAndFetch() async throws {
        try await contract.saveAndFetch()
    }

    // ... all contract tests
}

@Suite("SQLiteDataStore Contract")
struct SQLiteDataStoreContractTests {
    let contract = DataStoreContractTests { SQLiteDataStore(path: ":memory:") }

    @Test("save increases count")
    func saveIncreasesCount() async throws {
        try await contract.saveIncreasesCount()
    }

    // ... all contract tests
}

Alternative: Parameterized by Implementation

@Suite("DataStore Contract")
struct DataStoreContractSuite {

    enum StoreType: String, CaseIterable {
        case inMemory, sqlite, cloud
    }

    func makeStore(_ type: StoreType) -> any DataStore {
        switch type {
        case .inMemory: return InMemoryDataStore()
        case .sqlite: return SQLiteDataStore(path: ":memory:")
        case .cloud: return MockCloudDataStore()
        }
    }

    @Test("save increases count", arguments: StoreType.allCases)
    func saveIncreasesCount(type: StoreType) async throws {
        let store = makeStore(type)
        try await store.save(Item(id: "1", title: "Test"))
        #expect(store.count == 1)
    }

    @Test("fetch non-existent returns nil", arguments: StoreType.allCases)
    func fetchNonExistent(type: StoreType) async throws {
        let store = makeStore(type)
        let result = try await store.fetch(id: "nonexistent")
        #expect(result == nil)
    }
}

Common Contract Categories

Repository / Data Store

CRUD operations (create, read, update, delete)
Query/filter behavior
Ordering guarantees
Uniqueness constraints
Empty state handling

Network Client

Successful response parsing
Error response handling (4xx, 5xx)
Timeout behavior
Retry logic
Request construction (headers, body)

Cache

Store and retrieve
Expiration/TTL
Eviction policy (LRU, size limit)
Thread safety
Persistence across init

Authentication

Login with valid credentials
Reject invalid credentials
Token refresh
Session expiration
Logout clears state

Output Format

## Contract Tests: [Protocol Name]

### Protocol
```swift
protocol DataStore { ... }

Behaviors Tested

| Behavior | Tests | Edge Cases | |----------|-------|------------| | save | 3 | empty title, duplicate ID | | fetch | 2 | non-existent ID | | delete | 2 | non-existent ID | | fetchAll | 2 | empty store | | invariants | 1 | count consistency |

Implementations Tested

[x] InMemoryDataStore — all passing
[x] SQLiteDataStore — all passing
[ ] CloudDataStore — pending implementation

Files Created

Tests/Contracts/DataStoreContractTests.swift
Tests/Contracts/InMemoryDataStoreContractTests.swift


## References

- `testing/tdd-feature/` — for TDD workflow using contract tests
- `generators/test-generator/` — for standard test generation
- Design by Contract (Bertrand Meyer) — theoretical foundation

Agent Skills: Test Contract

Install this agent skill to your local

Skill Files