23Contract Testing (Pact)

23.1 The problem

Microservice A calls Microservice B. Traditional ways to test the integration:

• End-to-end tests — slow, flaky, expensive to maintain
• Shared mocks — drift from reality without anyone noticing
• Schema check (OpenAPI) — catches shape changes but not semantic mismatch

Contract testing: the consumer declares "I send X, expect Y back"; the producer verifies it can satisfy that contract. Producer changes that break the contract fail BEFORE deploy.

23.2 How Pact works

23.3 Consumer test (Node)

// users-client.consumer.spec.ts
import { PactV3, MatchersV3 } from '@pact-foundation/pact';
const { like, eachLike, integer, string } = MatchersV3;

const provider = new PactV3({ consumer: 'web', provider: 'users-api' });

test('GET /users/42', async () => {
  provider
    .given('user 42 exists')
    .uponReceiving('a request for user 42')
    .withRequest({ method: 'GET', path: '/users/42',
                   headers: { Accept: 'application/json' } })
    .willRespondWith({
      status: 200,
      headers: { 'Content-Type': 'application/json' },
      body: like({
        id: integer(42),
        email: string('alice@test.com'),
        orders: eachLike({ id: string('o_1'), total: integer(99) }),
      }),
    });

  await provider.executeTest(async (mockServer) => {
    const client = new UsersClient(mockServer.url);
    const user = await client.getUser(42);
    expect(user.email).toBe('alice@test.com');
  });
});

Result: a JSON pact file in pacts/web-users-api.json describing the interaction.

23.4 Publishing to the broker

npm i -D @pact-foundation/pact-node
pact-broker publish ./pacts \
  --consumer-app-version=$GIT_SHA \
  --branch=$GIT_BRANCH \
  --broker-base-url=https://pact-broker.acme.com

23.5 Provider verification (Java)

@Provider("users-api")
@PactBroker(url = "https://pact-broker.acme.com")
public class UsersApiPactTest {
  @LocalServerPort int port;

  @BeforeEach
  void before(PactVerificationContext ctx) {
    ctx.setTarget(new HttpTestTarget("localhost", port));
  }

  @State("user 42 exists")
  void userExists() {
    /* seed DB so the request will succeed */
    userRepo.save(new User(42, "alice@test.com"));
  }

  @TestTemplate
  @ExtendWith(PactVerificationInvocationContextProvider.class)
  void pactVerificationTestTemplate(PactVerificationContext context) {
    context.verifyInteraction();
  }
}

23.6 Pact Broker

Central service for pact storage and orchestration. Key features:

• Store every pact + version
• Webhooks: trigger provider verification when a new pact is published
• can-i-deploy — pre-deploy check: "can consumer X version Y safely deploy against current provider Y?" Fails if no successful verification exists.
• Network graph visualisation across all services

# Gate deploy
pact-broker can-i-deploy --pacticipant web --version $GIT_SHA --to-environment production

23.7 Matchers (the magic)

You don't pin exact values — you specify shapes. Producer can return different ACTUAL values; only the shape must match.

23.8 Contract vs Schema vs E2E