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=productionSee 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 versioningRelated Skills
integration-testing- API endpoint testingapi-design-framework- REST API design patternsproperty-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