DEV Community: mos_

Consumer-Driven Contract Testing with Pact and Java - Part II

mos_ — Wed, 17 Jun 2020 12:00:00 +0000

The previous post explains the principles and motivations behind contract testing. Today we take a look to how write consumer-driven contract tests with pact and Java in a SpringBoot application.

Pact foundation provides junit5 integration for creation and verification of contracts.

Let’s start!

What you need

The Java Pact Testing framework used in this example is the 4.0.0, based on v3 specification.

Furthermore, you should have:

jdk 1.8 or later
maven 3.2+
a bit of testing knowledge in Spring

You can find all the presented code on github.

The example

The proposed example is similar to the previous one seen in part I: we have a provider service which expose anAPI that given a sentence and a timestamp, it replies an echo response enriched with local timestamp. This API _is consumed_by another service. To summarize:

endpoint POST /api/echo

request body

{
    "timestamp": 1593373353,
    "sentence": "hello!"
}

response body

{
    "phrase": "hello! sent at: 1593373353 worked at: 1593373360"
}

Consumer side

We are driven by Consumer, so then we start working on consumer side: we add the pact maven dependency in consumer pom.xml

<dependency>
    <groupId>au.com.dius</groupId>
    <artifactId>pact-jvm-consumer-junit5</artifactId>
    <version>4.0.10</version>
</dependency>

create a contract

Let’s start creating a junit5 test with PactConsumerTestExt junit extension:


import au.com.dius.pact.consumer.junit5.PactConsumerTestExt;
import org.junit.jupiter.api.extension.ExtendWith;

@ExtendWith(PactConsumerTestExt.class)
class ConsumerContractTest {

in @BeforeEach method we can assert that the mockServer which will serve the contracts is correctly up:

    @BeforeEach
    public void setUp(MockServer mockServer) {
        assertThat(mockServer, is(notNullValue()));
    }

ok, now we can create a contract. A contract can be defined with a method annotated with @Pact that returns a RequestResponsePact and provides as parameter PactDslWithProvider. All methods annotated with @Pact are used toinstrument the mock server through the PactDslWithProvider in this way:

    @Pact(provider = "providerMicroservice", consumer = "consumerMicroservice")
    public RequestResponsePact echoRequest(PactDslWithProvider builder) {

        return builder
                .given("a sentence worked at 1593373360")
                .uponReceiving("an echo request at 1593373353")
                .path(API_ECHO) /* request */
                .method("POST")
                .body(echoRequest) 
                .willRespondWith() /* response */
                .status(200)
                .headers(headers)
                .body(echoResponse)
                .toPact();
    }

The Pact DSL provides a fluent API very similar to Spring mockMvc: Here we are saying that when the mock server receives an echoRequest, it should return 200 and an echoResponse. The given and the uponReceiving method, define the specification in bdd approach and the Pact testing framework, uses the given part to bring the provider into the correct state before executing the interaction defined in the contract.

Matchers: build a response with PactDslJsonBody

in the previous step we created an interaction using two json object(echoRequest and echoResponse). On the provider side, the test verify that the generated response is perfectly equal to the one defined in the contract.

The Pact testing framework provides also a DSL that permits the definition of different matching case in this way:

    @Pact(provider = "providerMicroservice", consumer = "consumerMicroservice")
    public RequestResponsePact echoRequestWithDsl(PactDslWithProvider builder) {

        PactDslJsonBody responseWrittenWithDsl = new PactDslJsonBody()
                .stringType("phrase", "hello! sent at: X worked at: Y") /* match on type */
                .close()
                .asBody();

        return builder
                .given("WITH DSL: a sentence worked at 1593373360")
                .uponReceiving("an echo request at 1593373353")
                .path(API_ECHO)
                .method("POST")
                .body(echoRequest)
                .willRespondWith()
                .status(200)
                .headers(headers)
                .body(responseWrittenWithDsl)
                .toPact();
    }

Here we created a response with PactDslJsonBody DSL that defines a match case based on type instead of value. It’s possible with PactDslJsonBody different match case based on regex or array length.

Verify the contract

Now we can create the real test which verify the contract on the consumer side:

