Agent skill
qa-contract-validator
Validates API contracts by discovering consumers and ensuring responses match their expectations. Detects breaking changes.
Stars
163
Forks
31
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/development/qa-contract-validator
SKILL.md
Contract Validator Agent
You validate that API responses match what consumers expect.
Consumer Discovery
Find consumers by searching for:
1. Frontend Code
# Look for fetch/axios calls
Grep: "fetch\(.*api.*\)" in *.ts, *.tsx, *.js
Grep: "axios\.(get|post|put|delete)" in *.ts, *.tsx, *.js
2. Other Services
# Look for HTTP client usage
Grep: "requests\.(get|post)" in *.py
Grep: "HttpClient" in *.java
Grep: "http\.Get|http\.Post" in *.go
3. Integration Tests
# Tests often document expected contracts
Grep: "assert.*response" in test_*.py
Grep: "expect.*response" in *.test.ts
4. OpenAPI/Swagger Specs
Glob: **/openapi.yaml, **/openapi.json
Glob: **/swagger.yaml, **/swagger.json
Contract Extraction
From consumers, extract expectations:
Example: Frontend Consumer
typescript
// frontend/src/hooks/useUsers.ts
const response = await fetch('/api/users/123');
const user = await response.json();
console.log(user.name, user.email, user.createdAt);
Extracted contract:
json
{
"endpoint": "GET /api/users/{id}",
"consumer": "frontend/src/hooks/useUsers.ts:3",
"expected_fields": ["name", "email", "createdAt"],
"field_types": {
"name": "string",
"email": "string",
"createdAt": "datetime"
}
}
Example: Python Consumer
python
# service/client.py
resp = requests.get(f"{API_URL}/api/users/{user_id}")
data = resp.json()
return User(
id=data["id"],
name=data["name"],
email=data["email"],
active=data.get("active", True)
)
Extracted contract:
json
{
"endpoint": "GET /api/users/{id}",
"consumer": "service/client.py:15",
"expected_fields": ["id", "name", "email"],
"optional_fields": ["active"],
"field_types": {
"id": "integer",
"name": "string",
"email": "string",
"active": "boolean"
}
}
Validation Rules
- Field Presence: All expected fields must be present
- Field Types: Types must match (string, number, boolean, array, object)
- Nullability: If consumer doesn't handle null, field must not be null
- Field Names: Exact match (case-sensitive)
- Array Structure: Array items must match expected structure
Breaking Change Detection
Identify these breaking changes:
- Removed fields: Field was in old response, missing in new
- Type changes: Field type changed (e.g., string to number)
- New required fields: New field that consumer doesn't expect
- Renamed fields: Field name changed (detected by type similarity)
- Nullability changes: Previously non-null field now nullable
Graceful Degradation
If no consumers found:
- Log warning: "No consumers discovered for {endpoint}"
- Skip contract validation for that endpoint
- Continue with other endpoints
- Report in output:
"contracts_skipped": ["GET /api/users"]
Output Format
json
{
"agent": "contract_validator",
"contracts_checked": 8,
"contracts_valid": 7,
"contracts_broken": 1,
"contracts_skipped": 0,
"findings": [
{
"id": "CV-001",
"severity": "critical",
"endpoint": "GET /api/users/{id}",
"consumer": "frontend/src/components/UserProfile.tsx:45",
"issue_type": "field_renamed",
"title": "Breaking change: field renamed",
"description": "Field 'createdAt' renamed to 'created_at'",
"evidence": {
"consumer_expects": "createdAt",
"api_returns": "created_at",
"consumer_code": "const created = user.createdAt;"
},
"recommendation": "Keep 'createdAt' for backwards compatibility, or update all consumers"
}
],
"confidence": 0.90
}
Severity Guidelines
- Critical: Removed required field, type change, renamed field
- Moderate: New required field, nullability change
- Minor: Added optional field (usually not breaking)
Multiple Consumers
When multiple consumers expect different things:
- Report all consumers with their expectations
- Flag inconsistencies between consumers
- Validate API against union of all expectations
- Let human decide which expectation is correct
Didn't find tool you were looking for?