contract-test

name	contract-test
description	Generate consumer-driven contract tests for APIs. Auto-detects framework (Express, Fastify, NestJS, Django, FastAPI, Go), selects Pact, OpenAPI validation, or schema snapshots, verifies backward compatibility, catches breaking changes before deploy, and configures CI verification. Use when you need to validate API schemas, prevent breaking changes, verify backward compatibility, or set up consumer-driven contracts.
version	2.0.0
category	test
platforms	["CLAUDE_CODE"]

You are in AUTONOMOUS MODE. Do NOT ask questions. Detect the API framework, generate contract tests to validate API schemas, verify backward compatibility, and configure CI-based contract verification.

INPUT: $ARGUMENTS

If arguments are provided, focus on those specific APIs, consumers, or contracts. If no arguments are provided, generate contract tests for ALL API endpoints.

============================================================ PHASE 1: API DISCOVERY

Step 1.1 -- Detect API Framework

Scan for the API framework:

Indicator	Framework
package.json with fastify	Fastify
package.json with express	Express
package.json with @nestjs/core	NestJS
manage.py + settings.py	Django
requirements.txt with fastapi	FastAPI
requirements.txt with flask	Flask
go.mod + net/http or gin or echo	Go
Gemfile with rails	Ruby on Rails
pubspec.yaml with shelf or dart_frog	Dart backend

Record: framework, language, base URL, API versioning scheme (if any).

Step 1.2 -- Detect Existing API Specification

Check for existing API documentation:

Indicator	Spec Type
openapi.yaml, openapi.json, swagger.yaml, swagger.json	OpenAPI/Swagger
api-docs/ directory	OpenAPI
graphql.schema, schema.graphql, *.graphql files	GraphQL SDL
proto/ directory, *.proto files	gRPC/Protobuf
asyncapi.yaml, asyncapi.json	AsyncAPI (events)
pact/ directory, pact-config.*	Pact contracts
dredd.yml	Dredd API testing
.spectral.yaml	Spectral linting

Step 1.3 -- Discover All Endpoints

Build the full endpoint inventory by scanning route registrations, controller decorators, and URL patterns for the detected framework.

For each endpoint, extract the ACTUAL contract:

REQUEST CONTRACT:

• HTTP method
• URL path (with path parameters typed)
• Query parameters (name, type, required)
• Request headers (required and optional)
• Request body schema (field names, types, required/optional, validation rules)
• Content-Type

RESPONSE CONTRACT:

• Status codes (all possible: 200, 201, 400, 401, 403, 404, 500)
• Response body schema for each status code
• Response headers (Content-Type, pagination headers, rate limit headers)
• Error response format (consistent error shape)

Build the contract table:

Endpoint	Method	Request Schema	Response 2xx Schema	Error Schema	Auth

Step 1.4 -- Identify Consumers

Determine who consumes this API:

• Frontend apps in the same repo (monorepo)
• Mobile apps
• Other microservices
• Third-party integrations
• Public API consumers

If consumers are in the same repo, read their API call code to extract ACTUAL usage patterns (which fields they send, which fields they read).

============================================================ PHASE 2: CONTRACT TOOL SETUP

Step 2.1 -- Select Contract Testing Approach

Choose based on project needs:

APPROACH 1 -- OPENAPI VALIDATION (schema-first): Best for: Projects with an OpenAPI spec, or projects that should have one. Tools: Prism (mock server), Spectral (linting), committee (Ruby), openapi-enforcer (Node.js)

APPROACH 2 -- CONSUMER-DRIVEN CONTRACTS (Pact): Best for: Microservice architectures with multiple consumers. Tools: Pact (pact-js, pact-python, pact-go)

APPROACH 3 -- API BLUEPRINT + DREDD: Best for: Projects using API Blueprint documentation. Tools: Dredd

APPROACH 4 -- SCHEMA SNAPSHOT TESTING: Best for: Simple projects where a full contract framework is overkill. Tools: Jest/Vitest snapshot tests on API response shapes

Decision logic:

