You can add a description to your contract. The description is arbitrary text. The following code shows an example:

You can provide a name for your contract. Assume that you provided the following name: should register a user. If you do so, the name of the autogenerated test is validate_should_register_a_user. Also, the name of the stub in a WireMock stub is should_register_a_user.json.

If you want to ignore a contract, you can either set a value of ignored contracts in the plugin configuration or set the ignored property on the contract itself:

Starting with version 1.2.0, you can pass values from files. Assume that you have the following resources in our project.

Further assume that your contract is as follows:

Further assume that the JSON files is as follows:

request.json

response.json

When test or stub generation takes place, the contents of the file is passed to the body of a request or a response. The name of the file needs to be a file with location relative to the folder in which the contract lays.

If you need to pass the contents of a file in a binary form it’s enough for you to use the fileAsBytes method in Groovy DSL or bodyFromFileAsBytes field in YAML.

The following methods can be called in the top-level closure of a contract definition. request and response are mandatory. priority is optional.

You can set the properties inside the body either with the value method or, if you use the Groovy map notation, with $(). The following example shows how to set dynamic properties with the value method:

The following example shows how to set dynamic properties with $():

Both approaches work equally well. stub and client methods are aliases over the consumer method. Subsequent sections take a closer look at what you can do with those values.

You can use regular expressions to write your requests in Contract DSL. Doing so is particularly useful when you want to indicate that a given response should be provided for requests that follow a given pattern. Also, you can use regular expressions when you need to use patterns and not exact values both for your test and your server side tests.

Make sure that regex matches a whole region of a sequence as internally a call to Pattern.matches() is called. For instance, abc pattern doesn’t match aabc string but .abc does. There are several additional known limitations as well.

The following example shows how to use regular expressions to write a request:

You can also provide only one side of the communication with a regular expression. If you do so, then the contract engine automatically provides the generated string that matches the provided regular expression. The following code shows an example:

In the preceding example, the opposite side of the communication has the respective data generated for request and response.

Spring Cloud Contract comes with a series of predefined regular expressions that you can use in your contracts, as shown in the following example:

In your contract, you can use it as shown in the following example:

To make matters even simpler you can use a set of predefined objects that will automatically assume that you want a regular expression to be passed. All of those methods start with any prefix:

and this is an example of how you can reference those methods:

It is possible to provide optional parameters in your contract. However, you can provide optional parameters only for the following:

The following example shows how to provide optional parameters:

By wrapping a part of the body with the optional() method, you create a regular expression that must be present 0 or more times.

If you use Spock for, the following test would be generated from the previous example:

The following stub would also be generated:

You can define a method call that executes on the server side during the test. Such a method can be added to the class defined as "baseClassForTests" in the configuration. The following code shows an example of the contract portion of the test case:

The following code shows the base class portion of the test case:

The type of the object read from the JSON can be one of the following, depending on the JSON path:

In the request part of the contract, you can specify that the body should be taken from a method.

The following example shows how to read an object from JSON:

The preceding example results in calling the hashCode() method in the request body. It should resemble the following code:

The best situation is to provide fixed values, but sometimes you need to reference a request in your response.

If you’re writing contracts using Groovy DSL, you can use the fromRequest() method, which lets you reference a bunch of elements from the HTTP request. You can use the following options:

If you’re using the YAML contract definition you have to use the Handlebars {{{ }}} notation with custom, Spring Cloud Contract functions to achieve this.

Consider the following contract:

Running a JUnit test generation leads to a test that resembles the following example:

As you can see, elements from the request have been properly referenced in the response.

The generated WireMock stub should resemble the following example:

Sending a request such as the one presented in the request part of the contract results in sending the following response body:

WireMock lets you register custom extensions. By default, Spring Cloud Contract registers the transformer, which lets you reference a request from a response. If you want to provide your own extensions, you can register an implementation of the org.springframework.cloud.contract.verifier.dsl.wiremock.WireMockExtensions interface. Since we use the spring.factories extension approach, you can create an entry in META-INF/spring.factories file similar to the following:

The following is an example of a custom extension:

If you work with Pact, the following discussion may seem familiar. Quite a few users are used to having a separation between the body and setting the dynamic parts of a contract.

You can use the bodyMatchers section for two reasons:

Currently, Spring Cloud Contract Verifier supports only JSON Path-based matchers with the following matching possibilities:

Please read the Groovy section for detailed explanation of what the types mean

For YAML the structure of a matcher looks like this

