Contract Testing with Pact

Ensure API compatibility between services with consumer-driven contracts.

Contract Testing vs Integration Testing

Integration Testing	Contract Testing
Requires all services	Each service tests independently
Slow feedback loop	Fast feedback
Environment-dependent	Environment-independent

Quick Reference

Consumer Test

from pact import Consumer, Provider, Like, EachLike

pact = Consumer("UserDashboard").has_pact_with(
    Provider("UserService"), pact_dir="./pacts"
)

def test_get_user(user_service):
    (
        user_service
        .given("a user with ID user-123 exists")
        .upon_receiving("a request to get user")
        .with_request("GET", "/api/users/user-123")
        .will_respond_with(200, body={
            "id": Like("user-123"),      # Any string
            "email": Like("test@example.com"),
        })
    )

    with user_service:
        client = UserServiceClient(base_url=user_service.uri)
        user = client.get_user("user-123")
        assert user.id == "user-123"

See consumer-tests.md for matchers and patterns.

Provider Verification

from pact import Verifier

def test_provider_honors_pact():
    verifier = Verifier(
        provider="UserService",
        provider_base_url="http://localhost:8000",
    )

    verifier.verify_with_broker(
        broker_url="https://pact-broker.example.com",
        consumer_version_selectors=[{"mainBranch": True}],
        publish_verification_results=True,
    )

See provider-verification.md for state setup.

Pact Broker CI/CD

# Publish consumer pacts
pact-broker publish ./pacts \
  --broker-base-url=$PACT_BROKER_URL \
  --consumer-app-version=$(git rev-parse HEAD)

# Check if safe to deploy
pact-broker can-i-deploy \
  --pacticipant=UserDashboard \
  --version=$(git rev-parse HEAD) \
  --to-environment=production

See pact-broker.md for CI/CD integration.

Key Decisions

Decision	Recommendation
Contract storage	Pact Broker (not git)
Consumer selectors	mainBranch + deployedOrReleased
Provider states	Dedicated test endpoint
Verification timing	After consumer publish
Matchers	Use Like(), EachLike() for flexibility

Anti-Patterns (FORBIDDEN)

# NEVER specify exact values when structure matters
.will_respond_with(200, body={
    "id": "user-123",  # WRONG - too specific
})
# Use: "id": Like("user-123")

# NEVER test provider implementation details
.given("database has 5 rows")  # WRONG
# Use: "multiple users exist"

# NEVER skip provider state setup
.given("some state")  # Must be handled!

# NEVER commit pact files to git
# Use Pact Broker for versioning

Related Skills

integration-testing - API endpoint testing
api-design-framework - REST API design patterns
property-based-testing - Hypothesis integration

References

Consumer Tests - Consumer-side patterns
Provider Verification - Provider state setup
Pact Broker - CI/CD integration

Capability Details

consumer-tests

Keywords: consumer, pact, expectations, mock server Solves: Write consumer-side tests, define expectations, generate pacts

provider-verification

Keywords: provider, verify, states, verification Solves: Verify provider honors contracts, set up provider states

pact-broker

Keywords: broker, can-i-deploy, publish, environments Solves: Share contracts, check deployment safety, manage versions

matchers

Keywords: Like, EachLike, Term, matching, flexible Solves: Write flexible expectations, match structure not values

message-contracts

Keywords: async, events, message, MessageConsumer Solves: Test async event contracts, verify event compatibility

contract-testing