Contracts in an external repository 2.5.3

when a client wants a beer and has e.g. name "marcin" and age 22 - the answer that we’ll respond with THERE YOU GO

when a client is an underage and wants a beer and has e.g. name "marcin" and age 17 - the answer that we’ll respond with GET LOST

when a verification message with eligible field equal to true was sent to the verifications channel then we increment the eligible counter

when a verification message with eligible field equal to false was sent to the verifications channel then we increment the notEligible counter

Under the rest folder create a file shouldGrantABeerIfOldEnough.groovy

Call the Contract.make method to start defining the contract

org.springframework.cloud.contract.spec.Contract.make {

}

You can call description() method to provide some meaningful description. TIP: You can use the Groovy multiline String """ """ to have all special characters escaped. Every new line in the String will be converted into a new line character. Example

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
}

Now call the request { } and response { } methods

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
    request {
    }
    response {
    }
}

Let’s assume that we’re interested in sending a POST method. Call method POST() or method "POST". TIP: In Groovy you don’t need to provide parentheses (in most cases). You can write either method POST() or method(POST()). In both cases it’s the same syntax

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
    request {
        method POST()
    }
    response {
    }
}

Now we need to provide some URL. Let it be /check. Let’s write url "/check"

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
    request {
        method POST()
        url "/check"
    }
    response {
    }
}

Now time to define some body. We’ll leverage some of the Groovy power over here so if you’re lost you can always check the Groovy JSON documentation. Let’s call the body() method with brackets.

In Groovy you can use the map notation in such a way [key: "value", secondKey: 2]. In the same way we can describe the body of a JSON. So in order to send a JSON looking like this { "age": 22, "name": "marcin" } we can create a map notation of [age:22, name:"marcin"]. The body method accepts a map and in Groovy if a method accepts a map then the [] brackets can be omited. So you can either write body([age:22, name:"marcin"]) or body(age:22, name:"marcin"). The latter one contains less boilerplate code so let’s write that one

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
    request {
        method POST()
        url "/check"
        body(
            age: 22, name: "marcin"
            )
    }
    response {
    }
}

Now time for the headers…​ Call the headers { } method

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
    request {
        method POST()
        url "/check"
        body(
            age: 22, name: "marcin"
            )
        headers {

        }
    }
    response {
    }
}

Inside that method let’s define that we want to use the Content-Type: "application/json header. Just call contentType(applicationJson()) methods

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
    request {
        method POST()
        url "/check"
        body(
            age: 22, name: "marcin"
            )
        headers {
            contentType(applicationJson())
        }
    }
    response {
    }
}

Congratulations! You defined how you would like the contract for the request to look like! Time for the response

In the response block we would like to define that that the status of our response will be 200. Just call status 200

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
    request {
        method POST()
        url "/check"
        body(
            age: 22, name: "marcin"
            )
        headers {
            contentType(applicationJson())
        }
    }
    response {
        status 200
    }
}

We’d like our response to have some body. As you could have assumed there’s a body method here too. We’ll now use another way of defining bodies (which is the less preferred option in Spring Cloud Contract but still can be useful) - using String

We’re assuming that we would like to send back a field called status that will return OK when the person can get the beer

Call the body(""" { "status" : "OK" } """). That way you’re defining how the response body will look like by providing the exact JSON value

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
    request {
        method POST()
        url "/check"
        body(
            age: 22, name: "marcin"
            )
        headers {
            contentType(applicationJson())
        }
    }
    response {
        status 200
        body("""
            { "status" : "OK" }
        """)
    }
}

Last thing to add are the response headers. We’re doing exactly the same thing as we have done previously for the request. headers { contentType(applicationJson()) }.

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
    request {
        method POST()
        url "/check"
        body(
            age: 22, name: "marcin"
            )
        headers {
            contentType(applicationJson())
        }
    }
    response {
        status 200
        body("""
            { "status" : "OK" }
        """)
        headers {
            contentType(applicationJson())
        }
    }
}

Congratulations! You have created your first contract!

Call the org.springframework.cloud.contract.spec.Contract.make { } method to start defining the contract

org.springframework.cloud.contract.spec.Contract.make {
}

You can call description() method to provide some meaningful description. TIP: You can use the Groovy multiline String """ """ to have all special characters escaped. Every new line in the String will be converted into a new line character

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
}

HTTP communication is synchronous - you send a request and you get a response. With messaging the situation is different - a consumer suddenly might get a message. In the consumer tests the consumer needs a mean to trigger that message. That hook is called a label in Spring Cloud Contract. Let’s call our label accepted_verification. To define it in the contract just call the label method like this label 'accepted_verification'

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
    label "accepted_verification"
}

Next we define the message that we would like to receive. So from the producer’s perspective that’s an outputMessage. You can call that message in the Groovy DSL outputMessage { }

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
    label "accepted_verification"
    outputMessage {

    }
}

