Index of every page on this site: llms.txt
All skills
rshankras avatar

/test-contract

@f958982
Run it yourself

Generate protocol/interface test suites that any implementation must pass. Define the contract once, test every implementation. Use when designing protocols or swapping implementations.

Use this Skill: https://skilld.dev/gh/rshankras/claude-code-apple-skills/test-contract

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈50 tokens for metadata: the name and description. ≈1.9k when used: this file.

Description uses 2.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈201 characters, or 2.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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
- Saved item is retrievable by ID

### 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
- 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
}

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
  • 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

  • InMemoryDataStore — all passing
  • 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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts3mo3 checks · Risk SAFE
  • Gen Agent Trust Hub3mo

    This skill is a software engineering tool designed to generate behavioral contract tests for Swift protocols. It scans a codebase to identify protocol definitions and produces generic test suites to ensure that all implementations—whether production, mock, or in-memory—adhere to the same specification. No malicious patterns such as exfiltration, obfuscation, or persistence were found. As a code generation tool that processes local source files, it presents a standard but manageable attack surface for indirect prompt injection.

  • Socket3mo

    No alerts

  • Snyk3mo

    Risk: LOW · No issues

Signed by skilld at f958982. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 4 months ago
What it can do
Reads files Edits files Runs commands
last_verified
2026-07-16
review_by
2027-06-22
All 7 allowed tools
ReadWriteEditGlobGrepBashAskUserQuestion

README badge

README badge for rshankras/claude-code-apple-skills/test-contract