    @Test
    @PactTestFor(pactMethod = "echoRequest")
    @DisplayName("given a sentence with a timestamp, when calling producer microservice, than I receive back an echo sentence with a timestamp")
    void givenASentenceWithATimestampWhenCallingProducerThanReturnAnEchoWithATimestamp(MockServer mockServer) throws IOException {

        BasicHttpEntity bodyRequest = new BasicHttpEntity();
        bodyRequest.setContent(IOUtils.toInputStream(echoRequest, Charset.defaultCharset()));

        expectedResult = new EchoResponse();
        expectedResult.setPhrase("hello! sent at: 1593373353 worked at: 1593373360");

        HttpResponse httpResponse = Request.Post(mockServer.getUrl() + API_ECHO)
                .body(bodyRequest)
                .execute()
                .returnResponse();

        ObjectMapper objectMapper = new ObjectMapper();
        EchoResponse actualResult = objectMapper.readValue(httpResponse.getEntity().getContent(), EchoResponse.class);

        assertEquals(expectedResult, actualResult);
    }

if we run mvn test and we don’t have errors, we will see in ./target/pacts a json file that use the pact formalism for contracts. We use the generated contract in the provider-side.

Provider side

For the provider, we have a different dependency to add in pom.xml:

        <dependency>
            <groupId>au.com.dius</groupId>
            <artifactId>pact-jvm-provider-junit5</artifactId>
            <version>4.0.10</version>
        </dependency>

Verify the contract on provider side

Here is the thing: we need to verify the contract against provider implementation. In the Spring world, it’s sounds like an integration test which verify the web layer. So here the magic:

@ExtendWith(SpringExtension.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT, classes = ProviderApplication.class)
@EnableAutoConfiguration
@AutoConfigureMockMvc
@TestPropertySource(locations = "classpath:application-contract-test.properties")
@Provider("providerMicroservice")
@PactFolder("../consumer/target/pacts")
public class ProviderContractTest {

    @Value("${server.host}")
    private String serverHost;
    @Value("${server.port}")
    private int serverPort;

    @BeforeEach
    void setupTestTarget(PactVerificationContext context) {
        context.setTarget(new HttpTestTarget(serverHost, serverPort, "/"));
    }

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

    @State("a sentence worked at 1593373360")
    public void sentenceWorkedAt1593373360() {
        when(phraseService.echo(1593373353, "hello!"))
                .thenReturn(new Phrase("hello! sent at: 1593373353 worked at: 1593373360"));
    }

}

That’s it. As you can see, we have a @SpringBootTest with a fixed port and a @TestPropertySource that defines it in order to attach the pact context to the application context with host and port info.Obviously there are other ways, like random ports and so on, but the main thing here is to bind both context together.

Another thing here is the @PactFolder annotation that points to contracts generated by the consumer. The Pact Framework search for contracts that belong to the service, and run the verification.

The `@State` annotation

    @State("a sentence worked at 1593373360")
    public void sentenceWorkedAt1593373360() {
        when(phraseService.echo(1593373353, "hello!"))
                .thenReturn(new Phrase("hello! sent at: 1593373353 worked at: 1593373360"));
    }

As previously mentioned, the given statement in the consumer contract, define with a business expression, the state in which the system-under-test, should be during the execution. Following this approach, we define in the provider, a method with @state annotation, that contains the commands necessary for the correct execution. In our case, we mock the business service delegated to execute the eco logic. The framework executes the state method before calling the API defined in the contracts. The real test, in this way, is “reduced” to a simple call:


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

Use a broker

If you have a broker that stores the contracts, you can change the @PactFolder annotation with @PactBroker one and define the following plugin in the pom.xml:

    <build>
        <plugins>
            <plugin>
                <groupId>au.com.dius</groupId>
                <artifactId>pact-jvm-provider-maven</artifactId>
                <version>4.0.0</version>
                <configuration>
                    <pactDirectory>target/pacts</pactDirectory>
                    <pactBrokerUrl>${pact.broker.protocol}://${pact.broker.host}</pactBrokerUrl>
                    <projectVersion>${contracts.version}</projectVersion>
                    <trimSnapshot>true</trimSnapshot>
                </configuration>
            </plugin>
        </plugins>
    </build>

What’s Next

We have covered how to develop and verify a simple contract with java starting from the consumer. We have used the Pact DSL and matchers introduced in v3 spec which is an interesting feature during design & testing. As previously mentioned, you can find a complete working example in this github repo.

In the next posts(I hope), we will see how deploy a broker server to store contracts and how integrate the entire flow witha CI.

The original post can be found here

Consumer-Driven Contract Testing - Part I

mos_ — Wed, 03 Jun 2020 12:00:00 +0000

Introduction

This is the first of a series of blog posts about Contract Testing which cover the minimum set of theory and practice necessary for an effective adoption in your team, from design to code integration.

Contract Testing is a category of testing activity where the data formats and conventions defined by two systems (services) which communicate a business value, is tested against a Mock called “Contract”. A service provides a callable API that can be consumed by another (or many) service which create an interaction between parties that needs to be satisfied during the evolution and developing of services which are now coupled. The interaction between services probably relies on a communication layer which can be slow or not reachable which can affect the test results. For this reason, sometimes the best solution is to verify the interaction with a TestDouble which describe the expectations between the parties.

For the sake of clarity, I have strong opinion.

Context

Let’s suppose that we have a Product Service which has an HTTP method that provides product information in a JSON format upon receiving a product id:

HTTP GET: api/v1/product?id=123

{
  "name": "nexus",
  "type": "smartphone",
  "price": "21.03"
}

The product information are consumed by Customer Service.

Conventions are defined in this way:

Customer Service is the Consumer
Product Service is the Provider

During developing, the Product service can evolve the API in a way that the HTTP response change the data format. For example, the type field from a string value change to object:

{
  "name": "nexus",
  "type": {
    "category": "smartphone",
    "weight": 0.2,
    "color": "blue"
  },
  "price": "21.03"
}

this is defined as a breaking change in which Provider doesn’t respect the defined interaction between Consumer.

In the same way, the Customer service can evolve the request call. For example, instead of call the API with a query parameter id, it can use a field in the header to query the Product Service. Also, this example is a sort of breaking change in which Consumer doesn’t respect the defined interaction between Provider.

Therefore, the interaction between services can be broken in many ways, and the cause can be triggered by both sides which makes necessary some checks to avoid regression during the development.

e2e Testing

The simplest thing to do, is to create an end-to-end test that cover the entire calls flow between Consumer Service and Provider Service.

Despite what I previously said about simplicity, e2e testing give the best confidence on software behaviour but with some problems.They are flaky tests and often fail with false positive furthermore e2e tests are hard do maintain, slow, and it’s necessary to span multiple services in testing environment with terrible slowness caused by deploy flow and environment nightmares. There are some solutions (1, 2) that can provide the right balance between simplicity and maintainability which are a step back e2e tests but often you need a staging environment to execute tests verification or add a level of complexity to remove the environment need, which personally I found with these solutions a tedious process. Moreover, all these solutions are reactive approaches which in the simplest case, doesn’t avoid the integration of code that breaks the services interactions, but they provide a sort of alerting like open a Jira defect or github issue. It’s possible to avoid code integration in case of breaks but imply an overcomplicated CI or some experimental branch.

Mocks

~~Developers~~ (I) usually dislike maintaining things which depend on environments or that needs hours to have a result. If something is faulty and slow, it’s often untrusted and consequently useless. Furthermore, works with other services means deal with other teams which are often too much busy doing new ~~bugs~~ features. So then, to avoid this annoying stuff, it’s necessary to adopt a strategy which imply a level of complexity which usually developers are used to see: Mocks.

Mocks are a type of TestDouble that define a sort of specification based on expectations and, in this particular case, mocks can substitute APIs or clients reducing in this way, parties to set up and run.

Even if the image show deployed services, there are many solutions to load part of an application which doesn’t imply a real execution. however, you can simulate an interaction through a mock or stub based on Contracts. As showed before, we can have two categories of breaking change based on the side that doesn’t maintain expectations and in the same way, we can identify two categories of contracts:

Provider Contracts
Consumer Contracts

Contracts characteristics

A Provider service exposes a set of business functionalities which can be used or not by one or many consumers and ingested in different ways. A change in the provider interface can break interactions with many consumers, but it isn't the same for the consumer. In the same way, a Provider contract cover completely the functionalities exposed by the service with only one definition. On the contrary, a Consumer contract can cover only a set of functionalities that are interesting for the service.

We can say that a provider contract is a closed and complete expression of business functionalities. Instead, consumer contract is an open and incomplete definition of business expectations. When a provider accepts the expectations defined by the consumer contract, confirms that the expectation is a functionality that supported for a period of time.

Consumer-driven Contracts

Ok, so now? Well, If you take a look on internet, ~~you will not find~~ any trace of provider driven contract testing ~~or question about it~~.On the contrary, the web is full of posts about Consumer-driven contract testing.This should be enough for you and me to choose a consumer-driven solution but, as I said at the beginning, the idea of this post is to give the minimum set of knowledge about Contract testing, and to have an answer in case of your colleagues are free mind enough to ask if exists an alternative meanwhile you are exposing why Contract tests are so cool.

In short terms, it’s all about business. Consumer contracts point the finger on current supported business value exposed by the provider. In a consumer-driven approach, the sum of all contracts generated by the consumers and asserted by the provider is closed and complete respect the functionalities requested.

Anyway Consumer-driven Contracts drive the evolution of the services keeping the focus on what really matter with a feedback loop on the changes that will arrive during the life and death of the services which cannot be achievable with a Provider-driven approach which not take in account the feedback from the consumer.

In my experience, it’s easier and natural to think in a Provider-First manner than Consumer-first, and the reason behind this mindset, it might be connected to the fact that a breaking change made by the Provider is more detectable than the one made by the Consumer. In a real world example where your team isn’t the owner of both services, you have to deal with meetings, longer meetings and extravagant, informal, hermetic, long-winded design docs and other mythical beasts. A contract is a formal expression of needs and duties which can be another tool in your pocket that can be used in order to reduce the background noise during the process of evolution of services. Probably you know the sensation of powerlessness when a design doc or swagger definition reaches the mailbox or a shared folder and it’s necessary another meeting or mail tread to have a change in the definition or worse, get an HTTP response status error because someone made a little change in the API which isn’t versioned.

To summarize, Consumer-Driven contracts can give you a process that presents an iterative way of proceeding with a formalised format which can help large organization with services which are owned by different teams that can be in different locations.

Contract Testing with Pact

Pact.io is an implementation of Consumer-driven contract testing which actually support many languages. At the moment of writing this post, pact foundation released v3 specification which cover the following features:

pact format for message queues
regular expression and type matching
specification shared between Ruby, JVM and .Net versions

Furthermore, it’s available a broker which can be used to publish and share contracts between services.

What’s Next

We have covered the minimum set of principles and motivations that are necessary in my opinion to work with contract testing. In the next posts we will take a look to how:

create consumer-driven contracts tests with Pact and Java
setup broker server
integration with Continuous Integration

The original article can be found here

References

Consumer-Driven Contracts: A Service Evolution Pattern

ContractTest

TestDouble

The curious case for the Provider Driven Contract

The Practical Test Pyramid

Patterns for Managing Source COde Branches

Mocks Aren’t Stubs

7 Reasons to Choose Consumer-Driven Contract Tests Over End-to-End Tests

DEV Community: mos_

Consumer-Driven Contract Testing with Pact and Java - Part II

What you need

The example

Consumer side

create a contract

Matchers: build a response with PactDslJsonBody

Verify the contract

Provider side

Verify the contract on provider side

The @State annotation

Use a broker

What’s Next

Consumer-Driven Contract Testing - Part I

Introduction

Context

e2e Testing

Mocks

Contracts characteristics

Consumer-driven Contracts

Contract Testing with Pact

What’s Next

References

The `@State` annotation