api-contract-testing

API Contract Testing — Verify Interfaces, Ship Faster

The Problem Contract Testing Solves

Traditional:  Consumer ←→ Provider (full integration required)
              ↑___________full stack deployment needed___________↑
                         ~40 min CI, all teams blocked

Contract:     Consumer ←→ Contract ←→ Provider
              ↑___________mock + contract________↑
                         ~3 min CI, teams unblocked

Contract testing proves that two services can communicate without deploying both or running a full integration environment.

Two Types of Contract Tests

Consumer-Driven Contract (CDC)

Consumer writes: "I expect Provider to respond with {status: 200, body: {id: string}}"
Consumer validates against a MOCK that implements this contract
Consumer publishes contract to a broker (PactFlow, Pact Broker)
Provider pulls contract and verifies: "I can satisfy this contract"

Provider-Side Contract

Provider defines: OpenAPI spec (Swagger/YAML) or GraphQL schema or Proto files
Consumer validates: Generated client code + runtime responses match schema
Tools: Dredd, OpenAPI Validator, Spectral

Tool Landscape

Type	Tool	Best For
CDC (HTTP/JSON)	Pact	REST microservices, consumer teams
CDC (Broker)	PactFlow	Enterprise, shared contracts, versioning
Provider (OpenAPI)	Dredd	Validating API against Swagger/OpenAPI spec
Provider (OpenAPI)	Spectral	Linting + validating YAML/JSON against rulesets
GraphQL	GraphQL Inspector	Schema diffs, breaking change detection
GraphQL	Envelop	Runtime schema validation
Proto/GRPC	grpcurl + buf	Protobuf contract testing
E2E contract	Postman/Newman	Full HTTP contract suites
Multi-format	RestAssured (JVM)	Java REST API testing

---

Pact (Consumer + Provider)

Consumer Test

# tests/consumer/test_order_client.py
import pytest
from pact import Consumer, Provider, Like, Term

@pytest.fixture
def pact():
    consumer = Consumer('OrderFrontend')
    provider = Provider('OrderService')
    return consumer


def test_create_order_returns_201(pact):
    """Consumer: I expect creating an order returns 201 with an order ID."""
    (
        pact.given('a valid cart with items')
        .upon_receiving('a request to create an order')
        .with_request(
            method='POST',
            path='/api/v1/orders',
            headers={'Content-Type': 'application/json', 'Authorization': 'Bearer valid_token'},
            body={
                'cart_id': 'cart-abc-123',
                'items': [
                    {'sku': 'WIDGET-001', 'quantity': 2},
                    {'sku': 'GADGET-002', 'quantity': 1},
                ],
                'shipping_address': {
                    'street': Like('123 Main St'),
                    'city': Term('[A-Za-z\\s]+'),
                    'postal_code': Like('10001'),
                }
            },
        )
        .will_respond_with(
            status=201,
            headers={'Content-Type': 'application/json'},
            body={
                'order_id': Like('ord-xxxxxxxx-xxxx'),
                'status': 'confirmed',
                'total': 149.99,
                'created_at': Term('\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z'),
                'items': [
                    {'sku': 'WIDGET-001', 'quantity': 2, 'price': 49.99},
                    {'sku': 'GADGET-002', 'quantity': 1, 'price': 50.00},
                ],
            },
        )
    )

    with pact:
        result = order_client.create_order(
            cart_id='cart-abc-123',
            items=[{'sku': 'WIDGET-001', 'qty': 2}, {'sku': 'GADGET-002', 'qty': 1}],
            token='valid_token',
        )
        assert result['status'] == 'confirmed'
        assert 'order_id' in result