Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add proffesor-for-testing/agentic-qe --skill contract-testing -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/contract-testing/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/contract-testing/

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.

contract-testing kindlmann contract-testing is a Claude Code skill for setting up Pact contracts between API consumers and providers. It activates for requests about Pact, provider verification, or can-i-deploy. CX Codex +1 1,400installs api-contract-testing aj-geddes api-contract-testing verifies API contracts between consumers and providers without full integration tests. Helps stop breaking schema changes before deploying microservices. CX Codex +1 934installs contract-testing-builder patricio0312rev contract-testing-builder implements API contract testing with Pact, OpenAPI, and JSON Schema to catch breaking changes before deploying services. CX Codex +1 266installs swagger-contract-testing pactflow swagger-contract-testing is a Claude Code plugin for PactFlow contract testing, covering Pact tests, contract publishing, and can-i-deploy checks. ★ 7repo stars swagger-contract-testing-openapi-parser pactflow The swagger-contract-testing-openapi-parser plugin parses OpenAPI for drift test generation. Use it when API contract changes need a test-focused check. ★ 7repo stars suede-parity-contract JasonColapietro suede-parity-contract keeps a single value across every surface of a product: the contract is generated from the reference surface and the rest assert against it in tests. CX Codex +1 ★ 121repo stars agent-browser vercel-labs This Claude Code skill automates browser interaction for tasks like navigating sites, filling forms, and testing web apps. It also supports exploratory QA and Electron app automation. CX Codex +1 1,600,000installs improve-codebase-architecture Matt Pocock The improve-codebase-architecture skill scans a codebase for architectural friction, then builds a visual HTML report with refactoring candidates. Use it before a deeper architecture review. CX Codex +1 1,163,035installs tdd Matt Pocock Guides the red-green TDD loop: ensures tests are written first, keep them at public interfaces, and avoid coupling to implementation details. CX Codex +1 1,141,062installs

From the same set73

The whole set →
sherlock-review sherlock-review is a skill for investigating code changes through evidence and deduction. It helps find bug root causes or verify fixes. CX Codex +1 135installs wms-testing-patterns wms-testing-patterns is a Claude Code skill with patterns for testing inventory accuracy, pick waves, EDI documents, and WMS-ERP integration. CX Codex +1 134installs six-thinking-hats Applies Six Thinking Hats to test strategy, failure analysis, and retrospectives. It separates facts, risks, benefits, ideas, feelings, and next actions. CX Codex +1 131installs a11y-ally The a11y-ally skill audits pages for WCAG issues and suggests fixes based on page context. Use it to review a site or assess video accessibility. CX Codex +1 131installs qe-quality-assessment qe-quality-assessment reviews code quality through complexity, lint, code smells, and test health. Use it for release scoring, quality gates, and deployment checks. CX Codex +1 129installs qe-defect-intelligence qe-defect-intelligence identifies high-risk code before bugs escape by analyzing change frequency, complexity metrics, and past defect patterns. Flags risky PRs and runs root cause analysis on test failures. CX Codex +1 129installs risk-based-testing risk-based-testing directs QA effort to high-risk areas using a 1-5 probability and impact scale, adjusting test depth dynamically. CX Codex +1 128installs n8n-trigger-testing-strategies n8n-trigger-testing-strategies — a skill for testing how n8n workflows get triggered: webhooks, cron schedules, service events, polling. Useful when a workflow fires at the wrong moment or not at all. CX Codex +1 128installs

Project sponsors

Companies that keep this analytics open