Real-World Contract Testing Patterns — consumer-driven contract testing with Pact for microservices.
Real-World Contract Testing Patterns solves the integration testing problem in microservices architectures. Instead of running end-to-end tests against a full deployed environment, consumer-driven contracts let each service test its dependencies in isolation while maintaining compatibility guarantees.
1# Contract testing flow:
2
31. Consumer writes Pact test
4 → Interaction: POST /auth/login with {email, password}
5 → Expectation: 200 {accessToken: string, user: object}
6
72. Pact runs consumer test against a mock server
8 → Records the interaction as a pact file (JSON)
9
103. Pact publishes to Pact Broker
11 → Other teams can see what you depend on
12
134. Provider runs Pact verifier
14 → Replays each interaction against the real API
15 → Verifies responses match the consumer's expectations
16
175. can-i-deploy check before deployment
18 → Ensures consumer and provider are compatible1npm install --save-dev @pact-foundation/pact1import { PactV3 } from '@pact-foundation/pact';
2import { like, eachLike } from '@pact-foundation/pact/src/dsl/matchers';
3import * as path from 'path';
4
5const provider = new PactV3({
6 consumer: 'web-frontend',
7 provider: 'api-service',
8 dir: path.resolve(process.cwd(), 'pacts'),
9});
10
11test('GET /courses contract', async () => {
12 await provider
13 .given('courses exist')
14 .uponReceiving('a request for courses')
15 .withRequest({ method: 'GET', path: '/courses' })
16 .willRespondWith({
17 status: 200,
18 body: {
19 data: eachLike({ id: like('id'), title: like('title') }),
20 meta: like({ total: 42 }),
21 },
22 })
23 .executeTest(async (mockServer) => {
24 const res = await fetch(`${mockServer.url}/courses`);
25 const body = await res.json();
26 expect(res.status).toBe(200);
27 expect(body.data).toBeInstanceOf(Array);
28 });
29});1import { Verifier } from '@pact-foundation/pact';
2
3test('provider verification', async () => {
4 await new Verifier({
5 providerBaseUrl: `http://localhost:${port}`,
6 pactUrls: ['pacts/web-frontend-api-service.json'],
7 provider: 'api-service',
8 stateHandlers: {
9 'courses exist': async () => {
10 await prisma.course.createMany({ data: testCourseData });
11 },
12 },
13 }).verifyProvider();
14});1# Publish pacts after consumer tests pass:
2npx pact-broker publish pacts/ \
3 --broker-base-url https://pact-broker.example.com \
4 --broker-token $TOKEN \
5 --consumer-app-version $(git rev-parse --short HEAD)
6
7# Check deployment safety:
8npx pact-broker can-i-deploy \
9 --pacticipant web-frontend \
10 --version $(git rev-parse --short HEAD) \
11 --to-environment staging \
12 --broker-base-url https://pact-broker.example.com
13
14# can-i-deploy exits 0 (safe) or 1 (not safe)
15# Add to deploy script before every deployment1import { like, eachLike, term, integer, decimal } from '@pact-foundation/pact/src/dsl/matchers';
2
3// like(): matches the type, not the value
4body: { id: like('any-string-id'), count: like(42) }
5// Verifies: id is a string, count is a number
6
7// eachLike(): array where each item matches the pattern
8body: { data: eachLike({ id: like('id'), price: like(10.0) }) }
9// Verifies: data is an array, each item has id (string) and price (number)
10
11// term(): regex match
12body: { email: term({ generate: '[email protected]', matcher: '^[\\w.-]+@[\\w.-]+\\.[a-z]{2,}$' }) }
13
14// integer(): whole numbers only
15body: { count: integer(5) }
16
17// decimal(): decimal numbers
18body: { price: decimal(79.99) }
19
20// NEVER use exact values in pact matchers:
21// BAD: body: { id: 'cuid-specific-value' } — breaks when ID changes
22// GOOD: body: { id: like('any-id') } — stable across test runsFull Pact implementation with consumer test, provider verification, and Pact Broker integration.
1// Production contract testing patterns and anti-patterns
2
3// ANTI-PATTERN: Testing too much detail
4// BAD: Matching exact response body
5body: {
6 id: 'exact-cuid-123', // breaks when ID changes
7 title: 'TypeScript Mastery', // breaks when title changes
8 description: 'A very long description that breaks if anyone edits it...',
9}
10
11// GOOD: Match types, not values
12body: {
13 id: like('cuid-abc'), // any string
14 title: like('Any Title'), // any string
15 price: like(79.99), // any number
16 data: eachLike({ id: like('id'), title: like('t') }), // array of objects
17}
18
19// ANTI-PATTERN: Consumer testing internal provider behavior
20// Consumers should only test what they actually USE
21// BAD: Consumer tests 50 response fields, uses only 5
22// GOOD: Consumer tests only the 5 fields it renders in the UI
23
24// PATTERN: Consumer test for each UI feature that calls the API
25const CONTRACT_TEST_COVERAGE = {
26 'CourseList component': 'GET /courses - needs id, title, price, rating, thumbnailUrl',
27 'CourseDetail component': 'GET /courses/:id - needs + description, instructor, lessons',
28 'EnrollButton component': 'POST /progress/enroll - needs success status',
29 'LoginForm component': 'POST /auth/login - needs accessToken, user.email',
30};
31
32// PATTERN: Group related interactions in describe blocks
33describe('Course API contract', () => {
34 describe('authenticated user', () => {
35 // interactions requiring auth token
36 });
37 describe('unauthenticated user', () => {
38 // interactions not requiring auth
39 });
40});This implementation demonstrates real-world contract testing patterns with the complete Pact workflow. Consumer tests run against a mock server (no real API needed), recording interactions as pact files. Provider verification replays those interactions against the real NestJS API with state handlers setting up required test data. The Pact Broker stores contracts and the can-i-deploy command checks compatibility before every deployment.
Continue with the next contract testing topic to complete your consumer-driven contract testing implementation.
Your progress is saved in this browser, on this device only.