Contract testing

API Design

Meaning

Contract testing verifies that two services can communicate by checking each side against a shared specification of expected interactions. It addresses the pain point where integration tests require running all services together, slowing CI and making failures hard to localize. You reach for it when a consumer and provider are owned by different teams or deployed independently and you need confidence that breaking API changes are caught early.

Primary Function

API testing

Communicative Purpose

Ensures independent services remain compatible by validating each side against a shared interaction specification rather than full end-to-end execution.

Pattern

define expected request/response interactions → publish contract → consumer verifies mock matches contract → provider verifies real implementation satisfies contract

Função primária

API testing

Propósito comunicativo

Ensures independent services remain compatible by validating each side against a shared interaction specification rather than full end-to-end execution.

Situações de gatilho

Microservices: consumer and provider teams deploy on independent schedules and need to catch breaking API changes before release

Contextos

Microservices architectures, REST/HTTP APIs, event-driven systems, polyglot service ecosystems, CI/CD pipelines with independent deploys

Padrão

define expected request/response interactions → publish contract → consumer verifies mock matches contract → provider verifies real implementation satisfies contract

Colocados típicos

Pact
consumer-driven contracts
provider verification
mock server
schema validation
OpenAPI/Swagger specs
CI pipeline gates
can-i-deploy check

Substituições comuns

End-to-end integration tests (slower
requires full stack running)
schema-only validation (catches structure but not semantic mismatches)
shared client library (couples teams and versions tightly)

Erros comuns

Treating contract tests as a replacement for integration tests — they verify the boundary, not business workflows across services

Similar / contraste

Integration testing: runs the full stack and exercises real I/O paths; contract testing: runs each side in isolation against a shared spec

Interferências

Coming from monolith development: may assume a shared codebase guarantees compatibility — contract testing is needed precisely because services are deployed independently and types alone do not enforce runtime behavior

Família do chunk

consumer-driven contracts
provider verification
mock server
schema validation
Pact broker
can-i-deploy

Nuance

Skip when a single team owns both sides and deploys them together — the overhead of maintaining a separate contract artifact exceeds the benefit

Efeito pragmático

Catches breaking API changes at the service boundary before they reach production, enabling teams to deploy independently without coordinated release windows.

Dica de memória

Like a prenup between two services: each side promises what it will send and accept, and a lawyer (the verifier) checks the promises match before either can move in.

Upgrade path

Consumer-driven contract testing with Pact broker and can-i-deploy gating in CI

Frequência: MediumFormulaicidade: FlexiblePrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term

Examples

# Consumer-side contract definition (Pact-style) from pact import Consumer, Provider pact = Consumer('UserServiceClient').has_pact_with(Provider('UserService')) def test_get_user_by_id(): (pact .given('user 42 exists') .upon_receiving('a request for user 42') .with_request('GET', '/users/42') .will_respond_with(200, body={'id': 42, 'name': 'Alice'})) with pact: result = user_client.fetch(42) assert result.name == 'Alice'

# Provider-side verification against published contracts from pact import Verifier def test_provider_honors_pacts(): verifier = Verifier( provider='UserService', provider_base_url='http://localhost:8080' ) success, logs = verifier.verify_pacts( pact_urls=['./pacts/user_service_client-user_service.json'], provider_states_url='http://localhost:8080/states' ) assert success == 0, logs

# Lightweight schema-based contract check import jsonschema import requests user_contract = { 'type': 'object', 'required': ['id', 'name', 'email'], 'properties': { 'id': {'type': 'integer'}, 'name': {'type': 'string'}, 'email': {'type': 'string', 'format': 'email'} }, 'additionalProperties': False } def test_user_endpoint_matches_contract(): response = requests.get('https://api.example.com/users/42').json() jsonschema.validate(response, user_contract)