contract-testing

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)

// 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();
  });
});