Contract Testing with Pact

In microservices, services communicate via APIs, and integration failures often happen due to mismatched expectations. Contract testing ensures that both consumer and provider agree on API behavior without requiring full integration setups. Pact is a leading tool for this.

What Is Pact?

Pact is a consumer-driven contract testing tool:

Consumers define their expectations (contracts) of the provider API.
Providers verify that they honor these expectations.
Supports REST APIs and message-based/event-driven services.

Benefits:

Detect integration issues early
Reduce dependency on full end-to-end tests
Improve confidence in service evolution
Enables safe deployments across teams

Core Concepts

Concept	Description
Consumer	The service calling an API (e.g., frontend or payment service)
Provider	The service exposing an API (e.g., order service)
Pact File	JSON file capturing consumer expectations
Pact Broker	Central repository to share and manage contracts
Interaction	A single request-response expectation between consumer and provider

How Pact Works

Consumer writes a contract specifying expected requests and responses.
Consumer tests → generates a Pact file.
Provider verifies → reads the Pact file and tests its API against it.

Consumer Service → Pact Contract → Provider Service Verification

Pact files can be stored locally or in a Pact Broker for multi-team collaboration.

Setting Up Pact in Spring Boot

Pact helps microservices ensure API contracts are honored between consumers and providers, avoiding integration failures.

a) Add Dependencies (Maven)

Include Pact consumer and provider JUnit 5 libraries to write and verify contracts in Spring Boot.

<dependency>
    <groupId>au.com.dius.pact.consumer</groupId>
    <artifactId>junit5</artifactId>
    <version>4.6.8</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>au.com.dius.pact.provider</groupId>
    <artifactId>junit5</artifactId>
    <version>4.6.8</version>
    <scope>test</scope>
</dependency>

b) Consumer Test Example

Consumers define their expectations for provider APIs using Pact contracts and test them locally.

@ExtendWith(PactConsumerTestExt.class)
@PactTestFor(providerName = "OrderService")
class PaymentConsumerPactTest {

    @Pact(consumer = "PaymentService")
    public RequestResponsePact createPact(PactDslWithProvider builder) {
        return builder
            .given("Order 123 exists")
            .uponReceiving("Request order details")
            .path("/orders/123")
            .method("GET")
            .willRespondWith()
            .status(200)
            .body("{\\"orderId\\":123,\\"status\\":\\"PAID\\"}")
            .toPact();
    }

    @Test
    void testOrderDetails(MockServer mockServer) {
        RestTemplate restTemplate = new RestTemplate();
        String response = restTemplate.getForObject(mockServer.getUrl() + "/orders/123", String.class);
        assertTrue(response.contains("\\"status\\":\\"PAID\\""));
    }
}

@Pact → defines expected request and response.
MockServer → simulates provider behavior for testing.

c) Contract Verification (Provider-Side)

Contract Verification is the process where the provider validates its API against consumer expectations.

Ensures all interactions defined in the Pact file are honored.
Can pull contracts from local files or Pact Broker.
Usually automated in CI/CD pipelines to prevent breaking changes before deployment.
Covers both positive (expected requests succeed) and negative (invalid requests fail) scenarios.
Applies to both REST and message/event-driven services.

Example: REST API Verification

@Provider("OrderService")
@PactBroker(host = "localhost", port = "9292") // optional
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
class OrderProviderContractVerificationTest {

    @TestTemplate
    @ExtendWith(PactVerificationInvocationContextProvider.class)
    void verifyContract(PactVerificationContext context) {
        context.verifyInteraction(); // Verifies provider honors consumer contract
    }

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

Example: Message/Event Contract Verification

@Provider("InventoryService")
@PactBroker(host = "localhost", port = "9292")
@SpringBootTest
class InventoryProviderMessageVerification {

    @TestTemplate
    @ExtendWith(PactVerificationInvocationContextProvider.class)
    void verifyMessageContract(PactVerificationContext context) {
        context.verifyInteraction(); // Verifies message contract
    }
}

Using Pact Broker

Pact Broker centralizes and manages API contracts, making it easy for teams to share, version, and verify contracts across services.

Stores contracts for multiple consumers and providers.
Integrates with CI/CD pipelines for automated contract verification.
Supports multiple environments (dev, staging, prod) to ensure safe deployments.

Best Practices

Let consumers define contracts (Consumer-Driven Contracts)
Use Pact Broker or Git for versioning contracts
Integrate provider verification in CI/CD pipelines
Use mock servers for consumer testing without live providers
Include only relevant interactions in contracts
Combine with integration tests for comprehensive coverage
Test positive and negative scenarios

Advantages of Using Pact

Detect breaking API changes before deployment
Decouples testing from live environments
Works for HTTP, messaging, and event-driven contracts
Integrates with CI/CD pipelines
Encourages collaboration between teams
Reduces flaky integration tests

Real-World Example

Scenario: PaymentService → OrderService

Consumer (PaymentService) defines expected GET /orders/{id} response
Pact generates a contract file → stored in Pact Broker
Provider (OrderService) verifies it implements the contract
Both services guarantee API compatibility across teams

Flow:

Consumer → Pact Contract → Pact Broker → Provider Verification → Deployment

Benefits:

Early detection of integration errors
Decoupled testing (no need for full E2E environment)
Encourages collaboration between teams
Supports multiple versions and environments
Reduces flaky integration tests

Conclusion

Pact-based contract testing ensures that microservices evolve independently without breaking consumers. It complements unit and integration testing, improves reliability, and integrates seamlessly into CI/CD pipelines, making it essential for modern microservice ecosystems.