Or if you want to use one of the predefined regular expressions [only_alpha_unicode, number, any_boolean, ip_address, hostname, email, url, uuid, iso_date, iso_date_time, iso_time, iso_8601_with_offset, non_empty, non_blank]:

Below you can find the allowed list of `type`s.

You can also define which type the regular expression corresponds to via the regexType field. Below you can find the allowed list of regular expression types:

Consider the following example:

In the preceding example, you can see the dynamic portions of the contract in the matchers sections. For the request part, you can see that, for all fields but valueWithoutAMatcher, the values of the regular expressions that the stub should contain are explicitly set. For the valueWithoutAMatcher, the verification takes place in the same way as without the use of matchers. In that case, the test performs an equality check.

For the response side in the bodyMatchers section, we define the dynamic parts in a similar manner. The only difference is that the byType matchers are also present. The verifier engine checks four fields to verify whether the response from the test has a value for which the JSON path matches the given field, is of the same type as the one defined in the response body, and passes the following check (based on the method being called):

The resulting test would resemble the following example (note that an and section separates the autogenerated assertions and the assertion from matchers):

The resulting WireMock stub is in the following example:

Consider the following example:

The preceding code leads to creating the following test (the code block shows only the assertion section):

As you can see, the assertion is malformed. Only the first element of the array got asserted. In order to fix this, you should apply the assertion to the whole $.events collection and assert it with the byCommand(…​) method.

One of them is via the WebTestClient mode.

The following example shows how to set up a WebTestClient base class and RestAssured for WebFlux:

Another way is with the EXPLICIT mode in your generated tests to work with WebFlux.

The following example shows how to set up a base class and Rest Assured for Web Flux:

The output message can be triggered by calling a method (such as a Scheduler when a was started and a message was sent), as shown in the following example:

In the previous example case, the output message is sent to output if a method called bookReturnedTriggered is executed. On the message publisher’s side, we generate a test that calls that method to trigger the message. On the consumer side, you can use the some_label to trigger the message.

The output message can be triggered by receiving a message, as shown in the following example:

In the preceding example, the output message is sent to output if a proper message is received on the input destination. On the message publisher’s side, the engine generates a test that sends the input message to the defined destination. On the consumer side, you can either send a message to the input destination or use a label (some_label in the example) to trigger the message.

In HTTP, you have a notion of client/stub and `server/test notation. You can also use those paradigms in messaging. In addition, Spring Cloud Contract Verifier also provides the consumer and producer methods, as presented in the following example (note that you can use either $ or value methods to provide consumer and producer parts):

In the input or outputMessage section you can call assertThat with the name of a method (e.g. assertThatMessageIsOnTheQueue()) that you have defined in the base class or in a static import. Spring Cloud Contract will execute that method in the generated test.

The following examples show three classes that can be reused in the DSLs.

PatternUtils contains functions used by both the consumer and the producer.

ConsumerUtils contains functions used by the consumer.

ProducerUtils contains functions used by the producer.

In order for the plugins and IDE to be able to reference the common JAR classes, you need to pass the dependency to your project.

First, add the common jar dependency as a test dependency. Because your contracts files are available on the test resources path, the common jar classes automatically become visible in your Groovy files. The following examples show how to test the dependency:

Now, you must add the dependency for the plugin to reuse at runtime, as shown in the following example:

You can now reference your classes in your DSL, as shown in the following example:

Spring Cloud Contract includes support for Pact representation of contracts up until v4. Instead of using the Groovy DSL, you can use Pact files. In this section, we present how to add Pact support for your project. Note however that not all functionality is supported. Starting with v3 you can combine multiple matcher for the same element; you can use matchers for the body, headers, request and path; and you can use value generators. Spring Cloud Contract currently only supports multiple matchers that are combined using the AND rule logic. Next to that the request and path matchers are skipped during the conversion. When using a date, time or datetime value generator with a given format, the given format will be skipped and the ISO format will be used.

In order to properly support the Spring Cloud Contract way of doing messaging with Pact you’ll have to provide some additional meta data entries. Below you can find a list of such entries:

Consider following example of a Pact contract, which is a file under the src/test/resources/contracts folder.

The remainder of this section about using Pact refers to the preceding file.

On the producer side, you must add two additional dependencies to your plugin configuration. One is the Spring Cloud Contract Pact support, and the other represents the current Pact version that you use.

When you execute the build of your application, a test will be generated. The generated test might be as follows:

The corresponding generated stub might be as follows:

On the producer side, you must add two additional dependencies to your project dependencies. One is the Spring Cloud Contract Pact support, and the other represents the current Pact version that you use.