API Contract Testing

Also Known As

TL;DR

Explanation

Consumer-driven contract testing (Pact): the consumer defines a contract (the requests it makes and responses it expects), the provider verifies it can fulfil those contracts independently. Unlike integration tests, both sides run independently — no shared environment needed. The Pact Broker stores and shares contracts between teams. Benefits: catches breaking API changes in CI without a shared staging environment, enables independent service deployments, and documents the actual consumer expectations. PHP: pact-foundation/pact-php, pest-pact.

Common Misconception

Why It Matters

Common Mistakes

• Provider-driven contracts — the provider dictates what it sends, not what consumers need.
• Not running contract tests in CI — contracts only help if violations are caught automatically.
• Overly specific contracts — test the fields you use, not the entire response structure.
• No Pact Broker — contracts stored locally cannot be shared between teams.

Avoid When

• A single team owns both consumer and provider and deploys them together — integration tests are simpler.
• The API surface changes so frequently that maintaining contracts costs more than the bugs they prevent.
• Simple internal SDKs where the provider and consumer share the same codebase and test suite.

When To Use

• Services owned by different teams or deployed independently — contract tests catch provider changes before they reach staging.
• Public or partner APIs where breaking changes have downstream cost and manual coordination is slow.
• CI pipelines between microservices to get fast feedback without spinning up the full environment.

Code Examples

// No contract testing — breaking changes discovered in staging:
// Provider renames 'user_email' to 'email' in v2
// Consumer teams never notified
// Integration test catches it... in a 2-hour E2E test run
// Fix: roll back provider deployment, coordinate change
// Cost: 4 hours of engineer time

// Pact consumer test:
$builder->given('user 42 exists')
    ->uponReceiving('a request for user 42')
    ->with(['method' => 'GET', 'path' => '/users/42'])
    ->willRespondWith([
        'status' => 200,
        'body'   => ['id' => 42, 'email' => 'alice@example.com'],
    ]);

// Provider verification runs against actual implementation:
$verifier->verify(); // Fails if provider returns user_email not email
// Caught in provider's CI — before deployment
// Fix: coordinate field rename with consumer teams first

References

• ↗ https://docs.pact.io/

Tags

Related Terms