Skip to content
Skills Library
Programming · Testing

contract-testing

/contract-testing

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.

Repository
agentic-qe ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Original author 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.

How it works

  1. Quick Reference Card
  2. Consumer Contract (Pact)
  3. Provider Verification
  4. Breaking Change Detection
  5. CI/CD Integration
  6. Agent Coordination Hints
  7. Agent CLI & Advanced Patterns
  8. Related Skills
  9. Remember
  10. Gotchas
Original SKILL.md headings · 221 lines, 809 words
SKILL.md preview
---
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
Files in this package (7)
  • SKILL.md 7 KB
  • config.json 1 KB
  • evals/contract-testing.yaml 21 KB
  • references/agent-commands.md 3 KB
  • references/provider-states.md 1 KB
  • schemas/output.json 17 KB
  • scripts/validate-config.json 1 KB

Versions

RepositoryScoreLicence
This page · proffesor-for-testing/agentic-qe100MIT
claude-dev-suite/claude-dev-suite100MIT
sebastiendegodez/skraft-plugin100GPL-3.0
petrkindlmann/qa-skills100MIT
thedaviddias/front-end-checklist100MIT
jacob-balslev/skill-graph100Apache-2.0
Tyler-R-Kendrick/agent-skills95MIT
RobinBeraud/claude-qa-skills90MIT
Amey-Thakur/AI-SKILLS90MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version f0cbb1dd7ae8 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90quality-contract-testing
    Use this skill when setting up contract testing, Pact, consumer-driven contracts, provider contract verification, API compatibility, or integration testing between services. This skill enforces: consumer-driven contracts with Pact, provider-side verification, contract publishing…
  • 100pact
    Guidance for Pact contract testing framework in .NET. USE FOR: consumer-driven contract testing, verifying API compatibility between microservices, preventing breaking API changes, generating and verifying Pact files, provider state management, CI/CD integration with Pact…
  • 100validating-api-contracts
    Validate API contracts using consumer-driven contract testing (Pact, Spring Cloud Contract). Use when performing specialized testing. Trigger with phrases like "validate API contract", "run contract tests", or "check consumer contracts".
  • 100validating-api-contracts
    Validate API contracts using consumer-driven contract testing (Pact, Spring Cloud Contract). Use when performing specialized testing. Trigger with phrases like "validate API contract", "run contract tests", or "check consumer contracts".
  • 90backend-contract-testing
    Use this skill when the user says 'contract testing', 'Pact', 'consumer-driven contracts', 'CDC', 'provider verification', 'pact test', 'pactflow', 'contract test', 'consumer test', 'provider test'. This skill implements consumer-driven contract testing using Pact to ensure…
  • 85wicked-garden-qe-contract-testing-engineer
    API contract testing specialist. Designs and reviews consumer-driven contracts, Pact-style tests, OpenAPI contract verification, schema versioning, and breaking-change detection across service boundaries. Use when: API contract tests, CDC, Pact, OpenAPI verification, schema…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.