Estimate project
← All posts

Contract tests for an event-driven system built on Kafka, using Pact

Testing asynchronous, event-driven systems gets easier with contract tests. This article shows you how.

8 min read
KafkaApache KafkaTestingContract testsPactEvent-driven systemsContract Testing

Asynchronous event-driven systems are notoriously hard to test. Contract testing makes the job easier, because it verifies that services communicate correctly. Such tests can be built with Spring Cloud Contract, but this article walks through testing asynchronous communication that goes through Kafka as the message broker with the Pact framework.

I assume you already know the basics of event-driven architecture and have worked with the Kafka broker.

The example uses an order-service and a payment-service. Whenever an order is created, the order-service publishes an OrderCreated event to Kafka. The payment-service consumes that event and starts the payment process.

The OrderCreated event has the following shape:

{
  "eventId": "9c465a8f-bf77-4f3a-b357-d760ced8b26f",
  "occuredAt": "2023-12-02T13:00:00",
  "orderId": "59404950-bc8d-4722-a521-0dee64b680d6",
  "accountId": "5c2c2407-7202-4720-9a45-f0d0f8175ef1",
  "total": 120.8
}

The tests in this tutorial are written in Groovy with Spock, and the build tool is Gradle. The Kafka broker runs in Testcontainers.

Now let’s look at how Pact lets us test this communication.

Writing down the contract

In Pact, the contract expectations live in the consumer’s tests. Just as for HTTP communication, there is a dedicated API for describing message- or event-driven communication. Here the payment-service plays the consumer role, so the contract goes into its tests. The expectations for the OrderCreated event look like this:

new PactMessageBuilder().call {
    serviceConsumer 'payment-service'
    hasPactWith 'order-service'

    expectsToReceive 'OrderCreatedEvent when order is created'
    withContent(contentType: 'application/json') {
        eventId uuid()
        occurredAt datetime()
        orderId uuid()
        accountId uuid()
        total decimal()
    }
}

With the PactMessageBuilder class you describe what a message is expected to look like. The expectations go into a closure passed to the call() method. We start by naming the services taking part in the exchange. The serviceConsumer() builder method sets the consumer name to payment-service, and hasPactWith() states that this service talks to, or has a pact (contract) with, the provider - order-service.

The expectsToRecive() method gives the contract its name. I called it ‘OrderCreatedEvent when order is created’ so that it mirrors the business scenario under test. The name matters, since it is what identifies the contract in the PactBroker, and the producer has to refer to it as well, as I will show later. Lastly, withContent() describes the event body. I listed every field of the OrderCreated event body with the uuid(), datetime(), and decimal() matchers.

And that’s it - the contract between order-service and payment-service is in place. Next, let’s write a test that checks whether the payment-service handles this event properly.

Consumer-side test

To check that the payment-service consumes and processes the OrderCreated event properly, we have to imitate the provider sending this event to the broker. You can do this in several ways; I went with a real Kafka broker running in Testcontainers.

@Shared
static KafkaContainer kafka = new KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:latest"))

@DynamicPropertySource
static void kafkaProperties(DynamicPropertyRegistry registry) {
    kafka.start()
    registry.add("spring.kafka.bootstrap-servers", () -> kafka.getBootstrapServers())
}

In the test, the event is produced with Spring’s KafkaTemplate. The then section checks that consuming the event triggered the expected business behaviour - here, that the service created a payment and processed it.

def "should initiate payment on OrderCreatedEvent"() {
    given:
    def eventFlow = new PactMessageBuilder().call {
        serviceConsumer 'payment-service'
        (…) // already explained above
    }

    when:
    eventFlow.run { Message message ->
        kafkaTemplate.send('OrderCreated', message.contentsAsBytes())
    }

    then:
    new PollingConditions().eventually {
        def payments = paymentRepository.getAll()
        assert payments.size() == 1
        assert payments[0].paymentStatus() == FINISHED
    }
}

While the test runs, Pact generates the event, filling it with random values that match the declared field types. The event is then sent to Kafka, where the payment-service picks it up. Eventually it gets processed and a payment is created. That proves the payment-service understands the OrderCreated event and can act on it.

Naturally, implementing and running this test requires the right dependencies. In particular, we need the Pact dependency for Groovy:

testImplementation 'au.com.dius.pact.consumer:groovy:4.4.4'

The diagram below sums up how the test works:

As shown, the contract ends up in the Pact broker, because we want the provider to have access to it. For that, the Pact plugin has to be added and configured in build.gradle:

id "au.com.dius.pact" version "4.3.6"
(…)

pact {
    publish {
        pactBrokerUrl = 'http://localhost:9292/'
    }
}

To publish the contract to the Pact broker, run this command:

