Contract-Test Harness

# Contract-Test Harness

A Claude Code project configuration for consumer-driven contract testing between services.

## What it does

When this harness is active, Claude Code follows a contract-first discipline for API
interactions between services. The consumer defines what it expects; the provider must
prove it delivers exactly that — or the build breaks.

- **Consumer side:** Claude helps you write a contract file (Pact JSON or a plain schema)
  that describes the requests your service sends and the responses it needs.
- **Provider verification:** Claude runs the contract against the live or mocked provider
  and reports which interactions pass and which fail.
- **Drift detection:** When a provider changes a response shape, status code, or required
  field, the verification step catches it before the change reaches production.
- **CI integration:** The settings gate keeps bash scoped to contract tools so the harness
  is safe to run in a CI context without broad permissions.

## Files in this harness

| File | Purpose |
|------|---------|
| `README.md` | This guide — Claude reads it as its working instructions |
| `settings.json` | Claude Code project settings — copy to `.claude/settings.json` |

## Setup

1. Copy `settings.json` to `.claude/settings.json` in your project root.
2. Open your project in Claude Code.
3. Tell Claude which services are involved and which tool you use, e.g.:
   "The `orders` service consumes the `inventory` service API. We use Pact."

Claude will scaffold a contracts directory, a consumer test file, and a provider
verification script.

## Workflow reference

### Defining a contract
Tell Claude: "Define a contract for how `orders` calls `GET /products/:id`."

Claude will:
1. Ask what fields the consumer actually uses from the response (not just what the
   provider returns — only what the consumer reads matters).
2. Generate a Pact interaction or JSON schema scoped to those fields.
3. Write a consumer test that records the interaction and asserts it matches the contract.

### Verifying the provider
Tell Claude: "Verify the `inventory` provider against the `orders` consumer contracts."

Claude will run the provider verification script against the contract files and report
each interaction as PASS or FAIL.

### Detecting drift
Tell Claude: "The `inventory` team changed the `/products/:id` response. Check for drift."

Claude reruns verification, highlights every broken interaction, and explains what changed
and which consumer fields are affected.

## Commands

- `/contract <consumer> <provider> <endpoint>` — Scaffold a consumer contract for a
  specific interaction, scoped to only the fields the consumer reads.
- `/verify-provider <provider>` — Run provider verification against all consumer contracts
  and report PASS/FAIL per interaction.
- `/contract-drift` — Rerun verification after a provider change and summarise every
  broken interaction with the field-level diff.

## Allowed bash commands

The harness permits contract-testing tools:

- `Bash(npx pact*)`, `Bash(pact*)` — Pact consumer and provider tests
- `Bash(npm test*)`, `Bash(npx vitest*)`, `Bash(npx jest*)` — run consumer tests
  that generate Pact files
- `Bash(curl*)` — probe the provider before a verification run
- `Bash(git diff*)`, `Bash(git status*)`, `Bash(git log*)` — inspect changes

Destructive commands and pushes are blocked.

## Known limitations

- Pact broker integration (publishing and fetching contracts from a broker) requires
  broker credentials; tell Claude your broker URL at session start.
- The harness covers HTTP/REST contracts; message-queue contracts need the Pact message
  provider setup, which Claude can scaffold if you describe your message format.

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Write(**)",
      "Edit(**)",
      "Bash(npx pact*)",
      "Bash(pact*)",
      "Bash(npm test*)",
      "Bash(npx vitest*)",
      "Bash(npx jest*)",
      "Bash(curl*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(git log*)"
    ],
    "deny": [
      "Bash(git push*)",
      "Bash(git reset --hard*)",
      "Bash(git restore*)",
      "Bash(git clean*)",
      "Bash(rm -rf*)"
    ]
  }
}