How Contract Testing with Pact Prevents API Breakages in Microservices

Problem Root

In a microservice architecture, a change such as renaming the quantity field to availableQuantity in an inventory service can pass all unit tests and code reviews, yet cause the dependent order service to fail in production because the contract between services is broken.

Contract Testing Core Principle

A contract is a mutual agreement: the consumer (e.g., order service) declares the expected request and response format, while the provider (e.g., inventory service) promises to honor that format. Contract tests verify both sides—consumer tests ensure the client can handle the expected response, and provider tests confirm the service actually returns data that matches the contract.

Pact Framework Practical Guide

Pact is a popular contract‑testing library for Java microservices. It separates tests into consumer and provider parts, automatically generating a JSON pact file that describes the interaction.

Consumer Test Implementation

@ExtendWith(PactConsumerTestExt.class)
public class InventoryServiceContractTest {
    @Pact(consumer = "order-service", provider = "inventory-service")
    public RequestResponsePact checkInventoryPact(PactDslWithProvider builder) {
        return builder
                .given("item SKU-12345 exists with stock")
                .uponReceiving("a request for inventory")
                .path("/singleTest/FunTester")
                .method("GET")
                .willRespondWith()
                .status(200)
                .headers(Map.of("Content-Type", "application/json"))
                .body(new PactDslJsonBody()
                        .stringType("sku", "SKU-12345")
                        .integerType("quantity", 42)
                        .integerType("reserved", 5))
                .toPact();
    }

    @Test
    @PactTestFor(pactMethod = "checkInventoryPact")
    void testInventoryCheck(MockServer mockServer) {
        InventoryClient client = new InventoryClient(mockServer.getUrl());
        InventoryItem item = client.checkInventory("SKU-12345");
        assertThat(item.getSku()).isEqualTo("SKU-12345");
        assertThat(item.getQuantity()).isGreaterThan(0);
    }
}

The test spins up a mock server, defines the expected GET request and JSON response, and generates a pact file such as order-service-inventory-service.json.

Provider Test Implementation

@Provider("inventory-service")
@PactBroker(url = "https://pact-broker.example.com")
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class InventoryServiceProviderTest {
    @LocalServerPort
    private int port;

    @Autowired
    private InventoryRepository repository;

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

    @State("item SKU-12345 exists with stock")
    void itemExists() {
        repository.save(new InventoryItem("SKU-12345", 42, 5));
    }

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

The provider test launches the real Spring Boot application, replays the interaction from the pact file, and fails if the response deviates from the contract.

Pact Broker Ecosystem

The Pact Broker stores all contracts and tracks version compatibility. Consumers publish contracts from CI:

mvn pact:publish \
    -Dpact.broker.url=https://pact-broker.yourcompany.com \
    -Dpact.consumer.version=1.4.2 \
    -Dpact.consumer.tags=main

Providers then pull and verify contracts:

mvn pact:verify \
    -Dpact.broker.url=https://pact-broker.yourcompany.com \
    -Dpact.provider.version=2.1.0

The broker can query compatibility, acting like a traffic‑control system that prevents incompatible changes from reaching production.

Production‑Grade Tips

When removing an API field, use either a coordinated removal (notify all consumers and wait for contract verification) or a gradual deprecation (keep the old field marked as deprecated while adding a new one, and let contract tests validate both until migration completes).

Contract Testing Best Practices

Start with critical interfaces : prioritize high‑risk, core‑business APIs.

Integrate into CI/CD pipelines : automate publishing and verification of contracts.

Centralize contract storage : use a Pact Broker for version tracking.

Standardize API evolution : define clear processes for adding, deprecating, and deleting fields.

Regularly review and prune contracts : avoid technical debt by cleaning outdated contracts.