contract-testing · proffesor-for-testing — Claude Code skill: what it does, how to install
Guides consumer-driven contract testing for microservices using Pact, catching breaking API changes before deploy.
MIT 130 installs ★ 533 updated 2026-10-25
npx skills add proffesor-for-testing/agentic-qe --skill contract-testing -a claude-codeWhat contract-testing does
This skill implements consumer-driven contract testing across microservices and external APIs. It formalizes consumer expectations, checks provider compliance, and integrates validation gates into deployment workflows.
Behind the scenes, the skill relies on specialized roles like qe-api-contract-validator to compare schemas and flag breaking diffs against semver rules. Breaking modifications like field deletions or type swaps trigger major version recommendations.
Without a preconfigured Pact Broker URL, generated test suites silently skip provider verification.
What it helps with
- detect breaking schema diffs across API revisions
- generate consumer Pact interaction tests
- validate provider compliance before release
- set up can-i-deploy gating in CI/CD pipelines
Example prompts for the agent
- Check openapi-v1.yaml against openapi-v2.yaml for breaking changes and propose semver.
- Generate a Pact consumer test for the OrderService client.
- Add contract verification steps using Pact Broker to our CI/CD pipeline.
How to install contract-testing
1Skills CLI (Vercel)
npx skills add proffesor-for-testing/agentic-qe --skill contract-testing -a claude-code2Manually: put the files in place
~/.claude/skills/contract-testing/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/contract-testing/
1Skills CLI (Vercel)
npx skills add proffesor-for-testing/agentic-qe --skill contract-testing -a codex2Manually: put the files in place
.agents/skills/contract-testing/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add proffesor-for-testing/agentic-qe --skill contract-testing -a cursor2Manually: put the files in place
.cursor/skills/contract-testing/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install proffesor-for-testing/agentic-qe assets/skills/contract-testing2Manually: put the files in place
.github/skills/contract-testing/SKILL.md1Skills CLI (Vercel)
npx skills add proffesor-for-testing/agentic-qe --skill contract-testing -a gemini-cli2Platform CLI
gemini skills install https://github.com/proffesor-for-testing/agentic-qe --path assets/skills/contract-testingManually: put the files in place
.devin/skills/contract-testing/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add proffesor-for-testing/agentic-qe --skill contract-testing -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about contract-testing
How to install contract-testing in Claude Code?
Run npx skills add proffesor-for-testing/agentic-qe --skill contract-testing -a claude-code in your terminal.
What does the contract-testing skill do?
It enforces consumer-driven API contracts, verifies providers against Pact definitions, and catches breaking changes before deployment.
Why is a Pact Broker URL required?
You need to set the broker endpoint beforehand because the agent will otherwise produce test code that skips verification silently.
Source text
SKILL.md · MIT
---
name: contract-testing
description: "Consumer-driven contract testing for microservices using Pact, schema validation, API versioning, and backward compatibility testing. Use when testing API contracts or coordinating distributed teams."
category: testing-methodologies
priority: high
tokenEstimate: 900
agents: [qe-api-contract-validator, qe-test-generator, qe-security-scanner]
implementation_status: optimized
optimization_version: 1.0
last_optimized: 2025-12-02
dependencies: []
quick_reference_card: true
tags: [contract, pact, consumer-driven, api, microservices, schema-validation]
trust_tier: 3
validation:
schema_path: schemas/output.json
validator_path: scripts/validate-config.json
eval_path: evals/contract-testing.yaml
---
# Contract Testing
<default_to_action>
When testing API contracts or microservices:
1. DEFINE consumer expectations (what consumers actually need)
2. VERIFY provider fulfills contracts (Pact verification)
3. DETECT breaking changes before deployment (CI/CD integration)
4. VERSION APIs semantically (breaking = major bump)
5. MAINTAIN backward compatibility for supported versions
**Quick Contract Testing Steps:**
- Consumer: Define expected request/response pairs
- Provider: Verify against all consumer contracts
- CI/CD: Block deploys that break contracts
- Versioning: Document supported versions and deprecation
**Critical Success Factors:**
- Consumers own the contract (they define what they need)
- Provider must pass all consumer contracts before deploy
- Breaking changes require coordination, not surprise
</default_to_action>
## Quick Reference Card
### When to Use
- Microservices communication
- Third-party API integrations
- Distributed team coordination
- Preventing breaking changes
### Consumer-Driven Contract Flow
```
Consumer → Defines Expectations → Contract
↓
Provider → Verifies Contract → Pass/Fail
↓
CI/CD → Blocks Breaking Changes
```
### Breaking vs Non-Breaking Changes
| Change Type | Breaking? | Semver |
|-------------|-----------|--------|
| Remove field | ✅ Yes | Major |
| Rename field | ✅ Yes | Major |
| Change type | ✅ Yes | Major |
| Add optional field | ❌ No | Minor |
| Add new endpoint | ❌ No | Minor |
| Bug fix | ❌ No | Patch |
### Tools
| Tool | Best For |
|------|----------|
| **Pact** | Consumer-driven contracts |
| **OpenAPI/Swagger** | API-first design |
| **JSON Schema** | Schema validation |
| **GraphQL** | Schema-first contracts |
---
## Consumer Contract (Pact)
```javascript
// Consumer defines what it needs
const { Pact } = require('@pact-foundation/pact');
describe('Order API Consumer', () => {
const provider = new Pact({
consumer: 'CheckoutUI',
provider: 'OrderService'
});
beforeAll(() => provider.setup());
afterAll(() => provider.finalize());
it('creates an order', async () => {
await provider.addInteraction({
state: 'products exist',
uponReceiving: 'a create order request',
withRequest: {
method: 'POST',
path: '/orders',
body: { productId: 'abc', quantity: 2 }
},
willRespondWith: {
status: 201,
body: {
orderId: like('order-123'), // Any string matching pattern
total: like(19.99) // Any number
}
}
});
const response = await orderClient.create({ productId: 'abc', quantity: 2 });
expect(response.orderId).toBeDefined();
});
});
```
---
## Provider Verification
```javascript
// Provider verifies it fulfills all consumer contracts
const { Verifier } = require('@pact-foundation/pact');
describe('Order Service Provider', () => {
it('fulfills all consumer contracts', async () => {
await new Verifier({
provider: 'OrderService',
providerBaseUrl: 'http://localhost:3000',
pactUrls: ['./pacts/checkoutui-orderservice.json'],
stateHandlers: {
'products exist': async () => {
await db.products.create({ id: 'abc', price: 9.99 });
}
}
}).verifyProvider();
});
});
```
---
## Breaking Change Detection
```typescript
// Agent detects breaking changes
await Task("Contract Validation", {
currentContract: 'openapi-v2.yaml',
previousContract: 'openapi-v1.yaml',
detectBreaking: true,
calculateSemver: true,
generateMigrationGuide: true
}, "qe-api-contract-validator");
// Output:
// Breaking changes found: 2
// - Removed field: order.discount
// - Type change: order.total (number → string)
// Recommended version: 3.0.0 (major bump)
```
---
## CI/CD Integration
```yaml
name: Contract Tests
on: [push]
jobs:
consumer-tests:
steps:
- run: npm run test:contract
- name: Publish Pacts
run: npx pact-broker publish ./pacts --broker-base-url $PACT_BROKER
provider-verification:
needs: consumer-tests
steps:
- name: Verify Provider
run: npm run verify:contracts
- name: Can I Deploy?
run: npx pact-broker can-i-deploy --pacticipant OrderService --version $VERSION
```
---
## Agent Coordination Hints
### Memory Namespace
```
aqe/contract-testing/
├── contracts/* - Current contracts
├── breaking-changes/* - Detected breaking changes
├── versioning/* - Version compatibility matrix
└── verification-results/* - Provider verification history
```
### Fleet Coordination
```typescript
const contractFleet = await FleetManager.coordinate({
strategy: 'contract-testing',
agents: [
'qe-api-contract-validator', // Validation, breaking detection
'qe-test-generator', // Generate contract tests
'qe-security-scanner' // API security
],
topology: 'sequential'
});
```
---
## Agent CLI & Advanced Patterns
For v3 agent-specific commands (`aqe contract ...`), GraphQL contracts, event contracts, and Pact Broker integration, see [references/agent-commands.md](references/agent-commands.md).
## Related Skills
- [api-testing-patterns](../api-testing-patterns/) - API testing strategies
- [shift-left-testing](../shift-left-testing/) - Early contract validation
- [cicd-pipeline-qe-orchestrator](../cicd-pipeline-qe-orchestrator/) - Pipeline integration
---
## Remember
**Consumers own the contract.** They define what they need; providers must fulfill it. Breaking changes require major version bumps and coordination. CI/CD blocks deploys that break contracts. Use Pact for consumer-driven, OpenAPI for API-first.
**With Agents:** Agents validate contracts, detect breaking changes with semver recommendations, and generate migration guides. Use agents to maintain contract compliance at scale.
## Gotchas
- Pact broker URL must be configured before running — agent will generate tests that silently skip verification without it
- Consumer tests pass locally but fail in CI when provider states aren't set up — always verify both sides
- Adding a required field to a response is a BREAKING change even though provider tests pass — consumer didn't expect it
- Agent may generate contracts from API docs instead of actual consumer usage — contracts must reflect real consumer needs
- GraphQL contract testing requires schema stitching awareness — fragments may reference types from other services
© proffesor-for-testing · MIT · proffesor-for-testing/agentic-qe
Similar skills
All skills for Testing and QA →contract-testing by other authors comes first.