Inside that method we need to define where and what we want to send. Let’s start with the first. You can call the sentTo method and provide the destination. According to the requirements we want to send the message to the verifications channel. Let’s define that in the contract by calling sentTo 'verifications'

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
    label "accepted_verification"
    outputMessage {
        sentTo "verifications"
    }
}

As for the body we just can call body(eligible: true). That way we’ll send a JSON body via messaging

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
    label "accepted_verification"
    outputMessage {
        sentTo "verifications"
        body(eligible: true)
    }
}

We can also set headers on the message. Let’s call headers { } method and inside the closure we can set an explicit header. In case of messaging with Spring Cloud Stream, a header that describes the content type of the payload is called contentType. So we need to set it like this header("contentType", applicationJsonUtf8()).

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
    label "accepted_verification"
    outputMessage {
        sentTo "verifications"
        body(eligible: true)
        headers {
            header("contentType", applicationJsonUtf8())
        }
    }
}

Sets the jar name to the beer-api-producer-external (that’s how the producer’s called).

Disables test generation (we want only to generate stubs).

Adds the Spring Cloud Contract plugin (as you can see, there is no configuration related to base classes).

Sets excludeBuildFolders, which is pretty descriptive. When generating stubs, target and build folders are generated, and we don’t want them in the output jar.

Sets contractsDirectory. By default, Spring Cloud Contract searches under the src/test/resources/contracts folder. In this case, we have the contracts under / (from the point of view of the pom.xml file).

it will download the stub JARs from Maven local (stubsMode = StubRunnerProperties.StubsMode.LOCAL)

it will search for a JAR with coordinates com.example:beer-api-producer-external with latest version (+) and stubs classifier. Once it’s found the fake HTTP server stub will be started at port 8090

In the logs you will see information about downloading, unpacking and starting stubs (see the logs)

What happened is that we could interact with real API without writing a single line of production code

The same will happen if you leave the name but change the age to some other value (e.g. 28). Our stubs at the moment are very strict. We’ll try to fix that in a second

Just remove the name field from the request body.

Spring Cloud Contract allows you to provide dynamic values for parts of body, urls, headers etc. This is especially useful when working with dates, database ids, UUIDs etc.

Let’s open the shouldGrantABeerIfOldEnough.groovy and go to the request body age element

Instead of 22 write $(regex('[2-9][0-9]')). Now let’s analyze what this is.

Repeat the same process for the shouldRejectABeerIfTooYoung.groovy contract but change the regular expression to [0-1][0-9]

Run the building with test skipping and check the output of stubs. You’ll see that the generated mappings have changed from equality check in JSON Path to regular expression check

Go back to the consumer code and run the BeerControlerTest again. This time it should pass. You can also change the values of age to e.g. 45 for the positive case and 11 for the negative on.

there are 2 test methods with empty bodies

in both cases we need to trigger a message that will get sent to a destination at which our listener class is awaiting messages

we’re missing the triggering part - but we’ll add it in a second

We’re using the Spring Cloud Stream’s abstraction of a queue / topic which is called a channel.

There are 2 channels that come out od the box with SC-Stream. These are input and output. Those channels can be found in 2 interfaces - Sink and Source. Sink contains the input channel which is used for listening for messages and Source contains the output channel which is used to send messages. In the listener class you can see that we use the Sink one cause we’re waiting for a message to be received.

We have to configure the destination, so the actual name of a queue / topic on which we will be listening. To do that you have to set in the src/main/resources/application.yml the property spring.cloud.stream.bindings.input-in-0.destination: verifications. That means that the we’ll use the input channel (so the channel in the Sink interface) to listen to messages coming from a destination called verifications.

Now that we have configured Spring Cloud Stream let’s write the missing feature. If the eligible flag in the incoming message is true - increase the eligibleCounter value. Otherwise increment the other notEligibleCounter one. (Show solution)

We need to use Spring Cloud Contract Stub Runner so that it downloads the stubs. Just add the @AutoConfigureStubRunner(stubsMode = StubRunnerProperties.StubsMode.LOCAL, ids = "com.example:beer-api-producer-external") to download the latest stubs of com.example:beer-api-producer-external, with classifier stubs and if the JAR contains any HTTP stubs then register them at a random port.

Now we need a solution to trigger the message. To do that we need to autowire a StubTrigger interface. Just add @Autowired StubTrigger stubTrigger field to your test

In the contract on the producer side we’ve described 2 labels. accepted_verification and rejected_verification. You can use the StubTrigger#trigger method to trigger a message with a given label. For example if you call stubTrigger.trigger("accepted_verification") you’ll trigger a message that got described with the accepted_verification label.

Now add the missing StubTrigger#tigger method in the test bodies. (Show solution)

Run the tests and they should pass!

You can change the destination name in src/main/resources/application.yml to foo and rerun the tests - you’ll see that they’ll start failing. That’s because you’re listening to messages at destination foo whereas the message is sent to verifications

You can also play around with the Verification payload class. If you change the field name from eligible to foo an rerun the tests - the tests will fail. If you change the type from boolean to Integer (and change the production code too) then the tests will fail due to serialization problems