1. If OpenAPI spec exists -> APPROACH 1 (validate against spec)
2. If multiple consumers exist -> APPROACH 2 (Pact)
3. If API Blueprint exists -> APPROACH 3 (Dredd)
4. If simple single-consumer project -> APPROACH 4 (schema snapshots)
5. If no spec exists -> Generate OpenAPI spec from code, then APPROACH 1

Step 2.2 -- Install Tools

FOR OPENAPI VALIDATION:

If no OpenAPI spec exists, generate one:

Framework	Generation Method
Fastify	Use @fastify/swagger to auto-generate from route schemas
Express + Zod/Joi	Extract schemas from validation middleware
NestJS	Use @nestjs/swagger decorators (may already exist)
FastAPI	Auto-generated at /openapi.json
Django REST	Use drf-spectacular or drf-yasg
Go (Gin/Echo)	Use swaggo/swag annotations

Install validation tools:

• Node.js: npm install -D @stoplight/prism-cli @stoplight/spectral-cli
• Python: pip install openapi-core schemathesis
• Ruby: gem install committee

FOR PACT:

Install consumer and provider packages:

• Node.js: npm install -D @pact-foundation/pact
• Python: pip install pact-python
• Go: (use pact-go, requires pact CLI tools)

FOR SCHEMA SNAPSHOTS:

No additional installation needed. Uses existing test framework snapshot capabilities.

============================================================ PHASE 3: CONTRACT TEST GENERATION

Step 3.1 -- OpenAPI Validation Tests

If using APPROACH 1:

SPEC LINTING:

• Run Spectral against the OpenAPI spec
• Check for: missing descriptions, inconsistent naming, missing error responses, deprecated endpoints without alternatives

RESPONSE VALIDATION: For each endpoint, generate a test that:

1. Calls the endpoint with valid request data
2. Validates the response against the OpenAPI schema
3. Verifies all required fields are present
4. Verifies field types match the schema
5. Verifies enum values are within allowed set
6. Verifies nullable fields handle null correctly

REQUEST VALIDATION: For each endpoint, generate a test that:

1. Sends a request missing required fields -> verify 400
2. Sends a request with wrong field types -> verify 400
3. Sends a request with extra unknown fields -> verify behavior (ignored or rejected)
4. Sends a request with invalid enum values -> verify 400

SCHEMA FUZZ TESTING:

• Use Schemathesis (Python) or openapi-fuzzer to auto-generate edge case inputs
• Run: schemathesis run http://localhost:PORT/openapi.json --checks all

Step 3.2 -- Consumer-Driven Contract Tests (Pact)

If using APPROACH 2:

CONSUMER SIDE: For each consumer, generate a Pact test that:

1. Defines the expected interactions (request + expected response)
2. Uses the Pact mock provider to simulate the API
3. Runs the consumer code against the mock
4. Generates a contract file (pact JSON)

Interactions to define:

• Every API call the consumer makes
• The specific request fields the consumer sends
• The specific response fields the consumer reads
• Error responses the consumer handles

PROVIDER SIDE: Generate a provider verification test that:

1. Starts the real API server
2. Loads all consumer contract files
3. Replays each interaction against the real API
4. Verifies responses match the contract
5. Uses provider states to set up required data

Provider state handlers:

• "user exists": create a test user
• "resource exists": create a test resource
• "no data": ensure empty state
• "unauthorized": use invalid credentials

Step 3.3 -- Schema Snapshot Tests

If using APPROACH 4:

For each endpoint, generate a test that:

1. Calls the endpoint with valid data
2. Extracts the response body shape (field names and types, not values)
3. Compares against a stored snapshot
4. Fails if the shape changed (field added, removed, or type changed)

Shape extraction function:

• Recursively walk the response object
• Record field name, type, and whether it is an array
• Sort fields alphabetically for deterministic comparison
• Handle nested objects and arrays of objects

Step 3.4 -- Backward Compatibility Tests

Generate tests that verify API changes do not break existing consumers:

FIELD REMOVAL:

• Verify no response fields were removed compared to the previous version
• Any removed field is a BREAKING CHANGE

FIELD TYPE CHANGE:

• Verify no response field types changed (string -> number is breaking)
• Any type change is a BREAKING CHANGE

REQUIRED FIELD ADDITION (request):

• Verify no new required request fields were added
• New required fields break existing consumers

STATUS CODE CHANGE:

• Verify existing endpoints return the same status codes
• Changing 200 to 201 or vice versa can break consumers

URL CHANGE:

• Verify no endpoint URLs changed
• Renaming /api/users to /api/v2/users breaks consumers unless both work

Generate a compatibility report:

Change	Type	Breaking?	Affected Consumers

============================================================ PHASE 4: EXECUTION

Step 4.1 -- Run Contract Tests

Execute all generated contract tests:

Approach	Command
OpenAPI + Prism	npx prism mock openapi.yaml && run validation tests
OpenAPI + Schemathesis	schemathesis run http://localhost:PORT/openapi.json
Spectral linting	npx spectral lint openapi.yaml
Pact consumer	npx vitest run tests/contract/consumer/
Pact provider	npx vitest run tests/contract/provider/
Schema snapshots	npx vitest run tests/contract/

Step 4.2 -- Self-Healing Loop (max 3 iterations)

For each failure, diagnose:

SPEC MISMATCH: The API response does not match the documented schema. -> Either fix the API to match the spec, or update the spec to match reality. -> Prefer fixing the spec if the API behavior is intentional.

CONTRACT VIOLATION: Provider does not satisfy consumer expectations. -> Fix the provider if the consumer expectation is valid. -> Update the consumer contract if the expectation was wrong.

SNAPSHOT DRIFT: Response shape changed from baseline. -> If intentional: update the snapshot. -> If unintentional: fix the API to restore the original shape.

Step 4.3 -- Publish Contracts (if using Pact)

If a Pact Broker is configured:

• Publish consumer contracts: npx pact-broker publish
• Tag with the branch name and version
• Verify can-i-deploy before merge

============================================================ OUTPUT

Contract Test Report

API Overview

• Framework: [detected]
• API spec: [OpenAPI / GraphQL / none -> generated]
• Contract approach: [OpenAPI validation / Pact / Schema snapshots]
• Endpoints tested: [count]
• Consumers identified: [list]

Spec Quality (if OpenAPI)

• Spectral lint: [N errors, N warnings]
• Missing descriptions: [count]
• Missing error responses: [count]
• Inconsistent naming: [list]

Contract Validation Results

Endpoint	Request Valid	Response Valid	Types Match	Backward Compatible

Backward Compatibility

Change Detected	Type	Breaking	Action Required

Breaking Changes Found

• Total: N
• [list each with impact description]

Results Summary

• Total contract tests: N
• Passed: N
• Failed: N
• Breaking changes: N
• Spec lint issues: N

NEXT STEPS:

• "Breaking changes found? Fix the API or version the endpoint before deploying."
• "No OpenAPI spec? The generated spec is at [path]. Review and commit it."
• "Run /integration-test to verify the contracts hold under real conditions."
• "Run /test-suite to see overall test health with contract coverage."
• "Add contract verification to CI so breaking changes are caught before merge."
• "Run /load-test to verify contract-compliant endpoints perform under load."

DO NOT:

• Do NOT skip backward compatibility checks. Breaking changes cause production incidents.
• Do NOT auto-approve breaking changes. Always flag them for human review.
• Do NOT generate contracts from documentation alone. Validate against the real API.
• Do NOT mock the API in provider-side contract tests. Use the real implementation.
• Do NOT ignore optional fields in contract validation. They must still have correct types.
• Do NOT generate contracts for internal implementation details (private methods, internal routes).
• Do NOT skip error response contracts. Error shapes must be consistent and documented.
• Do NOT update snapshots or baselines without verifying the change is intentional.

============================================================ SELF-EVOLUTION TELEMETRY

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /contract-test — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.