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.
<default_to_action> When testing API contracts or microservices:
Quick Contract Testing Steps:
Critical Success Factors:
Consumer → Defines Expectations → Contract
↓
Provider → Verifies Contract → Pass/Fail
↓
CI/CD → Blocks 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 |
| Tool | Best For | |------|----------| | Pact | Consumer-driven contracts | | OpenAPI/Swagger | API-first design | | JSON Schema | Schema validation | | GraphQL | Schema-first contracts |
// 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 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();
});
});
// 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)
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
aqe/contract-testing/
├── contracts/* - Current contracts
├── breaking-changes/* - Detected breaking changes
├── versioning/* - Version compatibility matrix
└── verification-results/* - Provider verification history
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'
});
For v3 agent-specific commands (aqe contract ...), GraphQL contracts, event contracts, and Pact Broker integration, see references/agent-commands.md.
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.
Category:other
Tags:contract, pact, consumer-driven, api, microservices, schema-validation