contract-testing-with-pact

Contract Testing with Pact

Overview

Contract testing validates that service consumers and providers agree on request/response expectations. Pact implements consumer-driven contracts (CDC) with shareable pact files and provider verification.

Table of Contents

1. What is Contract Testing
2. Consumer-Driven Contracts
3. Pact Fundamentals
4. Pact vs Integration Testing
5. Writing Consumer Tests
6. Provider Verification
7. Pact Broker
8. CI/CD Integration
9. Bi-Directional Contracts
10. Async Messaging
11. GraphQL
12. Language Support
13. Patterns and Anti-Patterns
14. Breaking Change Strategy
15. Monitoring Compliance

What is Contract Testing

Contract tests validate API interactions without full end-to-end setups. They prevent breaking changes by verifying expectations explicitly.

Consumer-Driven Contracts

Consumers define expectations; providers must satisfy them:

• Faster feedback for consumers
• Clear API expectations
• Reduced integration surprises

Pact Fundamentals

• Consumer tests: Generate pact files.
• Provider verification: Validate pact files.
• Pact files: JSON contracts.
• Pact Broker: Store and manage contracts.

Pact vs Integration Testing

• Pact: Validates interface compatibility.
• Integration: Validates full system behavior.

Use both for comprehensive coverage.

Writing Consumer Tests

Define interactions with matchers:

• Exact value
• Type-based matcher
• Regex matcher

Example (TypeScript):

await provider.addInteraction({
  state: 'user exists',
  uponReceiving: 'get user',
  withRequest: { method: 'GET', path: '/users/123' },
  willRespondWith: {
    status: 200,
    body: { id: like(123), name: like('Alice') }
  }
});

Provider Verification

Provider verifies against published contracts:

• Implement state handlers
• Validate response headers/body/status
• Support pending and WIP pacts for safe changes

Pact Broker

Key features:

• Publish and version contracts
• Webhooks on new contracts
• Can-I-Deploy checks for promotion
• Visibility into compatibility

CI/CD Integration

Recommended flow:

1. Consumer tests generate pact
2. Publish pact to broker
3. Provider verifies in CI
4. Use Can-I-Deploy before release

Bi-Directional Contracts

Support for provider-defined expectations plus consumer constraints:

• Useful for GraphQL or schema-first APIs
• Prevents provider drift

Async Messaging

Pact supports message-based contracts:

• Define message payload expectations
• Verify consumer and provider handlers

GraphQL

Contract test schema and query responses:

• Use schema as a contract baseline
• Validate query response shapes

Language Support

SDKs available for:

• JavaScript/TypeScript
• Python
• Java
• Go

Patterns and Anti-Patterns

Good:

• Use flexible matchers
• Keep interactions focused

Avoid:

• Over-specifying exact values
• One contract covering multiple unrelated cases

Breaking Change Strategy

• Use pending pacts for backward-compatible changes.
• Version APIs when breaking changes are required.
• Maintain old contract until consumers migrate.

Monitoring Compliance

Track contract verification in CI and alert on failed verification runs.

Related Skills

• 16-testing/integration-testing
• 09-microservices/service-design
• 03-backend-api/express-rest