In case of messaging there has to be some trigger that will result in producing an output message

Spring Cloud Contract accepts 3 situations

In our situation we’ll have a method produce an output. It’s enough to pass the input {} method and then the triggeredBy method. The triggeredBy method requires a String with a method execution. So if in the base class we expect to have a method called triggerSomeMessage() that would trigger a message for tests, then we would write input { triggeredBy("triggerSomeMessage()") } to make this happen. Example:

org.springframework.cloud.contract.spec.Contract.make {
    description("""
        some interesting description
    """)
    label "accepted_verification"
    input {
        triggeredBy("triggerSomeMessage()")
    }
    outputMessage {
        sentTo "verifications"
        body(eligible: true)
        headers {
            header("contentType", applicationJsonUtf8())
        }
    }
}

For this workshop for the shouldSendAcceptedVerification.groovy we want to trigger the clientIsOldEnough() method and for shouldSendRejectedVerification.groovy we want to trigger the clientIsTooYoung() method from the base class. (Show solution)

Suddenly some tests should start failing. Those tests are the autogenerated tests created by Spring Cloud Contract

The tests lay under /generated-test-sources/contracts/org/springframework/cloud/contract/verifier/tests/beer in target for Maven or build for Gradle

There will be a test for each folder in which you store your contracts. The name of the test class will be the name of that folder

Each of the contracts will be a single test inside that test class

If you check out the generated tests you’ll notice that the dynamic parts of the request part of the contract got converted to a concrete value. Any dynamic bits on the response side would be converted into matchers.

First let’s write the missing implementation in ProducerController. The logic to be written is extremely simple - if the personCheckingService.shouldGetBeer(…​) returns true then we should return new Response(BeerCheckStatus.OK). Otherwise new Response(BeerCheckStatus.NOT_OK). (Show solution)

The idea of CDC is NOT TO TEST every single feature. Contract tests are there to see if the API is matched, NOT that the feature is working. That’s why we shouldn’t be accessing databases etc. That means that we will work with mock of the PersonCheckingService. (Show solution)

Let’s annotate the test class with @RunWith(MockitoJUnitRunner.class) to enable Mockito runner.

@RunWith(MockitoJUnitRunner.class)
public abstract class BeerRestBase {
...
}

We’ll want to test the ProducerController so we can create a field @InjectMocks ProducerController producerController. Mockito will inject any mocks for us via the constructor.

    @Mock PersonCheckingService personCheckingService;
    @InjectMocks ProducerController producerController;

    @BeforeEach
    public void setup() {
        given(personCheckingService.shouldGetBeer(argThat(oldEnough()))).willReturn(true);
    }

It won’t compile cause we don’t have the oldEnough() method but don’t worry. So this line stubs the shouldGetBeer method in such a way that if the user is old enough then the method will return true. Let’s now add the oldEnoughMethod()

	private TypeSafeMatcher<PersonToCheck> oldEnough() {
		return new TypeSafeMatcher<PersonToCheck>() {
			@Override protected boolean matchesSafely(PersonToCheck personToCheck) {
				return personToCheck.age >= 20;
			}
			@Override public void describeTo(Description description) {
			}
		};
	}

We’re using the TypeSafeMatcher from Hamcrest to create a matcher for PersonToCheck. In this case if the person to check is older or is 20 then the method shouldGetBeer method will return true.

Now we need to configure RestAssured that is used by Spring Cloud Contract to send requests. In our case we want to profit from MockMvc. In order to set the ProducerController with RestAssured it’s enough to call // https://github.com/spring-cloud/spring-cloud-contract/issues/1428 EncoderConfig encoderConfig = new EncoderConfig().appendDefaultContentCharsetToContentTypeIfUndefined(false); RestAssuredMockMvc.config = new RestAssuredMockMvcConfig().encoderConfig(encoderConfig); RestAssuredMockMvc.standaloneSetup(producerController);

@RunWith(MockitoJUnitRunner.class)
public abstract class BeerRestBase {

    @Mock PersonCheckingService personCheckingService;
    @InjectMocks ProducerController producerController;

    @BeforeEach
    public void setup() {
        given(personCheckingService.shouldGetBeer(argThat(oldEnough()))).willReturn(true);

		// https://github.com/spring-cloud/spring-cloud-contract/issues/1428
		EncoderConfig encoderConfig = new EncoderConfig().appendDefaultContentCharsetToContentTypeIfUndefined(false);
		RestAssuredMockMvc.config = new RestAssuredMockMvcConfig().encoderConfig(encoderConfig);
		RestAssuredMockMvc.standaloneSetup(producerController);
    }

    private TypeSafeMatcher<PersonToCheck> oldEnough() {
        return new TypeSafeMatcher<PersonToCheck>() {
            @Override protected boolean matchesSafely(PersonToCheck personToCheck) {
                return personToCheck.age >= 20;
            }
            @Override public void describeTo(Description description) {
            }
        };
    }
}

With mocks and RestAssured setup - we’re ready to run our HTTP based autogenerated tests