./gradlew pactPublish

The Pact broker now lists the contract, but it has not been verified against the provider yet.

When you open the details of the order-service – payment-service integration (via the document icon), you will notice that the contract is identified by the name passed to expectsToReceive() in the contract expectations (the description field in the snippet below).

Next up is the producer’s test.

Producer-side test

At this point the contract is defined and stored in the Pact broker, and we have verified that the consumer handles the described message correctly. What remains is to confirm that the producer honours the contract and emits the right event. To do that, we have to implement a method that returns the event the producer publishes. Once more, there are several options. I chose to run the business logic that actually produces the OrderCreated event, and to receive the message from a Kafka broker running in Testcontainers. The test consumes the message and hands it back to Pact for verification. It might seem overly complex, but this way I know that what gets verified is exactly the message sent to Kafka, with no gap between production and test serialization settings.

Here is how consumption is set up in the test:

@PactBroker(url = "http://localhost:9292")
@Provider("order-service")
@SpringBootTest(webEnvironment = NONE)
@Testcontainers
class ContractVerificationSpec extends Specification {

    @Shared
    private static final KafkaContainer kafka = new KafkaContainer(DockerImageName.parse("confluentinc/cp-kafka:latest"))

    @Shared
    private static final Set<String> consumedEvents = Collections.synchronizedSet(new HashSet<String>())

    @DynamicPropertySource
    static void registerKafkaBootstrapServerProperty(DynamicPropertyRegistry registry) {
        kafka.start()
        registry.add("spring.kafka.bootstrap-servers", () -> kafka.getBootstrapServers())
    }

    @KafkaListener(topics = "OrderCreated")
    void orderCreatedEventListener(ConsumerRecord record) {
        consumedEvents.add((String) record.value())
    }
    ( ... )
}

The class carries several annotations:

  • @PactBroker tells the framework to fetch contracts from Pact Broker
  • @Provider sets the name of the provider service, which is used to look up its contracts in Pact Broker
  • @SpringBootTest builds the ApplicationContext
  • @Testcontainer enables the Kafka container

At the top of the class, I declared a Kafka container with KafkaContainer and a Set that holds the consumed messages. The method marked with @DynamicPropertySource is needed to start the Kafka container and point the spring.kafka.bootstrap-server property at the address the container exposes. Finally, a test consumer for the events is built with the @KafkaListener annotation; it just adds every consumed event to the set. This portion of the test class takes care of reading events from Kafka.

Out of the box, Pact is set up to verify HTTP communication, so we have to switch it to verifying messages. The code below does exactly that by making the target message-based.

@BeforeEach
void setTargetToMessage(PactVerificationContext context) {
    context.setTarget(new MessageTestTarget())
}

Time to write the test itself. Remember how I stressed that the contract name matters? This is where it comes into play. Each contract needs a method that returns the message to be verified, and that method has to be annotated with @PactVerifyProvider, with the contract name as its value parameter (‘OrderCreatedEvent when order is created’ here):

@PactVerifyProvider('OrderCreatedEvent when order is created')
String "should publish OrderCreated event"() {
    orderCreator.createOrder(randomUUID(),randomUUID(), BigDecimal.valueOf(10.5))

    new PollingConditions().eventually {
        assert consumedEvents.stream().findFirst().isPresent()
    }

    return consumedEvents.stream().findFirst().orElse(null)
}

The method runs the order creation logic, which publishes the OrderCreated event behind the scenes, and then waits for the event to show up in the consumedEvents set (that is, until the listener defined earlier has consumed it). The event is returned, and Pact checks whether its structure matches what the contract expects. The verification is kicked off by calling the verifyInteraction() method on the Pact context:

@TestTemplate
@ExtendWith(PactVerificationInvocationContextProvider)
void initInteractionVerification(PactVerificationContext context) {
    context.verifyInteraction()
}

When the order-service build runs, Pact connects to the Pact broker and downloads every contract defined for this service. For each one, it looks for a method annotated with @PactVerifyProvider that carries the matching name. If no such method exists, an error is reported, because every contract must have a test. This guarantees that all scenarios are covered. The picture below sums up the flow of this test:

The service build should push the contract verification results to the Pact broker, where they can be used, for example, by the can-i-deploy tool.

Wrap-up

This tutorial showed how the Pact framework can test asynchronous, event-based communication between services. In the consumer’s test (payment-service) we described the contract expectations using the dedicated DLS. We then wrote a test that checks whether the consumer handles the event properly and runs the expected business logic in response. After that, the contract was published to Pact Broker, which made it possible to write the producer’s tests. Those confirm that the producer emits events that satisfy the contract.

I hope that you now understand contract testing well and feel ready to introduce such tests in your own project.

Best of luck!