SpringCloud/spring-cloud-static
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
gh-pages
spring-cloud-static/spring-cloud-contract/2.1.0.RC3/spring-cloud-contract.xml
buildmaster bcdd4986ad Sync docs from v2.1.0.RC3 to gh-pages
2018-12-20 21:42:56 +00:00

10352 lines
458 KiB
XML
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<?xml version="1.0" encoding="UTF-8"?>
<?asciidoc-toc maxdepth="3"?>
<?asciidoc-numbered?>
<book xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
<info>
<title>Spring Cloud Contract</title>
<date>2018-12-20</date>
</info>
<preface>
<title></title>
<simpara><emphasis>Documentation Authors: Adam Dudczak, Mathias Düsterhöft, Marcin Grzejszczak, Dennis Kieselhorst, Jakub Kubryński, Karol Lassak,
Olga Maciaszek-Sharma, Mariusz Smykuła, Dave Syer, Jay Bryant</emphasis></simpara>
<simpara>2.1.0.RC3</simpara>
</preface>
<chapter xml:id="_spring_cloud_contract">
<title>Spring Cloud Contract</title>
<simpara>You need confidence when pushing new features to a new application or service in a
distributed system. This project provides support for Consumer Driven Contracts and
service schemas in Spring applications (for both HTTP and message-based interactions),
covering a range of options for writing tests, publishing them as assets, and asserting
that a contract is kept by producers and consumers.</simpara>
</chapter>
<chapter xml:id="_spring_cloud_contract_verifier_introduction">
<title>Spring Cloud Contract Verifier Introduction</title>
<simpara>Spring Cloud Contract Verifier enables Consumer Driven Contract (CDC) development of
JVM-based applications. It moves TDD to the level of software architecture.</simpara>
<simpara>Spring Cloud Contract Verifier ships with <emphasis>Contract Definition Language</emphasis> (CDL). Contract
definitions are used to produce the following resources:</simpara>
<itemizedlist>
<listitem>
<simpara>JSON stub definitions to be used by WireMock when doing integration testing on the
client code (<emphasis>client tests</emphasis>). Test code must still be written by hand, and test data is
produced by Spring Cloud Contract Verifier.</simpara>
</listitem>
<listitem>
<simpara>Messaging routes, if you&#8217;re using a messaging service. We integrate with Spring
Integration, Spring Cloud Stream, Spring AMQP, and Apache Camel. You can also set your
own integrations.</simpara>
</listitem>
<listitem>
<simpara>Acceptance tests (in JUnit 4, JUnit 5 or Spock) are used to verify if server-side implementation
of the API is compliant with the contract (<emphasis>server tests</emphasis>). A full test is generated by
Spring Cloud Contract Verifier.</simpara>
</listitem>
</itemizedlist>
<section xml:id="_history">
<title>History</title>
<simpara>Before becoming Spring Cloud Contract, this project was called <link xl:href="https://github.com/Codearte/accurest">Accurest</link>.
It was created by <link xl:href="https://twitter.com/mgrzejszczak">Marcin Grzejszczak</link> and <link xl:href="https://twitter.com/jkubrynski">Jakub Kubrynski</link>
from (<link xl:href="http://codearte.io">codearte.io</link>.</simpara>
<simpara>The <literal>0.1.0</literal> release took place on 26 Jan 2015 and it became stable with <literal>1.0.0</literal> release on 29 Feb 2016.</simpara>
</section>
<section xml:id="_why_a_contract_verifier">
<title>Why a Contract Verifier?</title>
<simpara>Assume that we have a system consisting of multiple microservices:</simpara>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/master/docs/src/main/asciidoc/images/Deps.png"/>
</imageobject>
<textobject><phrase>Microservices Architecture</phrase></textobject>
</mediaobject>
</informalfigure>
<section xml:id="_testing_issues">
<title>Testing issues</title>
<simpara>If we wanted to test the application in top left corner to determine whether it can
communicate with other services, we could do one of two things:</simpara>
<itemizedlist>
<listitem>
<simpara>Deploy all microservices and perform end-to-end tests.</simpara>
</listitem>
<listitem>
<simpara>Mock other microservices in unit/integration tests.</simpara>
</listitem>
</itemizedlist>
<simpara>Both have their advantages but also a lot of disadvantages.</simpara>
<simpara><emphasis role="strong">Deploy all microservices and perform end to end tests</emphasis></simpara>
<simpara>Advantages:</simpara>
<itemizedlist>
<listitem>
<simpara>Simulates production.</simpara>
</listitem>
<listitem>
<simpara>Tests real communication between services.</simpara>
</listitem>
</itemizedlist>
<simpara>Disadvantages:</simpara>
<itemizedlist>
<listitem>
<simpara>To test one microservice, we have to deploy 6 microservices, a couple of databases,
etc.</simpara>
</listitem>
<listitem>
<simpara>The environment where the tests run is locked for a single suite of tests (nobody else
would be able to run the tests in the meantime).</simpara>
</listitem>
<listitem>
<simpara>They take a long time to run.</simpara>
</listitem>
<listitem>
<simpara>The feedback comes very late in the process.</simpara>
</listitem>
<listitem>
<simpara>They are extremely hard to debug.</simpara>
</listitem>
</itemizedlist>
<simpara><emphasis role="strong">Mock other microservices in unit/integration tests</emphasis></simpara>
<simpara>Advantages:</simpara>
<itemizedlist>
<listitem>
<simpara>They provide very fast feedback.</simpara>
</listitem>
<listitem>
<simpara>They have no infrastructure requirements.</simpara>
</listitem>
</itemizedlist>
<simpara>Disadvantages:</simpara>
<itemizedlist>
<listitem>
<simpara>The implementor of the service creates stubs that might have nothing to do with
reality.</simpara>
</listitem>
<listitem>
<simpara>You can go to production with passing tests and failing production.</simpara>
</listitem>
</itemizedlist>
<simpara>To solve the aforementioned issues, Spring Cloud Contract Verifier with Stub Runner was
created. The main idea is to give you very fast feedback, without the need to set up the
whole world of microservices. If you work on stubs, then the only applications you need
are those that your application directly uses.</simpara>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/master/docs/src/main/asciidoc/images/Stubs2.png"/>
</imageobject>
<textobject><phrase>Stubbed Services</phrase></textobject>
</mediaobject>
</informalfigure>
<simpara>Spring Cloud Contract Verifier gives you the certainty that the stubs that you use were
created by the service that you&#8217;re calling. Also, if you can use them, it means that they
were tested against the producer&#8217;s side. In short, you can trust those stubs.</simpara>
</section>
</section>
<section xml:id="_purposes">
<title>Purposes</title>
<simpara>The main purposes of Spring Cloud Contract Verifier with Stub Runner are:</simpara>
<itemizedlist>
<listitem>
<simpara>To ensure that WireMock/Messaging stubs (used when developing the client) do exactly
what the actual server-side implementation does.</simpara>
</listitem>
<listitem>
<simpara>To promote ATDD method and Microservices architectural style.</simpara>
</listitem>
<listitem>
<simpara>To provide a way to publish changes in contracts that are immediately visible on both
sides.</simpara>
</listitem>
<listitem>
<simpara>To generate boilerplate test code to be used on the server side.</simpara>
</listitem>
</itemizedlist>
<important>
<simpara>Spring Cloud Contract Verifier&#8217;s purpose is NOT to start writing business
features in the contracts. Assume that we have a business use case of fraud check. If a
user can be a fraud for 100 different reasons, we would assume that you would create 2
contracts, one for the positive case and one for the negative case. Contract tests are
used to test contracts between applications and not to simulate full behavior.</simpara>
</important>
</section>
<section xml:id="_how_it_works">
<title>How It Works</title>
<simpara>This section explores how Spring Cloud Contract Verifier with Stub Runner works.</simpara>
<section xml:id="spring-cloud-contract-verifier-intro-three-second-tour">
<title>A Three-second Tour</title>
<simpara>This very brief tour walks through using Spring Cloud Contract:</simpara>
<itemizedlist>
<listitem>
<simpara><xref linkend="spring-cloud-contract-verifier-intro-three-second-tour-producer"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="spring-cloud-contract-verifier-intro-three-second-tour-consumer"/></simpara>
</listitem>
</itemizedlist>
<simpara>You can find a somewhat longer tour
<link linkend="spring-cloud-contract-verifier-intro-three-minute-tour">here</link>.</simpara>
<section xml:id="spring-cloud-contract-verifier-intro-three-second-tour-producer">
<title>On the Producer Side</title>
<simpara>To start working with Spring Cloud Contract, add files with <literal>REST/</literal> messaging contracts
expressed in either Groovy DSL or YAML to the contracts directory, which is set by the
<literal>contractsDslDir</literal> property. By default, it is <literal>$rootDir/src/test/resources/contracts</literal>.</simpara>
<simpara>Then add the Spring Cloud Contract Verifier dependency and plugin to your build file, as
shown in the following example:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-starter-contract-verifier&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;</programlisting>
<simpara>The following listing shows how to add the plugin, which should go in the build/plugins
portion of the file:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;/plugin&gt;</programlisting>
<simpara>Running <literal>./mvnw clean install</literal> automatically generates tests that verify the application
compliance with the added contracts. By default, the tests get generated under
<literal>org.springframework.cloud.contract.verifier.tests.</literal>.</simpara>
<simpara>As the implementation of the functionalities described by the contracts is not yet
present, the tests fail.</simpara>
<simpara>To make them pass, you must add the correct implementation of either handling HTTP
requests or messages. Also, you must add a correct base test class for auto-generated
tests to the project. This class is extended by all the auto-generated tests, and it
should contain all the setup necessary to run them (for example <literal>RestAssuredMockMvc</literal>
controller setup or messaging test setup).</simpara>
<simpara>Once the implementation and the test base class are in place, the tests pass, and both the
application and the stub artifacts are built and installed in the local Maven repository.
The changes can now be merged, and both the application and the stub artifacts may be
published in an online repository.</simpara>
</section>
<section xml:id="spring-cloud-contract-verifier-intro-three-second-tour-consumer">
<title>On the Consumer Side</title>
<simpara><literal>Spring Cloud Contract Stub Runner</literal> can be used in the integration tests to get a running
WireMock instance or messaging route that simulates the actual service.</simpara>
<simpara>To do so, add the dependency to <literal>Spring Cloud Contract Stub Runner</literal>, as shown in the
following example:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-starter-contract-stub-runner&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;</programlisting>
<simpara>You can get the Producer-side stubs installed in your Maven repository in either of two
ways:</simpara>
<itemizedlist>
<listitem>
<simpara>By checking out the Producer side repository and adding contracts and generating the stubs
by running the following commands:</simpara>
<programlisting language="bash" linenumbering="unnumbered">$ cd local-http-server-repo
$ ./mvnw clean install -DskipTests</programlisting>
<tip>
<simpara>The tests are being skipped because the Producer-side contract implementation is not
in place yet, so the automatically-generated contract tests fail.</simpara>
</tip>
</listitem>
<listitem>
<simpara>By getting already-existing producer service stubs from a remote repository. To do so,
pass the stub artifact IDs and artifact repository URL as <literal>Spring Cloud Contract
Stub Runner</literal> properties, as shown in the following example:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">stubrunner:
ids: 'com.example:http-server-dsl:+:stubs:8080'
repositoryRoot: http://repo.spring.io/libs-snapshot</programlisting>
</listitem>
</itemizedlist>
<simpara>Now you can annotate your test class with <literal>@AutoConfigureStubRunner</literal>. In the annotation,
provide the <literal>group-id</literal> and <literal>artifact-id</literal> values for <literal>Spring Cloud Contract Stub Runner</literal> to
run the collaborators' stubs for you, as shown in the following example:</simpara>
<programlisting language="java" linenumbering="unnumbered">@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment=WebEnvironment.NONE)
@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:6565"},
stubsMode = StubRunnerProperties.StubsMode.LOCAL)
public class LoanApplicationServiceTests {</programlisting>
<tip>
<simpara>Use the <literal>REMOTE</literal> <literal>stubsMode</literal> when downloading stubs from an online repository and
<literal>LOCAL</literal> for offline work.</simpara>
</tip>
<simpara>Now, in your integration test, you can receive stubbed versions of HTTP responses or
messages that are expected to be emitted by the collaborator service.</simpara>
</section>
</section>
<section xml:id="spring-cloud-contract-verifier-intro-three-minute-tour">
<title>A Three-minute Tour</title>
<simpara>This brief tour walks through using Spring Cloud Contract:</simpara>
<itemizedlist>
<listitem>
<simpara><xref linkend="spring-cloud-contract-verifier-intro-three-minute-tour-producer"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="spring-cloud-contract-verifier-intro-three-minute-tour-consumer"/></simpara>
</listitem>
</itemizedlist>
<simpara>You can find an even more brief tour
<link linkend="spring-cloud-contract-verifier-intro-three-second-tour">here</link>.</simpara>
<section xml:id="spring-cloud-contract-verifier-intro-three-minute-tour-producer">
<title>On the Producer Side</title>
<simpara>To start working with <literal>Spring Cloud Contract</literal>, add files with <literal>REST/</literal> messaging contracts
expressed in either Groovy DSL or YAML to the contracts directory, which is set by the
<literal>contractsDslDir</literal> property. By default, it is <literal>$rootDir/src/test/resources/contracts</literal>.</simpara>
<simpara>For the HTTP stubs, a contract defines what kind of response should be returned for a
given request (taking into account the HTTP methods, URLs, headers, status codes, and so
on). The following example shows how an HTTP stub contract in Groovy DSL:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">package contracts
org.springframework.cloud.contract.spec.Contract.make {
request {
method 'PUT'
url '/fraudcheck'
body([
"client.id": $(regex('[0-9]{10}')),
loanAmount: 99999
])
headers {
contentType('application/json')
}
}
response {
status OK()
body([
fraudCheckStatus: "FRAUD",
"rejection.reason": "Amount too high"
])
headers {
contentType('application/json')
}
}
}</programlisting>
<simpara>The same contract expressed in YAML would look like the following example:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">request:
method: PUT
url: /fraudcheck
body:
"client.id": 1234567890
loanAmount: 99999
headers:
Content-Type: application/json
matchers:
body:
- path: $.['client.id']
type: by_regex
value: "[0-9]{10}"
response:
status: 200
body:
fraudCheckStatus: "FRAUD"
"rejection.reason": "Amount too high"
headers:
Content-Type: application/json;charset=UTF-8</programlisting>
<simpara>In the case of messaging, you can define:</simpara>
<itemizedlist>
<listitem>
<simpara>The input and the output messages can be defined (taking into account from and where it
was sent, the message body, and the header).</simpara>
</listitem>
<listitem>
<simpara>The methods that should be called after the message is received.</simpara>
</listitem>
<listitem>
<simpara>The methods that, when called, should trigger a message.</simpara>
</listitem>
</itemizedlist>
<simpara>The following example shows a Camel messaging contract expressed in Groovy DSL:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">def contractDsl = Contract.make {
label 'some_label'
input {
messageFrom('jms:delete')
messageBody([
bookName: 'foo'
])
messageHeaders {
header('sample', 'header')
}
assertThat('bookWasDeleted()')
}
}</programlisting>
<simpara>The following example shows the same contract expressed in YAML:</simpara>
<programlisting language="yml" linenumbering="unnumbered">label: some_label
input:
messageFrom: jms:delete
messageBody:
bookName: 'foo'
messageHeaders:
sample: header
assertThat: bookWasDeleted()</programlisting>
<simpara>Then you can add Spring Cloud Contract Verifier dependency and plugin to your build file,
as shown in the following example:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-starter-contract-verifier&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;</programlisting>
<simpara>The following listing shows how to add the plugin, which should go in the build/plugins
portion of the file:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;/plugin&gt;</programlisting>
<simpara>Running <literal>./mvnw clean install</literal> automatically generates tests that verify the application
compliance with the added contracts. By default, the generated tests are under
<literal>org.springframework.cloud.contract.verifier.tests.</literal>.</simpara>
<simpara>The following example shows a sample auto-generated test for an HTTP contract:</simpara>
<programlisting language="java" linenumbering="unnumbered">@Test
public void validate_shouldMarkClientAsFraud() throws Exception {
// given:
MockMvcRequestSpecification request = given()
.header("Content-Type", "application/vnd.fraud.v1+json")
.body("{\"client.id\":\"1234567890\",\"loanAmount\":99999}");
// when:
ResponseOptions response = given().spec(request)
.put("/fraudcheck");
// then:
assertThat(response.statusCode()).isEqualTo(200);
assertThat(response.header("Content-Type")).matches("application/vnd.fraud.v1.json.*");
// and:
DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
assertThatJson(parsedJson).field("['fraudCheckStatus']").matches("[A-Z]{5}");
assertThatJson(parsedJson).field("['rejection.reason']").isEqualTo("Amount too high");
}</programlisting>
<simpara>The preceding example uses Spring&#8217;s <literal>MockMvc</literal> to run the tests. This is the default test
mode for HTTP contracts. However, JAX-RS client and explicit HTTP invocations can also be
used. (To do so, change the <literal>testMode</literal> property of the plugin to <literal>JAX-RS</literal> or <literal>EXPLICIT</literal>,
respectively.)</simpara>
<simpara>Since 2.1.0, it is also possible to use <literal>RestAssuredWebTestClient`with Spring&#8217;s reactive `WebTestClient</literal>
run under the hood. This is particularly recommended while working with Reactive, <literal>Web-Flux</literal>-based applications.
In order to use <literal>WebTestClient</literal> set <literal>testMode</literal> to <literal>WEBTESTCLIENT</literal>.</simpara>
<simpara>Here is an example of a test generated in <literal>WEBTESTCLIENT</literal> test mode:</simpara>
<literallayout class="monospaced">[source,java,indent=0]</literallayout>
<screen>@Test
public void validate_shouldRejectABeerIfTooYoung() throws Exception {
// given:
WebTestClientRequestSpecification request = given()
.header("Content-Type", "application/json")
.body("{\"age\":10}");
// when:
WebTestClientResponse response = given().spec(request)
.post("/check");
// then:
assertThat(response.statusCode()).isEqualTo(200);
assertThat(response.header("Content-Type")).matches("application/json.*");
// and:
DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
assertThatJson(parsedJson).field("['status']").isEqualTo("NOT_OK");
}</screen>
<simpara>Apart from the default JUnit 4, you can instead use JUnit 5 or Spock tests, by setting the plugin
<literal>testFramework</literal> property to either <literal>JUNIT5</literal> or <literal>Spock</literal>.</simpara>
<tip>
<simpara>You can now also generate WireMock scenarios based on the contracts, by including an
order number followed by an underscore at the beginning of the contract file names.</simpara>
</tip>
<simpara>The following example shows an auto-generated test in Spock for a messaging stub contract:</simpara>
<literallayout class="monospaced">[source,groovy,indent=0]</literallayout>
<screen>given:
ContractVerifierMessage inputMessage = contractVerifierMessaging.create(
\'\'\'{"bookName":"foo"}\'\'\',
['sample': 'header']
)
when:
contractVerifierMessaging.send(inputMessage, 'jms:delete')
then:
noExceptionThrown()
bookWasDeleted()</screen>
<simpara>As the implementation of the functionalities described by the contracts is not yet
present, the tests fail.</simpara>
<simpara>To make them pass, you must add the correct implementation of handling either HTTP
requests or messages. Also, you must add a correct base test class for auto-generated
tests to the project. This class is extended by all the auto-generated tests and should
contain all the setup necessary to run them (for example, <literal>RestAssuredMockMvc</literal> controller
setup or messaging test setup).</simpara>
<simpara>Once the implementation and the test base class are in place, the tests pass, and both the
application and the stub artifacts are built and installed in the local Maven repository.
Information about installing the stubs jar to the local repository appears in the logs, as
shown in the following example:</simpara>
<programlisting language="bash" linenumbering="unnumbered">[INFO] --- spring-cloud-contract-maven-plugin:1.0.0.BUILD-SNAPSHOT:generateStubs (default-generateStubs) @ http-server ---
[INFO] Building jar: /some/path/http-server/target/http-server-0.0.1-SNAPSHOT-stubs.jar
[INFO]
[INFO] --- maven-jar-plugin:2.6:jar (default-jar) @ http-server ---
[INFO] Building jar: /some/path/http-server/target/http-server-0.0.1-SNAPSHOT.jar
[INFO]
[INFO] --- spring-boot-maven-plugin:1.5.5.BUILD-SNAPSHOT:repackage (default) @ http-server ---
[INFO]
[INFO] --- maven-install-plugin:2.5.2:install (default-install) @ http-server ---
[INFO] Installing /some/path/http-server/target/http-server-0.0.1-SNAPSHOT.jar to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT.jar
[INFO] Installing /some/path/http-server/pom.xml to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT.pom
[INFO] Installing /some/path/http-server/target/http-server-0.0.1-SNAPSHOT-stubs.jar to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar</programlisting>
<simpara>You can now merge the changes and publish both the application and the stub artifacts
in an online repository.</simpara>
<simpara><emphasis role="strong">Docker Project</emphasis></simpara>
<simpara>In order to enable working with contracts while creating applications in non-JVM
technologies, the <literal>springcloud/spring-cloud-contract</literal> Docker image has been created. It
contains a project that automatically generates tests for HTTP contracts and executes them
in <literal>EXPLICIT</literal> test mode. Then, if the tests pass, it generates Wiremock stubs and,
optionally, publishes them to an artifact manager. In order to use the image, you can
mount the contracts into the <literal>/contracts</literal> directory and set a few environment variables.</simpara>
</section>
<section xml:id="spring-cloud-contract-verifier-intro-three-minute-tour-consumer">
<title>On the Consumer Side</title>
<simpara><literal>Spring Cloud Contract Stub Runner</literal> can be used in the integration tests to get a running
WireMock instance or messaging route that simulates the actual service.</simpara>
<simpara>To get started, add the dependency to <literal>Spring Cloud Contract Stub Runner</literal>:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-starter-contract-stub-runner&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;</programlisting>
<simpara>You can get the Producer-side stubs installed in your Maven repository in either of two
ways:</simpara>
<itemizedlist>
<listitem>
<simpara>By checking out the Producer side repository and adding contracts and generating the
stubs by running the following commands:</simpara>
<programlisting language="bash" linenumbering="unnumbered">$ cd local-http-server-repo
$ ./mvnw clean install -DskipTests</programlisting>
<note>
<simpara>The tests are skipped because the Producer-side contract implementation is not yet
in place, so the automatically-generated contract tests fail.</simpara>
</note>
</listitem>
<listitem>
<simpara>Getting already existing producer service stubs from a remote repository. To do so,
pass the stub artifact IDs and artifact repository URl as <literal>Spring Cloud Contract Stub
Runner</literal> properties, as shown in the following example:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">stubrunner:
ids: 'com.example:http-server-dsl:+:stubs:8080'
repositoryRoot: http://repo.spring.io/libs-snapshot</programlisting>
</listitem>
</itemizedlist>
<simpara>Now you can annotate your test class with <literal>@AutoConfigureStubRunner</literal>. In the annotation,
provide the <literal>group-id</literal> and <literal>artifact-id</literal> for <literal>Spring Cloud Contract Stub Runner</literal> to run
the collaborators' stubs for you, as shown in the following example:</simpara>
<programlisting language="java" linenumbering="unnumbered">@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment=WebEnvironment.NONE)
@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:6565"},
stubsMode = StubRunnerProperties.StubsMode.LOCAL)
public class LoanApplicationServiceTests {</programlisting>
<tip>
<simpara>Use the <literal>REMOTE</literal> <literal>stubsMode</literal> when downloading stubs from an online repository and
<literal>LOCAL</literal> for offline work.</simpara>
</tip>
<simpara>In your integration test, you can receive stubbed versions of HTTP responses or messages
that are expected to be emitted by the collaborator service. You can see entries similar
to the following in the build logs:</simpara>
<programlisting language="bash" linenumbering="unnumbered">2016-07-19 14:22:25.403 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Desired version is + - will try to resolve the latest version
2016-07-19 14:22:25.438 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved version is 0.0.1-SNAPSHOT
2016-07-19 14:22:25.439 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolving artifact com.example:http-server:jar:stubs:0.0.1-SNAPSHOT using remote repositories []
2016-07-19 14:22:25.451 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved artifact com.example:http-server:jar:stubs:0.0.1-SNAPSHOT to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar
2016-07-19 14:22:25.465 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacking stub from JAR [URI: file:/path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar]
2016-07-19 14:22:25.475 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacked file to [/var/folders/0p/xwq47sq106x1_g3dtv6qfm940000gq/T/contracts100276532569594265]
2016-07-19 14:22:27.737 INFO 41050 --- [ main] o.s.c.c.stubrunner.StubRunnerExecutor : All stubs are now running RunningStubs [namesAndPorts={com.example:http-server:0.0.1-SNAPSHOT:stubs=8080}]</programlisting>
</section>
</section>
<section xml:id="_defining_the_contract">
<title>Defining the Contract</title>
<simpara>As consumers of services, we need to define what exactly we want to achieve. We need to
formulate our expectations. That is why we write contracts.</simpara>
<simpara>Assume that you want to send a request containing the ID of a client company and the
amount it wants to borrow from us. You also want to send it to the /fraudcheck url via
the PUT method.</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">package contracts
org.springframework.cloud.contract.spec.Contract.make {
request { // (1)
method 'PUT' // (2)
url '/fraudcheck' // (3)
body([ // (4)
"client.id": $(regex('[0-9]{10}')),
loanAmount: 99999
])
headers { // (5)
contentType('application/json')
}
}
response { // (6)
status OK() // (7)
body([ // (8)
fraudCheckStatus: "FRAUD",
"rejection.reason": "Amount too high"
])
headers { // (9)
contentType('application/json')
}
}
}
/*
From the Consumer perspective, when shooting a request in the integration test:
(1) - If the consumer sends a request
(2) - With the "PUT" method
(3) - to the URL "/fraudcheck"
(4) - with the JSON body that
* has a field `client.id` that matches a regular expression `[0-9]{10}`
* has a field `loanAmount` that is equal to `99999`
(5) - with header `Content-Type` equal to `application/json`
(6) - then the response will be sent with
(7) - status equal `200`
(8) - and JSON body equal to
{ "fraudCheckStatus": "FRAUD", "rejectionReason": "Amount too high" }
(9) - with header `Content-Type` equal to `application/json`
From the Producer perspective, in the autogenerated producer-side test:
(1) - A request will be sent to the producer
(2) - With the "PUT" method
(3) - to the URL "/fraudcheck"
(4) - with the JSON body that
* has a field `client.id` that will have a generated value that matches a regular expression `[0-9]{10}`
* has a field `loanAmount` that is equal to `99999`
(5) - with header `Content-Type` equal to `application/json`
(6) - then the test will assert if the response has been sent with
(7) - status equal `200`
(8) - and JSON body equal to
{ "fraudCheckStatus": "FRAUD", "rejectionReason": "Amount too high" }
(9) - with header `Content-Type` matching `application/json.*`
*/</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">request: # (1)
method: PUT # (2)
url: /fraudcheck # (3)
body: # (4)
"client.id": 1234567890
loanAmount: 99999
headers: # (5)
Content-Type: application/json
matchers:
body:
- path: $.['client.id'] # (6)
type: by_regex
value: "[0-9]{10}"
response: # (7)
status: 200 # (8)
body: # (9)
fraudCheckStatus: "FRAUD"
"rejection.reason": "Amount too high"
headers: # (10)
Content-Type: application/json;charset=UTF-8
#From the Consumer perspective, when shooting a request in the integration test:
#
#(1) - If the consumer sends a request
#(2) - With the "PUT" method
#(3) - to the URL "/fraudcheck"
#(4) - with the JSON body that
# * has a field `client.id`
# * has a field `loanAmount` that is equal to `99999`
#(5) - with header `Content-Type` equal to `application/json`
#(6) - and a `client.id` json entry matches the regular expression `[0-9]{10}`
#(7) - then the response will be sent with
#(8) - status equal `200`
#(9) - and JSON body equal to
# { "fraudCheckStatus": "FRAUD", "rejectionReason": "Amount too high" }
#(10) - with header `Content-Type` equal to `application/json`
#
#From the Producer perspective, in the autogenerated producer-side test:
#
#(1) - A request will be sent to the producer
#(2) - With the "PUT" method
#(3) - to the URL "/fraudcheck"
#(4) - with the JSON body that
# * has a field `client.id` `1234567890`
# * has a field `loanAmount` that is equal to `99999`
#(5) - with header `Content-Type` equal to `application/json`
#(7) - then the test will assert if the response has been sent with
#(8) - status equal `200`
#(9) - and JSON body equal to
# { "fraudCheckStatus": "FRAUD", "rejectionReason": "Amount too high" }
#(10) - with header `Content-Type` equal to `application/json;charset=UTF-8`</programlisting>
</para>
</formalpara>
</section>
<section xml:id="_client_side">
<title>Client Side</title>
<simpara>Spring Cloud Contract generates stubs, which you can use during client-side testing.
You get a running WireMock instance/Messaging route that simulates the service.
You would like to feed that instance with a proper stub definition.</simpara>
<simpara>At some point in time, you need to send a request to the Fraud Detection service.</simpara>
<programlisting language="groovy" linenumbering="unnumbered">ResponseEntity&lt;FraudServiceResponse&gt; response =
restTemplate.exchange("http://localhost:" + port + "/fraudcheck", HttpMethod.PUT,
new HttpEntity&lt;&gt;(request, httpHeaders),
FraudServiceResponse.class);</programlisting>
<simpara>Annotate your test class with <literal>@AutoConfigureStubRunner</literal>. In the annotation provide the group id and artifact id for the Stub Runner to download stubs of your collaborators.</simpara>
<programlisting language="groovy" linenumbering="unnumbered">@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = WebEnvironment.NONE)
@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:6565"},
stubsMode = StubRunnerProperties.StubsMode.LOCAL)
public class LoanApplicationServiceTests {</programlisting>
<simpara>After that, during the tests, Spring Cloud Contract automatically finds the stubs
(simulating the real service) in the Maven repository and exposes them on a configured
(or random) port.</simpara>
</section>
<section xml:id="_server_side">
<title>Server Side</title>
<simpara>Since you are developing your stub, you need to be sure that it actually resembles your
concrete implementation. You cannot have a situation where your stub acts in one way and
your application behaves in a different way, especially in production.</simpara>
<simpara>To ensure that your application behaves the way you define in your stub, tests are
generated from the stub you provide.</simpara>
<simpara>The autogenerated test looks, more or less, like this:</simpara>
<programlisting language="java" linenumbering="unnumbered">@Test
public void validate_shouldMarkClientAsFraud() throws Exception {
// given:
MockMvcRequestSpecification request = given()
.header("Content-Type", "application/vnd.fraud.v1+json")
.body("{\"client.id\":\"1234567890\",\"loanAmount\":99999}");
// when:
ResponseOptions response = given().spec(request)
.put("/fraudcheck");
// then:
assertThat(response.statusCode()).isEqualTo(200);
assertThat(response.header("Content-Type")).matches("application/vnd.fraud.v1.json.*");
// and:
DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
assertThatJson(parsedJson).field("['fraudCheckStatus']").matches("[A-Z]{5}");
assertThatJson(parsedJson).field("['rejection.reason']").isEqualTo("Amount too high");
}</programlisting>
</section>
</section>
<section xml:id="_step_by_step_guide_to_consumer_driven_contracts_cdc">
<title>Step-by-step Guide to Consumer Driven Contracts (CDC)</title>
<simpara>Consider an example of Fraud Detection and the Loan Issuance process. The business
scenario is such that we want to issue loans to people but do not want them to steal from
us. The current implementation of our system grants loans to everybody.</simpara>
<simpara>Assume that <literal>Loan Issuance</literal> is a client to the <literal>Fraud Detection</literal> server. In the current
sprint, we must develop a new feature: if a client wants to borrow too much money, then
we mark the client as a fraud.</simpara>
<simpara>Technical remark - Fraud Detection has an <literal>artifact-id</literal> of <literal>http-server</literal>, while Loan
Issuance has an artifact-id of <literal>http-client</literal>, and both have a <literal>group-id</literal> of <literal>com.example</literal>.</simpara>
<simpara>Social remark - both client and server development teams need to communicate directly and
discuss changes while going through the process. CDC is all about communication.</simpara>
<simpara>The <link xl:href="https://github.com/spring-cloud/spring-cloud-contract/tree/master/samples/standalone/dsl/http-server">server
side code is available here</link> and <link xl:href="https://github.com/spring-cloud/spring-cloud-contract/tree/master/samples/standalone/dsl/http-client">the
client code here</link>.</simpara>
<tip>
<simpara>In this case, the producer owns the contracts. Physically, all the contract are
in the producer&#8217;s repository.</simpara>
</tip>
<section xml:id="_technical_note">
<title>Technical note</title>
<simpara>If using the <emphasis role="strong">SNAPSHOT</emphasis> / <emphasis role="strong">Milestone</emphasis> / <emphasis role="strong">Release Candidate</emphasis> versions please add the
following section to your build:</simpara>
<formalpara role="primary">
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;repositories&gt;
&lt;repository&gt;
&lt;id&gt;spring-snapshots&lt;/id&gt;
&lt;name&gt;Spring Snapshots&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/snapshot&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;true&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/repository&gt;
&lt;repository&gt;
&lt;id&gt;spring-milestones&lt;/id&gt;
&lt;name&gt;Spring Milestones&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/milestone&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/repository&gt;
&lt;repository&gt;
&lt;id&gt;spring-releases&lt;/id&gt;
&lt;name&gt;Spring Releases&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/release&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/repository&gt;
&lt;/repositories&gt;
&lt;pluginRepositories&gt;
&lt;pluginRepository&gt;
&lt;id&gt;spring-snapshots&lt;/id&gt;
&lt;name&gt;Spring Snapshots&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/snapshot&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;true&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/pluginRepository&gt;
&lt;pluginRepository&gt;
&lt;id&gt;spring-milestones&lt;/id&gt;
&lt;name&gt;Spring Milestones&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/milestone&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/pluginRepository&gt;
&lt;pluginRepository&gt;
&lt;id&gt;spring-releases&lt;/id&gt;
&lt;name&gt;Spring Releases&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/release&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/pluginRepository&gt;
&lt;/pluginRepositories&gt;</programlisting>
</para>
</formalpara>
<formalpara role="secondary">
<title>Gradle</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">repositories {
mavenCentral()
mavenLocal()
maven { url "http://repo.spring.io/snapshot" }
maven { url "http://repo.spring.io/milestone" }
maven { url "http://repo.spring.io/release" }
}</programlisting>
</para>
</formalpara>
</section>
<section xml:id="_consumer_side_loan_issuance">
<title>Consumer side (Loan Issuance)</title>
<simpara>As a developer of the Loan Issuance service (a consumer of the Fraud Detection server), you might do the following steps:</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>Start doing TDD by writing a test for your feature.</simpara>
</listitem>
<listitem>
<simpara>Write the missing implementation.</simpara>
</listitem>
<listitem>
<simpara>Clone the Fraud Detection service repository locally.</simpara>
</listitem>
<listitem>
<simpara>Define the contract locally in the repo of Fraud Detection service.</simpara>
</listitem>
<listitem>
<simpara>Add the Spring Cloud Contract Verifier plugin.</simpara>
</listitem>
<listitem>
<simpara>Run the integration tests.</simpara>
</listitem>
<listitem>
<simpara>File a pull request.</simpara>
</listitem>
<listitem>
<simpara>Create an initial implementation.</simpara>
</listitem>
<listitem>
<simpara>Take over the pull request.</simpara>
</listitem>
<listitem>
<simpara>Write the missing implementation.</simpara>
</listitem>
<listitem>
<simpara>Deploy your app.</simpara>
</listitem>
<listitem>
<simpara>Work online.</simpara>
</listitem>
</orderedlist>
<simpara><emphasis role="strong">Start doing TDD by writing a test for your feature.</emphasis></simpara>
<programlisting language="groovy" linenumbering="unnumbered">@Test
public void shouldBeRejectedDueToAbnormalLoanAmount() {
// given:
LoanApplication application = new LoanApplication(new Client("1234567890"),
99999);
// when:
LoanApplicationResult loanApplication = service.loanApplication(application);
// then:
assertThat(loanApplication.getLoanApplicationStatus())
.isEqualTo(LoanApplicationStatus.LOAN_APPLICATION_REJECTED);
assertThat(loanApplication.getRejectionReason()).isEqualTo("Amount too high");
}</programlisting>
<simpara>Assume that you have written a test of your new feature. If a loan application for a big
amount is received, the system should reject that loan application with some description.</simpara>
<simpara><emphasis role="strong">Write the missing implementation.</emphasis></simpara>
<simpara>At some point in time, you need to send a request to the Fraud Detection service. Assume
that you need to send the request containing the ID of the client and the amount the
client wants to borrow. You want to send it to the <literal>/fraudcheck</literal> url via the <literal>PUT</literal> method.</simpara>
<programlisting language="groovy" linenumbering="unnumbered">ResponseEntity&lt;FraudServiceResponse&gt; response =
restTemplate.exchange("http://localhost:" + port + "/fraudcheck", HttpMethod.PUT,
new HttpEntity&lt;&gt;(request, httpHeaders),
FraudServiceResponse.class);</programlisting>
<simpara>For simplicity, the port of the Fraud Detection service is set to <literal>8080</literal>, and the
application runs on <literal>8090</literal>.</simpara>
<simpara>If you start the test at this point, it breaks, because no service currently runs on port
<literal>8080</literal>.</simpara>
<simpara><emphasis role="strong">Clone the Fraud Detection service repository locally.</emphasis></simpara>
<simpara>You can start by playing around with the server side contract. To do so, you must first
clone it.</simpara>
<programlisting language="bash" linenumbering="unnumbered">$ git clone https://your-git-server.com/server-side.git local-http-server-repo</programlisting>
<simpara><emphasis role="strong">Define the contract locally in the repo of Fraud Detection service.</emphasis></simpara>
<simpara>As a consumer, you need to define what exactly you want to achieve. You need to formulate
your expectations. To do so, write the following contract:</simpara>
<important>
<simpara>Place the contract under <literal>src/test/resources/contracts/fraud</literal> folder. The <literal>fraud</literal> folder
is important because the producer&#8217;s test base class name references that folder.</simpara>
</important>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">package contracts
org.springframework.cloud.contract.spec.Contract.make {
request { // (1)
method 'PUT' // (2)
url '/fraudcheck' // (3)
body([ // (4)
"client.id": $(regex('[0-9]{10}')),
loanAmount: 99999
])
headers { // (5)
contentType('application/json')
}
}
response { // (6)
status OK() // (7)
body([ // (8)
fraudCheckStatus: "FRAUD",
"rejection.reason": "Amount too high"
])
headers { // (9)
contentType('application/json')
}
}
}
/*
From the Consumer perspective, when shooting a request in the integration test:
(1) - If the consumer sends a request
(2) - With the "PUT" method
(3) - to the URL "/fraudcheck"
(4) - with the JSON body that
* has a field `client.id` that matches a regular expression `[0-9]{10}`
* has a field `loanAmount` that is equal to `99999`
(5) - with header `Content-Type` equal to `application/json`
(6) - then the response will be sent with
(7) - status equal `200`
(8) - and JSON body equal to
{ "fraudCheckStatus": "FRAUD", "rejectionReason": "Amount too high" }
(9) - with header `Content-Type` equal to `application/json`
From the Producer perspective, in the autogenerated producer-side test:
(1) - A request will be sent to the producer
(2) - With the "PUT" method
(3) - to the URL "/fraudcheck"
(4) - with the JSON body that
* has a field `client.id` that will have a generated value that matches a regular expression `[0-9]{10}`
* has a field `loanAmount` that is equal to `99999`
(5) - with header `Content-Type` equal to `application/json`
(6) - then the test will assert if the response has been sent with
(7) - status equal `200`
(8) - and JSON body equal to
{ "fraudCheckStatus": "FRAUD", "rejectionReason": "Amount too high" }
(9) - with header `Content-Type` matching `application/json.*`
*/</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">request: # (1)
method: PUT # (2)
url: /fraudcheck # (3)
body: # (4)
"client.id": 1234567890
loanAmount: 99999
headers: # (5)
Content-Type: application/json
matchers:
body:
- path: $.['client.id'] # (6)
type: by_regex
value: "[0-9]{10}"
response: # (7)
status: 200 # (8)
body: # (9)
fraudCheckStatus: "FRAUD"
"rejection.reason": "Amount too high"
headers: # (10)
Content-Type: application/json;charset=UTF-8
#From the Consumer perspective, when shooting a request in the integration test:
#
#(1) - If the consumer sends a request
#(2) - With the "PUT" method
#(3) - to the URL "/fraudcheck"
#(4) - with the JSON body that
# * has a field `client.id`
# * has a field `loanAmount` that is equal to `99999`
#(5) - with header `Content-Type` equal to `application/json`
#(6) - and a `client.id` json entry matches the regular expression `[0-9]{10}`
#(7) - then the response will be sent with
#(8) - status equal `200`
#(9) - and JSON body equal to
# { "fraudCheckStatus": "FRAUD", "rejectionReason": "Amount too high" }
#(10) - with header `Content-Type` equal to `application/json`
#
#From the Producer perspective, in the autogenerated producer-side test:
#
#(1) - A request will be sent to the producer
#(2) - With the "PUT" method
#(3) - to the URL "/fraudcheck"
#(4) - with the JSON body that
# * has a field `client.id` `1234567890`
# * has a field `loanAmount` that is equal to `99999`
#(5) - with header `Content-Type` equal to `application/json`
#(7) - then the test will assert if the response has been sent with
#(8) - status equal `200`
#(9) - and JSON body equal to
# { "fraudCheckStatus": "FRAUD", "rejectionReason": "Amount too high" }
#(10) - with header `Content-Type` equal to `application/json;charset=UTF-8`</programlisting>
</para>
</formalpara>
<simpara>The YML contract is quite straight-forward. However when you take a look at the Contract
written using a statically typed Groovy DSL - you might wonder what the
<literal>value(client(&#8230;&#8203;), server(&#8230;&#8203;))</literal> parts are. By using this notation, Spring Cloud
Contract lets you define parts of a JSON block, a URL, etc., which are dynamic. In case
of an identifier or a timestamp, you need not hardcode a value. You want to allow some
different ranges of values. To enable ranges of values, you can set regular expressions
matching those values for the consumer side. You can provide the body by means of either
a map notation or String with interpolations.
Consult the <xref linkend="contract-dsl"/> section for more information. We highly recommend using the map notation!</simpara>
<tip>
<simpara>You must understand the map notation in order to set up contracts. Please read the
<link xl:href="http://groovy-lang.org/json.html">Groovy docs regarding JSON</link>.</simpara>
</tip>
<simpara>The previously shown contract is an agreement between two sides that:</simpara>
<itemizedlist>
<listitem>
<simpara>if an HTTP request is sent with all of</simpara>
<itemizedlist>
<listitem>
<simpara>a <literal>PUT</literal> method on the <literal>/fraudcheck</literal> endpoint,</simpara>
</listitem>
<listitem>
<simpara>a JSON body with a <literal>client.id</literal> that matches the regular expression <literal>[0-9]{10}</literal> and
<literal>loanAmount</literal> equal to <literal>99999</literal>,</simpara>
</listitem>
<listitem>
<simpara>and a <literal>Content-Type</literal> header with a value of <literal>application/vnd.fraud.v1+json</literal>,</simpara>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<simpara>then an HTTP response is sent to the consumer that</simpara>
<itemizedlist>
<listitem>
<simpara>has status <literal>200</literal>,</simpara>
</listitem>
<listitem>
<simpara>contains a JSON body with the <literal>fraudCheckStatus</literal> field containing a value <literal>FRAUD</literal> and
the <literal>rejectionReason</literal> field having value <literal>Amount too high</literal>,</simpara>
</listitem>
<listitem>
<simpara>and a <literal>Content-Type</literal> header with a value of <literal>application/vnd.fraud.v1+json</literal>.</simpara>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<simpara>Once you are ready to check the API in practice in the integration tests, you need to
install the stubs locally.</simpara>
<simpara><emphasis role="strong">Add the Spring Cloud Contract Verifier plugin.</emphasis></simpara>
<simpara>We can add either a Maven or a Gradle plugin. In this example, you see how to add Maven.
First, add the <literal>Spring Cloud Contract</literal> BOM.</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependencyManagement&gt;
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-dependencies&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-release.version}&lt;/version&gt;
&lt;type&gt;pom&lt;/type&gt;
&lt;scope&gt;import&lt;/scope&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;/dependencyManagement&gt;</programlisting>
<simpara>Next, add the <literal>Spring Cloud Contract Verifier</literal> Maven plugin</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;configuration&gt;
&lt;packageWithBaseClasses&gt;com.example.fraud&lt;/packageWithBaseClasses&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</programlisting>
<simpara>Since the plugin was added, you get the <literal>Spring Cloud Contract Verifier</literal> features which,
from the provided contracts:</simpara>
<itemizedlist>
<listitem>
<simpara>generate and run tests</simpara>
</listitem>
<listitem>
<simpara>produce and install stubs</simpara>
</listitem>
</itemizedlist>
<simpara>You do not want to generate tests since you, as the consumer, want only to play with the
stubs. You need to skip the test generation and execution. When you execute:</simpara>
<programlisting language="bash" linenumbering="unnumbered">$ cd local-http-server-repo
$ ./mvnw clean install -DskipTests</programlisting>
<simpara>In the logs, you see something like this:</simpara>
<programlisting language="bash" linenumbering="unnumbered">[INFO] --- spring-cloud-contract-maven-plugin:1.0.0.BUILD-SNAPSHOT:generateStubs (default-generateStubs) @ http-server ---
[INFO] Building jar: /some/path/http-server/target/http-server-0.0.1-SNAPSHOT-stubs.jar
[INFO]
[INFO] --- maven-jar-plugin:2.6:jar (default-jar) @ http-server ---
[INFO] Building jar: /some/path/http-server/target/http-server-0.0.1-SNAPSHOT.jar
[INFO]
[INFO] --- spring-boot-maven-plugin:1.5.5.BUILD-SNAPSHOT:repackage (default) @ http-server ---
[INFO]
[INFO] --- maven-install-plugin:2.5.2:install (default-install) @ http-server ---
[INFO] Installing /some/path/http-server/target/http-server-0.0.1-SNAPSHOT.jar to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT.jar
[INFO] Installing /some/path/http-server/pom.xml to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT.pom
[INFO] Installing /some/path/http-server/target/http-server-0.0.1-SNAPSHOT-stubs.jar to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar</programlisting>
<simpara>The following line is extremely important:</simpara>
<programlisting language="bash" linenumbering="unnumbered">[INFO] Installing /some/path/http-server/target/http-server-0.0.1-SNAPSHOT-stubs.jar to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar</programlisting>
<simpara>It confirms that the stubs of the <literal>http-server</literal> have been installed in the local
repository.</simpara>
<simpara><emphasis role="strong">Run the integration tests.</emphasis></simpara>
<simpara>In order to profit from the Spring Cloud Contract Stub Runner functionality of automatic
stub downloading, you must do the following in your consumer side project (<literal>Loan
Application service</literal>):</simpara>
<simpara>Add the <literal>Spring Cloud Contract</literal> BOM:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependencyManagement&gt;
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-dependencies&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-release-train.version}&lt;/version&gt;
&lt;type&gt;pom&lt;/type&gt;
&lt;scope&gt;import&lt;/scope&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;/dependencyManagement&gt;</programlisting>
<simpara>Add the dependency to <literal>Spring Cloud Contract Stub Runner</literal>:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-starter-contract-stub-runner&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;</programlisting>
<simpara>Annotate your test class with <literal>@AutoConfigureStubRunner</literal>. In the annotation, provide the
<literal>group-id</literal> and <literal>artifact-id</literal> for the Stub Runner to download the stubs of your
collaborators. (Optional step) Because you&#8217;re playing with the collaborators offline, you
can also provide the offline work switch (<literal>StubRunnerProperties.StubsMode.LOCAL</literal>).</simpara>
<programlisting language="groovy" linenumbering="unnumbered">@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = WebEnvironment.NONE)
@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:6565"},
stubsMode = StubRunnerProperties.StubsMode.LOCAL)
public class LoanApplicationServiceTests {</programlisting>
<simpara>Now, when you run your tests, you see something like this:</simpara>
<programlisting language="bash" linenumbering="unnumbered">2016-07-19 14:22:25.403 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Desired version is + - will try to resolve the latest version
2016-07-19 14:22:25.438 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved version is 0.0.1-SNAPSHOT
2016-07-19 14:22:25.439 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolving artifact com.example:http-server:jar:stubs:0.0.1-SNAPSHOT using remote repositories []
2016-07-19 14:22:25.451 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved artifact com.example:http-server:jar:stubs:0.0.1-SNAPSHOT to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar
2016-07-19 14:22:25.465 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacking stub from JAR [URI: file:/path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar]
2016-07-19 14:22:25.475 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacked file to [/var/folders/0p/xwq47sq106x1_g3dtv6qfm940000gq/T/contracts100276532569594265]
2016-07-19 14:22:27.737 INFO 41050 --- [ main] o.s.c.c.stubrunner.StubRunnerExecutor : All stubs are now running RunningStubs [namesAndPorts={com.example:http-server:0.0.1-SNAPSHOT:stubs=8080}]</programlisting>
<simpara>This output means that Stub Runner has found your stubs and started a server for your app
with group id <literal>com.example</literal>, artifact id <literal>http-server</literal> with version <literal>0.0.1-SNAPSHOT</literal> of
the stubs and with <literal>stubs</literal> classifier on port <literal>8080</literal>.</simpara>
<simpara><emphasis role="strong">File a pull request.</emphasis></simpara>
<simpara>What you have done until now is an iterative process. You can play around with the
contract, install it locally, and work on the consumer side until the contract works as
you wish.</simpara>
<simpara>Once you are satisfied with the results and the test passes, publish a pull request to
the server side. Currently, the consumer side work is done.</simpara>
</section>
<section xml:id="_producer_side_fraud_detection_server">
<title>Producer side (Fraud Detection server)</title>
<simpara>As a developer of the Fraud Detection server (a server to the Loan Issuance service):</simpara>
<simpara><emphasis role="strong">Create an initial implementation.</emphasis></simpara>
<simpara>As a reminder, you can see the initial implementation here:</simpara>
<programlisting language="java" linenumbering="unnumbered">@RequestMapping(value = "/fraudcheck", method = PUT)
public FraudCheckResult fraudCheck(@RequestBody FraudCheck fraudCheck) {
return new FraudCheckResult(FraudCheckStatus.OK, NO_REASON);
}</programlisting>
<simpara><emphasis role="strong">Take over the pull request.</emphasis></simpara>
<programlisting language="bash" linenumbering="unnumbered">$ git checkout -b contract-change-pr master
$ git pull https://your-git-server.com/server-side-fork.git contract-change-pr</programlisting>
<simpara>You must add the dependencies needed by the autogenerated tests:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-starter-contract-verifier&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;</programlisting>
<simpara>In the configuration of the Maven plugin, pass the <literal>packageWithBaseClasses</literal> property</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;configuration&gt;
&lt;packageWithBaseClasses&gt;com.example.fraud&lt;/packageWithBaseClasses&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</programlisting>
<important>
<simpara>This example uses "convention based" naming by setting the
<literal>packageWithBaseClasses</literal> property. Doing so means that the two last packages combine to
make the name of the base test class. In our case, the contracts were placed under
<literal>src/test/resources/contracts/fraud</literal>. Since you do not have two packages starting from
the <literal>contracts</literal> folder, pick only one, which should be <literal>fraud</literal>. Add the <literal>Base</literal> suffix and
capitalize <literal>fraud</literal>. That gives you the <literal>FraudBase</literal> test class name.</simpara>
</important>
<simpara>All the generated tests extend that class. Over there, you can set up your Spring Context
or whatever is necessary. In this case, use <link xl:href="http://rest-assured.io/">Rest Assured MVC</link> to
start the server side <literal>FraudDetectionController</literal>.</simpara>
<programlisting language="java" linenumbering="unnumbered">package com.example.fraud;
import io.restassured.module.mockmvc.RestAssuredMockMvc;
import org.junit.Before;
public class FraudBase {
@Before
public void setup() {
RestAssuredMockMvc.standaloneSetup(new FraudDetectionController(),
new FraudStatsController(stubbedStatsProvider()));
}
private StatsProvider stubbedStatsProvider() {
return fraudType -&gt; {
switch (fraudType) {
case DRUNKS:
return 100;
case ALL:
return 200;
}
return 0;
};
}
public void assertThatRejectionReasonIsNull(Object rejectionReason) {
assert rejectionReason == null;
}
}</programlisting>
<simpara>Now, if you run the <literal>./mvnw clean install</literal>, you get something like this:</simpara>
<programlisting language="bash" linenumbering="unnumbered">Results :
Tests in error:
ContractVerifierTest.validate_shouldMarkClientAsFraud:32 » IllegalState Parsed...</programlisting>
<simpara>This error occurs because you have a new contract from which a test was generated and it
failed since you have not implemented the feature. The auto-generated test would look
like this:</simpara>
<programlisting language="java" linenumbering="unnumbered">@Test
public void validate_shouldMarkClientAsFraud() throws Exception {
// given:
MockMvcRequestSpecification request = given()
.header("Content-Type", "application/vnd.fraud.v1+json")
.body("{\"client.id\":\"1234567890\",\"loanAmount\":99999}");
// when:
ResponseOptions response = given().spec(request)
.put("/fraudcheck");
// then:
assertThat(response.statusCode()).isEqualTo(200);
assertThat(response.header("Content-Type")).matches("application/vnd.fraud.v1.json.*");
// and:
DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
assertThatJson(parsedJson).field("['fraudCheckStatus']").matches("[A-Z]{5}");
assertThatJson(parsedJson).field("['rejection.reason']").isEqualTo("Amount too high");
}</programlisting>
<simpara>If you used the Groovy DSL, you can see, all the <literal>producer()</literal> parts of the Contract that were present in the
<literal>value(consumer(&#8230;&#8203;), producer(&#8230;&#8203;))</literal> blocks got injected into the test.
In case of using YAML, the same applied for the <literal>matchers</literal> sections of the <literal>response</literal>.</simpara>
<simpara>Note that, on the producer side, you are also doing TDD. The expectations are expressed
in the form of a test. This test sends a request to our own application with the URL,
headers, and body defined in the contract. It also is expecting precisely defined values
in the response. In other words, you have the <literal>red</literal> part of <literal>red</literal>, <literal>green</literal>, and
<literal>refactor</literal>. It is time to convert the <literal>red</literal> into the <literal>green</literal>.</simpara>
<simpara><emphasis role="strong">Write the missing implementation.</emphasis></simpara>
<simpara>Because you know the expected input and expected output, you can write the missing
implementation:</simpara>
<programlisting language="java" linenumbering="unnumbered">@RequestMapping(value = "/fraudcheck", method = PUT)
public FraudCheckResult fraudCheck(@RequestBody FraudCheck fraudCheck) {
if (amountGreaterThanThreshold(fraudCheck)) {
return new FraudCheckResult(FraudCheckStatus.FRAUD, AMOUNT_TOO_HIGH);
}
return new FraudCheckResult(FraudCheckStatus.OK, NO_REASON);
}</programlisting>
<simpara>When you execute <literal>./mvnw clean install</literal> again, the tests pass. Since the <literal>Spring Cloud
Contract Verifier</literal> plugin adds the tests to the <literal>generated-test-sources</literal>, you can
actually run those tests from your IDE.</simpara>
<simpara><emphasis role="strong">Deploy your app.</emphasis></simpara>
<simpara>Once you finish your work, you can deploy your change. First, merge the branch:</simpara>
<programlisting language="bash" linenumbering="unnumbered">$ git checkout master
$ git merge --no-ff contract-change-pr
$ git push origin master</programlisting>
<simpara>Your CI might run something like <literal>./mvnw clean deploy</literal>, which would publish both the
application and the stub artifacts.</simpara>
</section>
<section xml:id="_consumer_side_loan_issuance_final_step">
<title>Consumer Side (Loan Issuance) Final Step</title>
<simpara>As a developer of the Loan Issuance service (a consumer of the Fraud Detection server):</simpara>
<simpara><emphasis role="strong">Merge branch to master.</emphasis></simpara>
<programlisting language="bash" linenumbering="unnumbered">$ git checkout master
$ git merge --no-ff contract-change-pr</programlisting>
<simpara><emphasis role="strong">Work online.</emphasis></simpara>
<simpara>Now you can disable the offline work for Spring Cloud Contract Stub Runner and indicate
where the repository with your stubs is located. At this moment the stubs of the server
side are automatically downloaded from Nexus/Artifactory. You can set the value of
<literal>stubsMode</literal> to <literal>REMOTE</literal>. The following code shows an example of
achieving the same thing by changing the properties.</simpara>
<programlisting language="yaml" linenumbering="unnumbered">stubrunner:
ids: 'com.example:http-server-dsl:+:stubs:8080'
repositoryRoot: http://repo.spring.io/libs-snapshot</programlisting>
<simpara>That&#8217;s it!</simpara>
</section>
</section>
<section xml:id="_dependencies">
<title>Dependencies</title>
<simpara>The best way to add dependencies is to use the proper <literal>starter</literal> dependency.</simpara>
<simpara>For <literal>stub-runner</literal>, use <literal>spring-cloud-starter-stub-runner</literal>. When you use a plugin, add
<literal>spring-cloud-starter-contract-verifier</literal>.</simpara>
</section>
<section xml:id="_additional_links">
<title>Additional Links</title>
<simpara>Here are some resources related to Spring Cloud Contract Verifier and Stub Runner. Note
that some may be outdated, because the Spring Cloud Contract Verifier project is under
constant development.</simpara>
<section xml:id="_spring_cloud_contract_video">
<title>Spring Cloud Contract video</title>
<simpara>You can check out the video from the Warsaw JUG about Spring Cloud Contract:</simpara>
</section>
<section xml:id="_readings">
<title>Readings</title>
<itemizedlist>
<listitem>
<simpara><link xl:href="http://www.slideshare.net/MarcinGrzejszczak/stick-to-the-rules-consumer-driven-contracts-201507-confitura">Slides from Marcin Grzejszczak&#8217;s talk about Accurest</link></simpara>
</listitem>
<listitem>
<simpara><link xl:href="http://toomuchcoding.com/blog/categories/accurest/">Accurest related articles from Marcin Grzejszczak&#8217;s blog</link></simpara>
</listitem>
<listitem>
<simpara><link xl:href="http://toomuchcoding.com/blog/categories/spring-cloud-contract/">Spring Cloud Contract related articles from Marcin Grzejszczak&#8217;s blog</link></simpara>
</listitem>
<listitem>
<simpara><link xl:href="http://groovy-lang.org/json.html">Groovy docs regarding JSON</link></simpara>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="_samples">
<title>Samples</title>
<simpara>You can find some samples at
<link xl:href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples">samples</link>.</simpara>
</section>
</chapter>
<chapter xml:id="_spring_cloud_contract_faq">
<title>Spring Cloud Contract FAQ</title>
<section xml:id="_why_use_spring_cloud_contract_verifier_and_not_x">
<title>Why use Spring Cloud Contract Verifier and not X ?</title>
<simpara>For the time being Spring Cloud Contract is a JVM based tool. So it could be your first pick when you&#8217;re already creating
software for the JVM. This project has a lot of really interesting features but especially quite a few of them definitely make
Spring Cloud Contract Verifier stand out on the "market" of Consumer Driven Contract (CDC) tooling. Out of many the most interesting are:</simpara>
<itemizedlist>
<listitem>
<simpara>Possibility to do CDC with messaging</simpara>
</listitem>
<listitem>
<simpara>Clear and easy to use, statically typed DSL</simpara>
</listitem>
<listitem>
<simpara>Possibility to copy paste your current JSON file to the contract and only edit its elements</simpara>
</listitem>
<listitem>
<simpara>Automatic generation of tests from the defined Contract</simpara>
</listitem>
<listitem>
<simpara>Stub Runner functionality - the stubs are automatically downloaded at runtime from Nexus / Artifactory</simpara>
</listitem>
<listitem>
<simpara>Spring Cloud integration - no discovery service is needed for integration tests</simpara>
</listitem>
<listitem>
<simpara>Spring Cloud Contract integrates with Pact out of the box and provides easy hooks to extend its functionality</simpara>
</listitem>
<listitem>
<simpara>Via Docker adds support for any language &amp; framework used</simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="_i_dont_want_to_write_a_contract_in_groovy">
<title>I don&#8217;t want to write a contract in Groovy!</title>
<simpara>No problem. You can write a contract in YAML!</simpara>
</section>
<section xml:id="_what_is_this_valueconsumer_producer">
<title>What is this value(consumer(), producer()) ?</title>
<simpara>One of the biggest challenges related to stubs is their reusability. Only if they can be vastly used, will they serve their purpose.
What typically makes that difficult are the hard-coded values of request / response elements. For example dates or ids.
Imagine the following JSON request</simpara>
<programlisting language="json" linenumbering="unnumbered">{
"time" : "2016-10-10 20:10:15",
"id" : "9febab1c-6f36-4a0b-88d6-3b6a6d81cd4a",
"body" : "foo"
}</programlisting>
<simpara>and JSON response</simpara>
<programlisting language="json" linenumbering="unnumbered">{
"time" : "2016-10-10 21:10:15",
"id" : "c4231e1f-3ca9-48d3-b7e7-567d55f0d051",
"body" : "bar"
}</programlisting>
<simpara>Imagine the pain required to set proper value of the <literal>time</literal> field (let&#8217;s assume that this content is generated by the
database) by changing the clock in the system or providing stub implementations of data providers. The same is related
to the field called <literal>id</literal>. Will you create a stubbed implementation of UUID generator? Makes little sense&#8230;&#8203;</simpara>
<simpara>So as a consumer you would like to send a request that matches any form of a time or any UUID. That way your system
will work as usual - will generate data and you won&#8217;t have to stub anything out. Let&#8217;s assume that in case of the aforementioned
JSON the most important part is the <literal>body</literal> field. You can focus on that and provide matching for other fields. In other words
you would like the stub to work like this:</simpara>
<programlisting language="json" linenumbering="unnumbered">{
"time" : "SOMETHING THAT MATCHES TIME",
"id" : "SOMETHING THAT MATCHES UUID",
"body" : "foo"
}</programlisting>
<simpara>As far as the response goes as a consumer you need a concrete value that you can operate on. So such a JSON is valid</simpara>
<programlisting language="json" linenumbering="unnumbered">{
"time" : "2016-10-10 21:10:15",
"id" : "c4231e1f-3ca9-48d3-b7e7-567d55f0d051",
"body" : "bar"
}</programlisting>
<simpara>As you could see in the previous sections we generate tests from contracts. So from the producer&#8217;s side the situation looks
much different. We&#8217;re parsing the provided contract and in the test we want to send a real request to your endpoints.
So for the case of a producer for the request we can&#8217;t have any sort of matching. We need concrete values that the
producer&#8217;s backend can work on. Such a JSON would be a valid one:</simpara>
<programlisting language="json" linenumbering="unnumbered">{
"time" : "2016-10-10 20:10:15",
"id" : "9febab1c-6f36-4a0b-88d6-3b6a6d81cd4a",
"body" : "foo"
}</programlisting>
<simpara>On the other hand from the point of view of the validity of the contract the response doesn&#8217;t necessarily have to
contain concrete values of <literal>time</literal> or <literal>id</literal>. Let&#8217;s say that you generate those on the producer side - again, you&#8217;d
have to do a lot of stubbing to ensure that you always return the same values. That&#8217;s why from the producer&#8217;s side
what you might want is the following response:</simpara>
<programlisting language="json" linenumbering="unnumbered">{
"time" : "SOMETHING THAT MATCHES TIME",
"id" : "SOMETHING THAT MATCHES UUID",
"body" : "bar"
}</programlisting>
<simpara>How can you then provide one time a matcher for the consumer and a concrete value for the producer and vice versa?
In Spring Cloud Contract we&#8217;re allowing you to provide a <emphasis role="strong">dynamic value</emphasis>. That means that it can differ for both
sides of the communication. You can pass the values:</simpara>
<simpara>Either via the <literal>value</literal> method</simpara>
<programlisting language="groovy" linenumbering="unnumbered">value(consumer(...), producer(...))
value(stub(...), test(...))
value(client(...), server(...))</programlisting>
<simpara>or using the <literal>$()</literal> method</simpara>
<programlisting language="groovy" linenumbering="unnumbered">$(consumer(...), producer(...))
$(stub(...), test(...))
$(client(...), server(...))</programlisting>
<simpara>You can read more about this in the <xref linkend="contract-dsl"/> section.</simpara>
<simpara>Calling <literal>value()</literal> or <literal>$()</literal> tells Spring Cloud Contract that you will be passing a dynamic value.
Inside the <literal>consumer()</literal> method you pass the value that should be used on the consumer side (in the generated stub).
Inside the <literal>producer()</literal> method you pass the value that should be used on the producer side (in the generated test).</simpara>
<tip>
<simpara>If on one side you have passed the regular expression and you haven&#8217;t passed the other, then the
other side will get auto-generated.</simpara>
</tip>
<simpara>Most often you will use that method together with the <literal>regex</literal> helper method. E.g. <literal>consumer(regex('[0-9]{10}'))</literal>.</simpara>
<simpara>To sum it up the contract for the aforementioned scenario would look more or less like this (the regular expression
for time and UUID are simplified and most likely invalid but we want to keep things very simple in this example):</simpara>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
request {
method 'GET'
url '/someUrl'
body([
time : value(consumer(regex('[0-9]{4}-[0-9]{2}-[0-9]{2} [0-2][0-9]-[0-5][0-9]-[0-5][0-9]')),
id: value(consumer(regex('[0-9a-zA-z]{8}-[0-9a-zA-z]{4}-[0-9a-zA-z]{4}-[0-9a-zA-z]{12}'))
body: "foo"
])
}
response {
status OK()
body([
time : value(producer(regex('[0-9]{4}-[0-9]{2}-[0-9]{2} [0-2][0-9]-[0-5][0-9]-[0-5][0-9]')),
id: value([producer(regex('[0-9a-zA-z]{8}-[0-9a-zA-z]{4}-[0-9a-zA-z]{4}-[0-9a-zA-z]{12}'))
body: "bar"
])
}
}</programlisting>
<important>
<simpara>Please read the <link xl:href="http://groovy-lang.org/json.html">Groovy docs related to JSON</link> to understand how to
properly structure the request / response bodies.</simpara>
</important>
</section>
<section xml:id="_how_to_do_stubs_versioning">
<title>How to do Stubs versioning?</title>
<section xml:id="_api_versioning">
<title>API Versioning</title>
<simpara>Let&#8217;s try to answer a question what versioning really means. If you&#8217;re referring to the API version then there are
different approaches.</simpara>
<itemizedlist>
<listitem>
<simpara>use Hypermedia, links and do not version your API by any means</simpara>
</listitem>
<listitem>
<simpara>pass versions through headers / urls</simpara>
</listitem>
</itemizedlist>
<simpara>I will not try to answer a question which approach is better. Whatever suits your needs and allows you to generate
business value should be picked.</simpara>
<simpara>Let&#8217;s assume that you do version your API. In that case you should provide as many contracts as many versions you support.
You can create a subfolder for every version or append it to the contract name - whatever suits you more.</simpara>
</section>
<section xml:id="_jar_versioning">
<title>JAR versioning</title>
<simpara>If by versioning you mean the version of the JAR that contains the stubs then there are essentially two main approaches.</simpara>
<simpara>Let&#8217;s assume that you&#8217;re doing Continuous Delivery / Deployment which means that you&#8217;re generating a new version of
the jar each time you go through the pipeline and that jar can go to production at any time. For example your jar version
looks like this (it got built on the 20.10.2016 at 20:15:21) :</simpara>
<programlisting language="groovy" linenumbering="unnumbered">1.0.0.20161020-201521-RELEASE</programlisting>
<simpara>In that case your generated stub jar will look like this.</simpara>
<programlisting language="groovy" linenumbering="unnumbered">1.0.0.20161020-201521-RELEASE-stubs.jar</programlisting>
<simpara>In this case you should inside your <literal>application.yml</literal> or <literal>@AutoConfigureStubRunner</literal> when referencing stubs provide the
latest version of the stubs. You can do that by passing the <literal>+</literal> sign. Example</simpara>
<programlisting language="java" linenumbering="unnumbered">@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:8080"})</programlisting>
<simpara>If the versioning however is fixed (e.g. <literal>1.0.4.RELEASE</literal> or <literal>2.1.1</literal>) then you have to set the concrete value of the jar
version. Example for 2.1.1.</simpara>
<programlisting language="java" linenumbering="unnumbered">@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:2.1.1:stubs:8080"})</programlisting>
</section>
<section xml:id="_dev_or_prod_stubs">
<title>Dev or prod stubs</title>
<simpara>You can manipulate the classifier to run the tests against current development version of the stubs of other services
or the ones that were deployed to production. If you alter your build to deploy the stubs with the <literal>prod-stubs</literal> classifier
once you reach production deployment then you can run tests in one case with dev stubs and one with prod stubs.</simpara>
<simpara>Example of tests using development version of stubs</simpara>
<programlisting language="java" linenumbering="unnumbered">@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:8080"})</programlisting>
<simpara>Example of tests using production version of stubs</simpara>
<programlisting language="java" linenumbering="unnumbered">@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:prod-stubs:8080"})</programlisting>
<simpara>You can pass those values also via properties from your deployment pipeline.</simpara>
</section>
</section>
<section xml:id="_common_repo_with_contracts">
<title>Common repo with contracts</title>
<simpara>Another way of storing contracts other than having them with the producer is keeping them in a common place.
It can be related to security issues where the consumers can&#8217;t clone the producer&#8217;s code. Also if you keep
contracts in a single place then you, as a producer, will know how many consumers you have and which
consumer you will break with your local changes.</simpara>
<section xml:id="_repo_structure">
<title>Repo structure</title>
<simpara>Let&#8217;s assume that we have a producer with coordinates <literal>com.example:server</literal> and 3 consumers: <literal>client1</literal>,
<literal>client2</literal>, <literal>client3</literal>. Then in the repository with common contracts you would have the following setup
(which you can checkout <link xl:href="https://github.com/spring-cloud/spring-cloud-contract/tree/master/samples/standalone/contracts">here</link>):</simpara>
<programlisting language="bash" linenumbering="unnumbered">├── com
│   └── example
│   └── server
│   ├── client1
│   │   └── expectation.groovy
│   ├── client2
│   │   └── expectation.groovy
│   ├── client3
│   │   └── expectation.groovy
│   └── pom.xml
├── mvnw
├── mvnw.cmd
├── pom.xml
└── src
└── assembly
└── contracts.xml</programlisting>
<simpara>As you can see under the slash-delimited groupid <literal>/</literal> artifact id folder (<literal>com/example/server</literal>) you have
expectations of the 3 consumers (<literal>client1</literal>, <literal>client2</literal> and <literal>client3</literal>). Expectations are the standard Groovy DSL
contract files as described throughout this documentation. This repository has to produce a JAR file that maps
one to one to the contents of the repo.</simpara>
<simpara>Example of a <literal>pom.xml</literal> inside the <literal>server</literal> folder.</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"&gt;
&lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
&lt;groupId&gt;com.example&lt;/groupId&gt;
&lt;artifactId&gt;server&lt;/artifactId&gt;
&lt;version&gt;0.0.1-SNAPSHOT&lt;/version&gt;
&lt;name&gt;Server Stubs&lt;/name&gt;
&lt;description&gt;POM used to install locally stubs for consumer side&lt;/description&gt;
&lt;parent&gt;
&lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
&lt;artifactId&gt;spring-boot-starter-parent&lt;/artifactId&gt;
&lt;version&gt;2.1.1.RELEASE&lt;/version&gt;
&lt;relativePath /&gt;
&lt;/parent&gt;
&lt;properties&gt;
&lt;project.build.sourceEncoding&gt;UTF-8&lt;/project.build.sourceEncoding&gt;
&lt;java.version&gt;1.8&lt;/java.version&gt;
&lt;spring-cloud-contract.version&gt;2.1.0.BUILD-SNAPSHOT&lt;/spring-cloud-contract.version&gt;
&lt;spring-cloud-release.version&gt;Greenwich.BUILD-SNAPSHOT&lt;/spring-cloud-release.version&gt;
&lt;excludeBuildFolders&gt;true&lt;/excludeBuildFolders&gt;
&lt;/properties&gt;
&lt;dependencyManagement&gt;
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-dependencies&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-release.version}&lt;/version&gt;
&lt;type&gt;pom&lt;/type&gt;
&lt;scope&gt;import&lt;/scope&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;/dependencyManagement&gt;
&lt;build&gt;
&lt;plugins&gt;
&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;configuration&gt;
&lt;!-- By default it would search under src/test/resources/ --&gt;
&lt;contractsDirectory&gt;${project.basedir}&lt;/contractsDirectory&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;
&lt;/plugins&gt;
&lt;/build&gt;
&lt;repositories&gt;
&lt;repository&gt;
&lt;id&gt;spring-snapshots&lt;/id&gt;
&lt;name&gt;Spring Snapshots&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/snapshot&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;true&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/repository&gt;
&lt;repository&gt;
&lt;id&gt;spring-milestones&lt;/id&gt;
&lt;name&gt;Spring Milestones&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/milestone&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/repository&gt;
&lt;repository&gt;
&lt;id&gt;spring-releases&lt;/id&gt;
&lt;name&gt;Spring Releases&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/release&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/repository&gt;
&lt;/repositories&gt;
&lt;pluginRepositories&gt;
&lt;pluginRepository&gt;
&lt;id&gt;spring-snapshots&lt;/id&gt;
&lt;name&gt;Spring Snapshots&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/snapshot&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;true&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/pluginRepository&gt;
&lt;pluginRepository&gt;
&lt;id&gt;spring-milestones&lt;/id&gt;
&lt;name&gt;Spring Milestones&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/milestone&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/pluginRepository&gt;
&lt;pluginRepository&gt;
&lt;id&gt;spring-releases&lt;/id&gt;
&lt;name&gt;Spring Releases&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/release&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/pluginRepository&gt;
&lt;/pluginRepositories&gt;
&lt;/project&gt;</programlisting>
<simpara>As you can see there are no dependencies other than the Spring Cloud Contract Maven Plugin.
Those poms are necessary for the consumer side to run <literal>mvn clean install -DskipTests</literal> to locally install
stubs of the producer project.</simpara>
<simpara>The <literal>pom.xml</literal> in the root folder can look like this:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"&gt;
&lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
&lt;groupId&gt;com.example.standalone&lt;/groupId&gt;
&lt;artifactId&gt;contracts&lt;/artifactId&gt;
&lt;version&gt;0.0.1-SNAPSHOT&lt;/version&gt;
&lt;name&gt;Contracts&lt;/name&gt;
&lt;description&gt;Contains all the Spring Cloud Contracts, well, contracts. JAR used by the producers to generate tests and stubs&lt;/description&gt;
&lt;properties&gt;
&lt;project.build.sourceEncoding&gt;UTF-8&lt;/project.build.sourceEncoding&gt;
&lt;/properties&gt;
&lt;build&gt;
&lt;plugins&gt;
&lt;plugin&gt;
&lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
&lt;artifactId&gt;maven-assembly-plugin&lt;/artifactId&gt;
&lt;executions&gt;
&lt;execution&gt;
&lt;id&gt;contracts&lt;/id&gt;
&lt;phase&gt;prepare-package&lt;/phase&gt;
&lt;goals&gt;
&lt;goal&gt;single&lt;/goal&gt;
&lt;/goals&gt;
&lt;configuration&gt;
&lt;attach&gt;true&lt;/attach&gt;
&lt;descriptor&gt;${basedir}/src/assembly/contracts.xml&lt;/descriptor&gt;
&lt;!-- If you want an explicit classifier remove the following line --&gt;
&lt;appendAssemblyId&gt;false&lt;/appendAssemblyId&gt;
&lt;/configuration&gt;
&lt;/execution&gt;
&lt;/executions&gt;
&lt;/plugin&gt;
&lt;/plugins&gt;
&lt;/build&gt;
&lt;/project&gt;</programlisting>
<simpara>It&#8217;s using the assembly plugin in order to build the JAR with all the contracts. Example of such setup is here:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd"&gt;
&lt;id&gt;project&lt;/id&gt;
&lt;formats&gt;
&lt;format&gt;jar&lt;/format&gt;
&lt;/formats&gt;
&lt;includeBaseDirectory&gt;false&lt;/includeBaseDirectory&gt;
&lt;fileSets&gt;
&lt;fileSet&gt;
&lt;directory&gt;${project.basedir}&lt;/directory&gt;
&lt;outputDirectory&gt;/&lt;/outputDirectory&gt;
&lt;useDefaultExcludes&gt;true&lt;/useDefaultExcludes&gt;
&lt;excludes&gt;
&lt;exclude&gt;**/${project.build.directory}/**&lt;/exclude&gt;
&lt;exclude&gt;mvnw&lt;/exclude&gt;
&lt;exclude&gt;mvnw.cmd&lt;/exclude&gt;
&lt;exclude&gt;.mvn/**&lt;/exclude&gt;
&lt;exclude&gt;src/**&lt;/exclude&gt;
&lt;/excludes&gt;
&lt;/fileSet&gt;
&lt;/fileSets&gt;
&lt;/assembly&gt;</programlisting>
</section>
<section xml:id="_workflow">
<title>Workflow</title>
<simpara>The workflow would look similar to the one presented in the <literal>Step by step guide to CDC</literal>. The only difference
is that the producer doesn&#8217;t own the contracts anymore. So the consumer and the producer have to work on
common contracts in a common repository.</simpara>
</section>
<section xml:id="_consumer">
<title>Consumer</title>
<simpara>When the <emphasis role="strong">consumer</emphasis> wants to work on the contracts offline, instead of cloning the producer code, the
consumer team clones the common repository, goes to the required producer&#8217;s folder (e.g. <literal>com/example/server</literal>)
and runs <literal>mvn clean install -DskipTests</literal> to install locally the stubs converted from the contracts.</simpara>
<tip>
<simpara>You need to have <link xl:href="http://maven.apache.org/download.cgi">Maven installed locally</link></simpara>
</tip>
</section>
<section xml:id="_producer">
<title>Producer</title>
<simpara>As a <emphasis role="strong">producer</emphasis> it&#8217;s enough to alter the Spring Cloud Contract Verifier to provide the URL and the dependency
of the JAR containing the contracts:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;configuration&gt;
&lt;contractsMode&gt;REMOTE&lt;/contractsMode&gt;
&lt;contractsRepositoryUrl&gt;http://link/to/your/nexus/or/artifactory/or/sth&lt;/contractsRepositoryUrl&gt;
&lt;contractDependency&gt;
&lt;groupId&gt;com.example.standalone&lt;/groupId&gt;
&lt;artifactId&gt;contracts&lt;/artifactId&gt;
&lt;/contractDependency&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</programlisting>
<simpara>With this setup the JAR with groupid <literal>com.example.standalone</literal> and artifactid <literal>contracts</literal> will be downloaded
from <literal><link xl:href="http://link/to/your/nexus/or/artifactory/or/sth">http://link/to/your/nexus/or/artifactory/or/sth</link></literal>. It will be then unpacked in a local temporary folder
and contracts present under the <literal>com/example/server</literal> will be picked as the ones used to generate the
tests and the stubs. Due to this convention the producer team will know which consumer teams will be broken
when some incompatible changes are done.</simpara>
<simpara>The rest of the flow looks the same.</simpara>
</section>
<section xml:id="_how_can_i_define_messaging_contracts_per_topic_not_per_producer">
<title>How can I define messaging contracts per topic not per producer?</title>
<simpara>To avoid messaging contracts duplication in the common repo, when few producers writing messages to one topic,
we could create the structure when the rest contracts would be placed in a folder per producer and messaging
contracts in the folder per topic.</simpara>
<section xml:id="_for_maven_project">
<title>For Maven Project</title>
<simpara>To make it possible to work on the producer side we should specify an inclusion pattern for
filtering common repository jar by messaging topics we are interested in. <literal><literal>includedFiles</literal></literal> property of <literal><literal>Maven Spring Cloud Contract plugin</literal></literal>
allows us to do that. Also <literal><literal>contractsPath</literal></literal> need to be specified since the default path would be the common repository <literal><literal>groupid/artifactid</literal></literal>.</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;configuration&gt;
&lt;contractsMode&gt;REMOTE&lt;/contractsMode&gt;
&lt;contractsRepositoryUrl&gt;http://link/to/your/nexus/or/artifactory/or/sth&lt;/contractsRepositoryUrl&gt;
&lt;contractDependency&gt;
&lt;groupId&gt;com.example&lt;/groupId&gt;
&lt;artifactId&gt;common-repo-with-contracts&lt;/artifactId&gt;
&lt;version&gt;+&lt;/version&gt;
&lt;/contractDependency&gt;
&lt;contractsPath&gt;/&lt;/contractsPath&gt;
&lt;baseClassMappings&gt;
&lt;baseClassMapping&gt;
&lt;contractPackageRegex&gt;.*messaging.*&lt;/contractPackageRegex&gt;
&lt;baseClassFQN&gt;com.example.services.MessagingBase&lt;/baseClassFQN&gt;
&lt;/baseClassMapping&gt;
&lt;baseClassMapping&gt;
&lt;contractPackageRegex&gt;.*rest.*&lt;/contractPackageRegex&gt;
&lt;baseClassFQN&gt;com.example.services.TestBase&lt;/baseClassFQN&gt;
&lt;/baseClassMapping&gt;
&lt;/baseClassMappings&gt;
&lt;includedFiles&gt;
&lt;includedFile&gt;**/${project.artifactId}/**&lt;/includedFile&gt;
&lt;includedFile&gt;**/${first-topic}/**&lt;/includedFile&gt;
&lt;includedFile&gt;**/${second-topic}/**&lt;/includedFile&gt;
&lt;/includedFiles&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</programlisting>
</section>
<section xml:id="_for_gradle_project">
<title>For Gradle Project</title>
<itemizedlist>
<listitem>
<simpara>Add a custom configuration for the common-repo dependency:</simpara>
</listitem>
</itemizedlist>
<programlisting language="groovy" linenumbering="unnumbered">ext {
conractsGroupId = "com.example"
contractsArtifactId = "common-repo"
contractsVersion = "1.2.3"
}
configurations {
contracts {
transitive = false
}
}</programlisting>
<itemizedlist>
<listitem>
<simpara>Add the common-repo dependency to your classpath:</simpara>
</listitem>
</itemizedlist>
<programlisting language="groovy" linenumbering="unnumbered">dependencies {
contracts "${conractsGroupId}:${contractsArtifactId}:${contractsVersion}"
testCompile "${conractsGroupId}:${contractsArtifactId}:${contractsVersion}"
}</programlisting>
<itemizedlist>
<listitem>
<simpara>Download the dependency to an appropriate folder:</simpara>
</listitem>
</itemizedlist>
<programlisting language="groovy" linenumbering="unnumbered">task getContracts(type: Copy) {
from configurations.contracts
into new File(project.buildDir, "downloadedContracts")
}</programlisting>
<itemizedlist>
<listitem>
<simpara>Unzip JAR:</simpara>
</listitem>
</itemizedlist>
<programlisting language="groovy" linenumbering="unnumbered">task unzipContracts(type: Copy) {
def zipFile = new File(project.buildDir, "downloadedContracts/${contractsArtifactId}-${contractsVersion}.jar")
def outputDir = file("${buildDir}/unpackedContracts")
from zipTree(zipFile)
into outputDir
}</programlisting>
<itemizedlist>
<listitem>
<simpara>Cleanup unused contracts:</simpara>
</listitem>
</itemizedlist>
<programlisting language="groovy" linenumbering="unnumbered">task deleteUnwantedContracts(type: Delete) {
delete fileTree(dir: "${buildDir}/unpackedContracts",
include: "**/*",
excludes: [
"**/${project.name}/**"",
"**/${first-topic}/**",
"**/${second-topic}/**"])
}</programlisting>
<itemizedlist>
<listitem>
<simpara>Create task dependencies:</simpara>
</listitem>
</itemizedlist>
<programlisting language="groovy" linenumbering="unnumbered">unzipContracts.dependsOn("getContracts")
deleteUnwantedContracts.dependsOn("unzipContracts")
build.dependsOn("deleteUnwantedContracts")</programlisting>
<itemizedlist>
<listitem>
<simpara>Configure plugin by specifying the directory containing contracts using <literal>contractsDslDir</literal> property</simpara>
</listitem>
</itemizedlist>
<programlisting language="groovy" linenumbering="unnumbered">contracts {
contractsDslDir = new File("${buildDir}/unpackedContracts")
}</programlisting>
</section>
</section>
</section>
<section xml:id="_do_i_need_a_binary_storage_cant_i_use_git">
<title>Do I need a Binary Storage? Can&#8217;t I use Git?</title>
<simpara>In the polyglot world, there are languages that don&#8217;t use binary storages like
Artifactory or Nexus. Starting from Spring Cloud Contract version 2.0.0 we provide
mechanisms to store contracts and stubs in a SCM repository. Currently the
only supported SCM is Git.</simpara>
<simpara>The repository would have to the following setup
(which you can checkout <link xl:href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/2.1.x/contracts_git/">here</link>):</simpara>
<screen>.
└── META-INF
└── com.example
└── beer-api-producer-git
└── 0.0.1-SNAPSHOT
├── contracts
│   └── beer-api-consumer
│   ├── messaging
│   │   ├── shouldSendAcceptedVerification.groovy
│   │   └── shouldSendRejectedVerification.groovy
│   └── rest
│   ├── shouldGrantABeerIfOldEnough.groovy
│   └── shouldRejectABeerIfTooYoung.groovy
└── mappings
└── beer-api-consumer
└── rest
├── shouldGrantABeerIfOldEnough.json
└── shouldRejectABeerIfTooYoung.json</screen>
<simpara>Under <literal>META-INF</literal> folder:</simpara>
<itemizedlist>
<listitem>
<simpara>we group applications via <literal>groupId</literal> (e.g. <literal>com.example</literal>)</simpara>
</listitem>
<listitem>
<simpara>then each application is represented via the <literal>artifactId</literal> (e.g. <literal>beer-api-producer-git</literal>)</simpara>
</listitem>
<listitem>
<simpara>next, the version of the application. The version is mandatory! (e.g. <literal>0.0.1-SNAPSHOT</literal>)</simpara>
</listitem>
<listitem>
<simpara>finally, there are two folders:</simpara>
<itemizedlist>
<listitem>
<simpara><literal>contracts</literal> - the good practice is to store the contracts required by each
consumer in the folder with the consumer name (e.g. <literal>beer-api-consumer</literal>). That way you
can use the <literal>stubs-per-consumer</literal> feature. Further directory structure is arbitrary.</simpara>
</listitem>
<listitem>
<simpara><literal>mappings</literal> - in this folder the Maven / Gradle Spring Cloud Contract plugins will push
the stub server mappings. On the consumer side, Stub Runner will scan this folder
to start stub servers with stub definitions. The folder structure will be a copy
of the one created in the <literal>contracts</literal> subfolder.</simpara>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<section xml:id="_protocol_convention">
<title>Protocol convention</title>
<simpara>In order to control the type and location of the source of contracts (whether it&#8217;s
a binary storage or an SCM repository), you can use the protocol in the URL of
the repository. Spring Cloud Contract iterates over registered protocol resolvers
and tries to fetch the contracts (via a plugin) or stubs (via Stub Runner).</simpara>
<simpara>For the SCM functionality, currently, we support the Git repository. To use it,
in the property, where the repository URL needs to be placed you just have to prefix
the connection URL with <literal>git://</literal>. Here you can find a couple of examples:</simpara>
<screen>git://file:///foo/bar
git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git
git://git@github.com:spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git</screen>
</section>
<section xml:id="_producer_2">
<title>Producer</title>
<simpara>For the producer, to use the SCM approach, we can reuse the
same mechanism we use for external contracts. We route Spring Cloud Contract
to use the SCM implementation via the URL that contains
the <literal>git://</literal> protocol.</simpara>
<important>
<simpara>You have to manually add the <literal>pushStubsToScm</literal>
goal in Maven or execute (bind) the <literal>pushStubsToScm</literal> task in
Gradle. We don&#8217;t push stubs to <literal>origin</literal> of your git
repository out of the box.</simpara>
</important>
<formalpara>
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;configuration&gt;
&lt;!-- Base class mappings etc. --&gt;
&lt;!-- We want to pick contracts from a Git repository --&gt;
&lt;contractsRepositoryUrl&gt;git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git&lt;/contractsRepositoryUrl&gt;
&lt;!-- We reuse the contract dependency section to set up the path
to the folder that contains the contract definitions. In our case the
path will be /groupId/artifactId/version/contracts --&gt;
&lt;contractDependency&gt;
&lt;groupId&gt;${project.groupId}&lt;/groupId&gt;
&lt;artifactId&gt;${project.artifactId}&lt;/artifactId&gt;
&lt;version&gt;${project.version}&lt;/version&gt;
&lt;/contractDependency&gt;
&lt;!-- The contracts mode can't be classpath --&gt;
&lt;contractsMode&gt;REMOTE&lt;/contractsMode&gt;
&lt;/configuration&gt;
&lt;executions&gt;
&lt;execution&gt;
&lt;phase&gt;package&lt;/phase&gt;
&lt;goals&gt;
&lt;!-- By default we will not push the stubs back to SCM,
you have to explicitly add it as a goal --&gt;
&lt;goal&gt;pushStubsToScm&lt;/goal&gt;
&lt;/goals&gt;
&lt;/execution&gt;
&lt;/executions&gt;
&lt;/plugin&gt;</programlisting>
</para>
</formalpara>
<formalpara>
<title>Gradle</title>
<para>
<programlisting language="gradle" linenumbering="unnumbered">contracts {
// We want to pick contracts from a Git repository
contractDependency {
stringNotation = "${project.group}:${project.name}:${project.version}"
}
/*
We reuse the contract dependency section to set up the path
to the folder that contains the contract definitions. In our case the
path will be /groupId/artifactId/version/contracts
*/
contractRepository {
repositoryUrl = "git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git"
}
// The mode can't be classpath
contractsMode = "REMOTE"
// Base class mappings etc.
}
/*
In this scenario we want to publish stubs to SCM whenever
the `publish` task is executed
*/
publish.dependsOn("publishStubsToScm")</programlisting>
</para>
</formalpara>
<simpara>With such a setup:</simpara>
<itemizedlist>
<listitem>
<simpara>Git project will be cloned to a temporary directory</simpara>
</listitem>
<listitem>
<simpara>The SCM stub downloader will go to <literal>META-INF/groupId/artifactId/version/contracts</literal> folder
to find contracts. E.g. for <literal>com.example:foo:1.0.0</literal> the path would be
<literal>META-INF/com.example/foo/1.0.0/contracts</literal></simpara>
</listitem>
<listitem>
<simpara>Tests will be generated from the contracts</simpara>
</listitem>
<listitem>
<simpara>Stubs will be created from the contracts</simpara>
</listitem>
<listitem>
<simpara>Once the tests pass, the stubs will be committed in the cloned repository</simpara>
</listitem>
<listitem>
<simpara>Finally, a push will be done to that repo&#8217;s <literal>origin</literal></simpara>
</listitem>
</itemizedlist>
<section xml:id="_keeping_contracts_with_the_producer_and_stubs_in_an_external_repository">
<title>Keeping contracts with the producer and stubs in an external repository</title>
<simpara>It is also possible to keep the contracts in the producer repository, but keep the stubs in an external git repo.
This is most useful when you want to use the base consumer-producer collaboration flow, but do not have a possibility to
use an artifact repository for storing the stubs.</simpara>
<simpara>In order to do that, use the usual producer setup, and then add the <literal>pushStubsToScm</literal> goal and set
<literal>contractsRepositoryUrl</literal> to the repository where you want to keep the stubs.</simpara>
</section>
</section>
<section xml:id="_consumer_2">
<title>Consumer</title>
<simpara>On the consumer side when passing the <literal>repositoryRoot</literal> parameter,
either from the <literal>@AutoConfigureStubRunner</literal> annotation, the
JUnit rule, JUnit 5 extension or properties, it&#8217;s enough to pass the URL of the
SCM repository, prefixed with the protocol. For example</simpara>
<programlisting language="java" linenumbering="unnumbered">@AutoConfigureStubRunner(
stubsMode="REMOTE",
repositoryRoot="git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git",
ids="com.example:bookstore:0.0.1.RELEASE"
)</programlisting>
<simpara>With such a setup:</simpara>
<itemizedlist>
<listitem>
<simpara>Git project will be cloned to a temporary directory</simpara>
</listitem>
<listitem>
<simpara>The SCM stub downloader will go to <literal>META-INF/groupId/artifactId/version/</literal> folder
to find stub definitions and contracts. E.g. for <literal>com.example:foo:1.0.0</literal> the path would be
<literal>META-INF/com.example/foo/1.0.0/</literal></simpara>
</listitem>
<listitem>
<simpara>Stub servers will be started and fed with mappings</simpara>
</listitem>
<listitem>
<simpara>Messaging definitions will be read and used in the messaging tests</simpara>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="_can_i_use_the_pact_broker">
<title>Can I use the Pact Broker?</title>
<simpara>When using <link xl:href="http://pact.io/">Pact</link> you can use the <link xl:href="https://github.com/pact-foundation/pact_broker">Pact Broker</link>
to store and share Pact definitions. Starting from Spring Cloud Contract
2.0.0 one can fetch Pact files from the Pact Broker to generate
tests and stubs.</simpara>
<simpara>As a prerequisite the Pact Converter and Pact Stub Downloader
are required. You have to add them via the <literal>spring-cloud-contract-pact</literal> dependency.
You can read more about it in the <xref linkend="pact-converter"/> section.</simpara>
<important>
<simpara>Pact follows the Consumer Contract convention. That means
that the Consumer creates the Pact definitions first, then
shares the files with the Producer. Those expectations are generated
from the Consumer&#8217;s code and can break the Producer if the expectations
are not met.</simpara>
</important>
<section xml:id="_pact_consumer">
<title>Pact Consumer</title>
<simpara>The consumer uses Pact framework to generate Pact files. The
Pact files are sent to the Pact Broker. An example of such
setup can be found <link xl:href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/2.1.x/consumer_pact">here</link>.</simpara>
</section>
<section xml:id="_producer_3">
<title>Producer</title>
<simpara>For the producer, to use the Pact files from the Pact Broker, we can reuse the
same mechanism we use for external contracts. We route Spring Cloud Contract
to use the Pact implementation via the URL that contains
the <literal>pact://</literal> protocol. It&#8217;s enough to pass the URL to the
Pact Broker. An example of such setup can be found <link xl:href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/2.1.x/producer_pact">here</link>.</simpara>
<formalpara>
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;configuration&gt;
&lt;!-- Base class mappings etc. --&gt;
&lt;!-- We want to pick contracts from a Git repository --&gt;
&lt;contractsRepositoryUrl&gt;pact://http://localhost:8085&lt;/contractsRepositoryUrl&gt;
&lt;!-- We reuse the contract dependency section to set up the path
to the folder that contains the contract definitions. In our case the
path will be /groupId/artifactId/version/contracts --&gt;
&lt;contractDependency&gt;
&lt;groupId&gt;${project.groupId}&lt;/groupId&gt;
&lt;artifactId&gt;${project.artifactId}&lt;/artifactId&gt;
&lt;!-- When + is passed, a latest tag will be applied when fetching pacts --&gt;
&lt;version&gt;+&lt;/version&gt;
&lt;/contractDependency&gt;
&lt;!-- The contracts mode can't be classpath --&gt;
&lt;contractsMode&gt;REMOTE&lt;/contractsMode&gt;
&lt;/configuration&gt;
&lt;!-- Don't forget to add spring-cloud-contract-pact to the classpath! --&gt;
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-pact&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;/plugin&gt;</programlisting>
</para>
</formalpara>
<formalpara>
<title>Gradle</title>
<para>
<programlisting language="gradle" linenumbering="unnumbered">buildscript {
repositories {
//...
}
dependencies {
// ...
// Don't forget to add spring-cloud-contract-pact to the classpath!
classpath "org.springframework.cloud:spring-cloud-contract-pact:${contractVersion}"
}
}
contracts {
// When + is passed, a latest tag will be applied when fetching pacts
contractDependency {
stringNotation = "${project.group}:${project.name}:+"
}
contractRepository {
repositoryUrl = "pact://http://localhost:8085"
}
// The mode can't be classpath
contractsMode = "REMOTE"
// Base class mappings etc.
}</programlisting>
</para>
</formalpara>
<simpara>With such a setup:</simpara>
<itemizedlist>
<listitem>
<simpara>Pact files will be downloaded from the Pact Broker</simpara>
</listitem>
<listitem>
<simpara>Spring Cloud Contract will convert the Pact files into tests and stubs</simpara>
</listitem>
<listitem>
<simpara>The JAR with the stubs gets automatically created as usual</simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="_pact_consumer_producer_contract_approach">
<title>Pact Consumer (Producer Contract approach)</title>
<simpara>In the scenario where you don&#8217;t want to do Consumer Contract approach
(for every single consumer define the expectations) but you&#8217;d prefer
to do Producer Contracts (the producer provides the contracts and
publishes stubs), it&#8217;s enough to use Spring Cloud Contract with
Stub Runner option. An example of such setup can be found <link xl:href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/2.1.x/consumer_pact_stubrunner">here</link>.</simpara>
<simpara>First, remember to add Stub Runner and Spring Cloud Contract Pact module
as test dependencies.</simpara>
<formalpara>
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependencyManagement&gt;
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-dependencies&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud.version}&lt;/version&gt;
&lt;type&gt;pom&lt;/type&gt;
&lt;scope&gt;import&lt;/scope&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;/dependencyManagement&gt;
&lt;!-- Don't forget to add spring-cloud-contract-pact to the classpath! --&gt;
&lt;dependencies&gt;
&lt;!-- ... --&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-starter-contract-stub-runner&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-pact&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;</programlisting>
</para>
</formalpara>
<formalpara>
<title>Gradle</title>
<para>
<programlisting language="gradle" linenumbering="unnumbered">dependencyManagement {
imports {
mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
}
}
dependencies {
//...
testCompile("org.springframework.cloud:spring-cloud-starter-contract-stub-runner")
// Don't forget to add spring-cloud-contract-pact to the classpath!
testCompile("org.springframework.cloud:spring-cloud-contract-pact")
}</programlisting>
</para>
</formalpara>
<simpara>Next, just pass the URL of the Pact Broker to <literal>repositoryRoot</literal>, prefixed
with <literal>pact://</literal> protocol. E.g. <literal>pact://http://localhost:8085</literal></simpara>
<programlisting language="java" linenumbering="unnumbered">@RunWith(SpringRunner.class)
@SpringBootTest
@AutoConfigureStubRunner(stubsMode = StubRunnerProperties.StubsMode.REMOTE,
ids = "com.example:beer-api-producer-pact",
repositoryRoot = "pact://http://localhost:8085")
public class BeerControllerTest {
//Inject the port of the running stub
@StubRunnerPort("beer-api-producer-pact") int producerPort;
//...
}</programlisting>
<simpara>With such a setup:</simpara>
<itemizedlist>
<listitem>
<simpara>Pact files will be downloaded from the Pact Broker</simpara>
</listitem>
<listitem>
<simpara>Spring Cloud Contract will convert the Pact files into stub definitions</simpara>
</listitem>
<listitem>
<simpara>The stub servers will be started and fed with stubs</simpara>
</listitem>
</itemizedlist>
<simpara>For more information about Pact support you can go to
the <xref linkend="pact-stub-downloader"/> section.</simpara>
</section>
</section>
<section xml:id="_how_can_i_debug_the_requestresponse_being_sent_by_the_generated_tests_client">
<title>How can I debug the request/response being sent by the generated tests client?</title>
<simpara>The generated tests all boil down to RestAssured in some form or fashion which relies on <link xl:href="https://hc.apache.org/httpcomponents-client-ga/">Apache HttpClient</link>. HttpClient has a facility called <link xl:href="https://hc.apache.org/httpcomponents-client-ga/logging.html#Wire_Logging">wire logging</link> which logs the entire request and response to HttpClient. Spring Boot has a logging <link xl:href="https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html">common application property</link> for doing this sort of thing, just add this to your application properties</simpara>
<programlisting language="properties" linenumbering="unnumbered">logging.level.org.apache.http.wire=DEBUG</programlisting>
<section xml:id="_how_can_i_debug_the_mappingrequestresponse_being_sent_by_wiremock">
<title>How can I debug the mapping/request/response being sent by WireMock?</title>
<simpara>Starting from version <literal>1.2.0</literal> we turn on WireMock logging to
info and the WireMock notifier to being verbose. Now you will
exactly know what request was received by WireMock server and which
matching response definition was picked.</simpara>
<simpara>To turn off this feature just bump WireMock logging to <literal>ERROR</literal></simpara>
<programlisting language="properties" linenumbering="unnumbered">logging.level.com.github.tomakehurst.wiremock=ERROR</programlisting>
</section>
<section xml:id="_how_can_i_see_what_got_registered_in_the_http_server_stub">
<title>How can I see what got registered in the HTTP server stub?</title>
<simpara>You can use the <literal>mappingsOutputFolder</literal> property on <literal>@AutoConfigureStubRunner</literal>, <literal>StubRunnerRule</literal> or
`StubRunnerExtension`to dump all mappings per artifact id. Also the port at which the given stub server
was started will be attached.</simpara>
</section>
<section xml:id="_can_i_reference_text_from_file">
<title>Can I reference text from file?</title>
<simpara>Yes! With version 1.2.0 we&#8217;ve added such a possibility. It&#8217;s enough to call <literal>file(&#8230;&#8203;)</literal> method in the
DSL and provide a path relative to where the contract lays.
If you&#8217;re using YAML just use the <literal>bodyFromFile</literal> property.</simpara>
</section>
</section>
</chapter>
<chapter xml:id="_spring_cloud_contract_verifier_setup">
<title>Spring Cloud Contract Verifier Setup</title>
<simpara>You can set up Spring Cloud Contract Verifier in the following ways:</simpara>
<itemizedlist>
<listitem>
<simpara><link linkend="gradle-project">As a Gradle project</link></simpara>
</listitem>
<listitem>
<simpara><link linkend="maven-project">As a Maven project</link></simpara>
</listitem>
<listitem>
<simpara><link linkend="docker-project">As a Docker project</link></simpara>
</listitem>
</itemizedlist>
<section xml:id="gradle-project">
<title>Gradle Project</title>
<simpara>To learn how to set up the Gradle project for Spring Cloud Contract Verifier, read the
following sections:</simpara>
<itemizedlist>
<listitem>
<simpara><xref linkend="gradle-prerequisites"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="gradle-add-gradle-plugin"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="gradle-and-rest-assured"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="gradle-snapshot-versions"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="gradle-add-stubs"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="gradle-default-setup"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="gradle-configure-plugin"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="gradle-configuration-options"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="gradle-single-base-class"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="gradle-different-base-classes"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="gradle-invoking-generated-tests"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="gradle-pushing-stubs-to-scm"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="gradle-consumer"/></simpara>
</listitem>
</itemizedlist>
<section xml:id="gradle-prerequisites">
<title>Prerequisites</title>
<simpara>In order to use Spring Cloud Contract Verifier with WireMock, you muse use either a
Gradle or a Maven plugin.</simpara>
<warning>
<simpara>If you want to use Spock in your projects, you must add separately the
<literal>spock-core</literal> and <literal>spock-spring</literal> modules. Check <link xl:href="http://spockframework.github.io/">Spock
docs for more information</link></simpara>
</warning>
</section>
<section xml:id="gradle-add-gradle-plugin">
<title>Add Gradle Plugin with Dependencies</title>
<simpara>To add a Gradle plugin with dependencies, use code similar to this:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath "org.springframework.boot:spring-boot-gradle-plugin:${springboot_version}"
classpath "org.springframework.cloud:spring-cloud-contract-gradle-plugin:${verifier_version}"
}
}
apply plugin: 'groovy'
apply plugin: 'spring-cloud-contract'
dependencyManagement {
imports {
mavenBom "org.springframework.cloud:spring-cloud-contract-dependencies:${verifier_version}"
}
}
dependencies {
testCompile 'org.codehaus.groovy:groovy-all:2.4.6'
// example with adding Spock core and Spock Spring
testCompile 'org.spockframework:spock-core:1.0-groovy-2.4'
testCompile 'org.spockframework:spock-spring:1.0-groovy-2.4'
testCompile 'org.springframework.cloud:spring-cloud-starter-contract-verifier'
}</programlisting>
</section>
<section xml:id="gradle-and-rest-assured">
<title>Gradle and Rest Assured 2.0</title>
<simpara>By default, Rest Assured 3.x is added to the classpath. However, to use Rest Assured 2.x
you can add it to the plugins classpath, as shown here:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath "org.springframework.boot:spring-boot-gradle-plugin:${springboot_version}"
classpath "org.springframework.cloud:spring-cloud-contract-gradle-plugin:${verifier_version}"
classpath "com.jayway.restassured:rest-assured:2.5.0"
classpath "com.jayway.restassured:spring-mock-mvc:2.5.0"
}
}
depenendencies {
// all dependencies
// you can exclude rest-assured from spring-cloud-contract-verifier
testCompile "com.jayway.restassured:rest-assured:2.5.0"
testCompile "com.jayway.restassured:spring-mock-mvc:2.5.0"
}</programlisting>
<simpara>That way, the plugin automatically sees that Rest Assured 2.x is present on the classpath
and modifies the imports accordingly.</simpara>
</section>
<section xml:id="gradle-snapshot-versions">
<title>Snapshot Versions for Gradle</title>
<simpara>Add the additional snapshot repository to your build.gradle to use snapshot versions,
which are automatically uploaded after every successful build, as shown here:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">buildscript {
repositories {
mavenCentral()
mavenLocal()
maven { url "http://repo.spring.io/snapshot" }
maven { url "http://repo.spring.io/milestone" }
maven { url "http://repo.spring.io/release" }
}
}</programlisting>
</section>
<section xml:id="gradle-add-stubs">
<title>Add stubs</title>
<simpara>By default, Spring Cloud Contract Verifier is looking for stubs in the
<literal>src/test/resources/contracts</literal> directory.</simpara>
<simpara>The directory containing stub definitions is treated as a class name, and each stub
definition is treated as a single test. Spring Cloud Contract Verifier assumes that it
contains at least one level of directories that are to be used as the test class name.
If more than one level of nested directories is present, all except the last one is used
as the package name. For example, with following structure:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">src/test/resources/contracts/myservice/shouldCreateUser.groovy
src/test/resources/contracts/myservice/shouldReturnUser.groovy</programlisting>
<simpara>Spring Cloud Contract Verifier creates a test class named <literal>defaultBasePackage.MyService</literal>
with two methods:</simpara>
<itemizedlist>
<listitem>
<simpara><literal>shouldCreateUser()</literal></simpara>
</listitem>
<listitem>
<simpara><literal>shouldReturnUser()</literal></simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="gradle-run-plugin">
<title>Run the Plugin</title>
<simpara>The plugin registers itself to be invoked before a <literal>check</literal> task. If you want it to be
part of your build process, you need to do nothing more. If you just want to generate
tests, invoke the <literal>generateContractTests</literal> task.</simpara>
</section>
<section xml:id="gradle-default-setup">
<title>Default Setup</title>
<simpara>The default Gradle Plugin setup creates the following Gradle part of the build (in
pseudocode):</simpara>
<programlisting language="groovy" linenumbering="unnumbered">contracts {
testFramework ='JUNIT'
testMode = 'MockMvc'
generatedTestSourcesDir = project.file("${project.buildDir}/generated-test-sources/contracts")
generatedTestResourcesDir = project.file("${project.buildDir}/generated-test-resources/contracts")
contractsDslDir = "${project.rootDir}/src/test/resources/contracts"
basePackageForTests = 'org.springframework.cloud.verifier.tests'
stubsOutputDir = project.file("${project.buildDir}/stubs")
// the following properties are used when you want to provide where the JAR with contract lays
contractDependency {
stringNotation = ''
}
contractsPath = ''
contractsWorkOffline = false
contractRepository {
cacheDownloadedContracts(true)
}
}
tasks.create(type: Jar, name: 'verifierStubsJar', dependsOn: 'generateClientStubs') {
baseName = project.name
classifier = contracts.stubsSuffix
from contractVerifier.stubsOutputDir
}
project.artifacts {
archives task
}
tasks.create(type: Copy, name: 'copyContracts') {
from contracts.contractsDslDir
into contracts.stubsOutputDir
}
verifierStubsJar.dependsOn 'copyContracts'
publishing {
publications {
stubs(MavenPublication) {
artifactId project.name
artifact verifierStubsJar
}
}
}</programlisting>
</section>
<section xml:id="gradle-configure-plugin">
<title>Configure Plugin</title>
<simpara>To change the default configuration, add a <literal>contracts</literal> snippet to your Gradle config, as
shown here:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">contracts {
testMode = 'MockMvc'
baseClassForTests = 'org.mycompany.tests'
generatedTestSourcesDir = project.file('src/generatedContract')
}</programlisting>
</section>
<section xml:id="gradle-configuration-options">
<title>Configuration Options</title>
<itemizedlist>
<listitem>
<simpara><emphasis role="strong">testMode</emphasis>: Defines the mode for acceptance tests. By default, the mode is MockMvc,
which is based on Spring&#8217;s MockMvc. It can also be changed to <emphasis role="strong">WebTestClient</emphasis>, <emphasis role="strong">JaxRsClient</emphasis> or to
<emphasis role="strong">Explicit</emphasis> for real HTTP calls.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">imports</emphasis>: Creates an array with imports that should be included in generated tests
(for example ['org.myorg.Matchers']). By default, it creates an empty array.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">staticImports</emphasis>: Creates an array with static imports that should be included in
generated tests(for example ['org.myorg.Matchers.*']). By default, it creates an empty
array.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">basePackageForTests</emphasis>: Specifies the base package for all generated tests. If not set,
the value is picked from <literal>baseClassForTests&#8217;s package and from `packageWithBaseClasses</literal>.
If neither of these values are set, then the value is set to
<literal>org.springframework.cloud.contract.verifier.tests</literal>.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">baseClassForTests</emphasis>: Creates a base class for all generated tests. By default, if you
use Spock classes, the class is <literal>spock.lang.Specification</literal>.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">packageWithBaseClasses</emphasis>: Defines a package where all the base classes reside. This
setting takes precedence over <emphasis role="strong">baseClassForTests</emphasis>.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">baseClassMappings</emphasis>: Explicitly maps a contract package to a FQN of a base class. This
setting takes precedence over <emphasis role="strong">packageWithBaseClasses</emphasis> and <emphasis role="strong">baseClassForTests</emphasis>.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">ruleClassForTests</emphasis>: Specifies a rule that should be added to the generated test
classes.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">ignoredFiles</emphasis>: Uses an <literal>Antmatcher</literal> to allow defining stub files for which processing
should be skipped. By default, it is an empty array.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">contractsDslDir</emphasis>: Specifies the directory containing contracts written using the
GroovyDSL. By default, its value is <literal>$rootDir/src/test/resources/contracts</literal>.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">generatedTestSourcesDir</emphasis>: Specifies the test source directory where tests generated
from the Groovy DSL should be placed. By default its value is
<literal>$buildDir/generated-test-sources/contracts</literal>.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">generatedTestResourcesDir</emphasis>: Specifies the test resource directory where resources used by the tests generated
from the Groovy DSL should be placed. By default its value is
<literal>$buildDir/generated-test-resources/contracts</literal>.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">stubsOutputDir</emphasis>: Specifies the directory where the generated WireMock stubs from
the Groovy DSL should be placed.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">testFramework</emphasis>: Specifies the target test framework to be used. Currently, Spock, JUnit 4 (<literal>TestFramework.JUNIT</literal>) and
JUnit 5 are supported with JUnit 4 being the default framework.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">contractsProperties</emphasis>: a map containing properties to be passed to Spring Cloud Contract
components. Those properties might be used by e.g. inbuilt or custom Stub Downloaders.</simpara>
</listitem>
</itemizedlist>
<simpara>The following properties are used when you want to specify the location of the JAR
containing the contracts:</simpara>
<itemizedlist>
<listitem>
<simpara><emphasis role="strong">contractDependency</emphasis>: Specifies the Dependency that provides
<literal>groupid:artifactid:version:classifier</literal> coordinates. You can use the <literal>contractDependency</literal>
closure to set it up.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">contractsPath</emphasis>: Specifies the path to the jar. If contract dependencies are
downloaded, the path defaults to <literal>groupid/artifactid</literal> where <literal>groupid</literal> is slash
separated. Otherwise, it scans contracts under the provided directory.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">contractsMode</emphasis>: Specifies the mode of downloading contracts (whether the
JAR is available offline, remotely etc.)</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">deleteStubsAfterTest</emphasis>: If set to <literal>false</literal> will not remove any downloaded
contracts from temporary directories</simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="gradle-single-base-class">
<title>Single Base Class for All Tests</title>
<simpara>When using Spring Cloud Contract Verifier in default MockMvc, you need to create a base
specification for all generated acceptance tests. In this class, you need to point to an
endpoint, which should be verified.</simpara>
<programlisting language="groovy" linenumbering="unnumbered">abstract class BaseMockMvcSpec extends Specification {
def setup() {
RestAssuredMockMvc.standaloneSetup(new PairIdController())
}
void isProperCorrelationId(Integer correlationId) {
assert correlationId == 123456
}
void isEmpty(String value) {
assert value == null
}
}</programlisting>
<simpara>If you use <literal>Explicit</literal> mode, you can use a base class to initialize the whole tested app
as you might see in regular integration tests. If you use the <literal>JAXRSCLIENT</literal> mode, this
base class should also contain a <literal>protected WebTarget webTarget</literal> field. Right now, the
only option to test the JAX-RS API is to start a web server.</simpara>
</section>
<section xml:id="gradle-different-base-classes">
<title>Different Base Classes for Contracts</title>
<simpara>If your base classes differ between contracts, you can tell the Spring Cloud Contract
plugin which class should get extended by the autogenerated tests. You have two options:</simpara>
<itemizedlist>
<listitem>
<simpara>Follow a convention by providing the <literal>packageWithBaseClasses</literal></simpara>
</listitem>
<listitem>
<simpara>Provide explicit mapping via <literal>baseClassMappings</literal></simpara>
</listitem>
</itemizedlist>
<simpara><emphasis role="strong">By Convention</emphasis></simpara>
<simpara>The convention is such that if you have a contract under (for example)
<literal>src/test/resources/contract/foo/bar/baz/</literal> and set the value of the
<literal>packageWithBaseClasses</literal> property to <literal>com.example.base</literal>, then Spring Cloud Contract
Verifier assumes that there is a <literal>BarBazBase</literal> class under the <literal>com.example.base</literal> package.
In other words, the system takes the last two parts of the package, if they exist, and
forms a class with a <literal>Base</literal> suffix. This rule takes precedence over <emphasis role="strong">baseClassForTests</emphasis>.
Here is an example of how it works in the <literal>contracts</literal> closure:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">packageWithBaseClasses = 'com.example.base'</programlisting>
<simpara><emphasis role="strong">By Mapping</emphasis></simpara>
<simpara>You can manually map a regular expression of the contract&#8217;s package to fully qualified
name of the base class for the matched contract. You have to provide a list called
<literal>baseClassMappings</literal> that consists <literal>baseClassMapping</literal> objects that takes a
<literal>contractPackageRegex</literal> to <literal>baseClassFQN</literal> mapping. Consider the following example:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">baseClassForTests = "com.example.FooBase"
baseClassMappings {
baseClassMapping('.*/com/.*', 'com.example.ComBase')
baseClassMapping('.*/bar/.*':'com.example.BarBase')
}</programlisting>
<simpara>Let&#8217;s assume that you have contracts under
- <literal>src/test/resources/contract/com/</literal>
- <literal>src/test/resources/contract/foo/</literal></simpara>
<simpara>By providing the <literal>baseClassForTests</literal>, we have a fallback in case mapping did not succeed.
(You could also provide the <literal>packageWithBaseClasses</literal> as a fallback.) That way, the tests
generated from <literal>src/test/resources/contract/com/</literal> contracts extend the
<literal>com.example.ComBase</literal>, whereas the rest of the tests extend <literal>com.example.FooBase</literal>.</simpara>
</section>
<section xml:id="gradle-invoking-generated-tests">
<title>Invoking Generated Tests</title>
<simpara>To ensure that the provider side is compliant with defined contracts, you need to invoke:</simpara>
<programlisting language="bash" linenumbering="unnumbered">./gradlew generateContractTests test</programlisting>
</section>
<section xml:id="gradle-pushing-stubs-to-scm">
<title>Pushing stubs to SCM</title>
<simpara>If you&#8217;re using the SCM repository to keep the contracts and
stubs, you might want to automate the step of pushing stubs to
the repository. To do that, it&#8217;s enough to call the <literal>pushStubsToScm</literal>
task. Example:</simpara>
<programlisting language="bash" linenumbering="unnumbered">$ ./gradlew pushStubsToScm</programlisting>
<simpara>Under <xref linkend="scm-stub-downloader"/> you can find all possible
configuration options that you can pass either via
the <literal>contractsProperties</literal> field e.g. <literal>contracts { contractsProperties = [foo:"bar"] }</literal>,
via <literal>contractsProperties</literal> method e.g. <literal>contracts { contractsProperties([foo:"bar"]) }</literal>,
a system property or an environment variable.</simpara>
</section>
<section xml:id="gradle-consumer">
<title>Spring Cloud Contract Verifier on the Consumer Side</title>
<simpara>In a consuming service, you need to configure the Spring Cloud Contract Verifier plugin
in exactly the same way as in case of provider. If you do not want to use Stub Runner
then you need to copy contracts stored in <literal>src/test/resources/contracts</literal> and generate
WireMock JSON stubs using:</simpara>
<programlisting language="bash" linenumbering="unnumbered">./gradlew generateClientStubs</programlisting>
<note>
<simpara>The <literal>stubsOutputDir</literal> option has to be set for stub generation to work.</simpara>
</note>
<simpara>When present, JSON stubs can be used in automated tests of consuming a service.</simpara>
<programlisting language="groovy" linenumbering="unnumbered">@ContextConfiguration(loader == SpringApplicationContextLoader, classes == Application)
class LoanApplicationServiceSpec extends Specification {
@ClassRule
@Shared
WireMockClassRule wireMockRule == new WireMockClassRule()
@Autowired
LoanApplicationService sut
def 'should successfully apply for loan'() {
given:
LoanApplication application =
new LoanApplication(client: new Client(clientPesel: '12345678901'), amount: 123.123)
when:
LoanApplicationResult loanApplication == sut.loanApplication(application)
then:
loanApplication.loanApplicationStatus == LoanApplicationStatus.LOAN_APPLIED
loanApplication.rejectionReason == null
}
}</programlisting>
<simpara><literal>LoanApplication</literal> makes a call to <literal>FraudDetection</literal> service. This request is handled by a
WireMock server configured with stubs generated by Spring Cloud Contract Verifier.</simpara>
</section>
</section>
<section xml:id="maven-project">
<title>Maven Project</title>
<simpara>To learn how to set up the Maven project for Spring Cloud Contract Verifier, read the
following sections:</simpara>
<itemizedlist>
<listitem>
<simpara><xref linkend="maven-add-plugin"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="maven-rest-assured"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="maven-snapshot-versions"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="maven-add-stubs"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="maven-run-plugin"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="maven-configure-plugin"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="maven-configuration-options"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="maven-single-base"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="maven-different-base"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="maven-invoking-generated-tests"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="maven-pushing-stubs-to-scm"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="maven-sts"/></simpara>
</listitem>
</itemizedlist>
<section xml:id="maven-add-plugin">
<title>Add maven plugin</title>
<simpara>Add the Spring Cloud Contract BOM in a fashion similar to this:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependencyManagement&gt;
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-dependencies&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-release.version}&lt;/version&gt;
&lt;type&gt;pom&lt;/type&gt;
&lt;scope&gt;import&lt;/scope&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;/dependencyManagement&gt;</programlisting>
<simpara>Next, add the <literal>Spring Cloud Contract Verifier</literal> Maven plugin:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;configuration&gt;
&lt;packageWithBaseClasses&gt;com.example.fraud&lt;/packageWithBaseClasses&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</programlisting>
<simpara>You can read more in the
<link xl:href="https://cloud.spring.io/spring-cloud-static/spring-cloud-contract/2.0.0.RELEASE/spring-cloud-contract-maven-plugin/">Spring
Cloud Contract Maven Plugin Documentation (example for <literal>2.0.0.RELEASE</literal> version)</link>.</simpara>
</section>
<section xml:id="maven-rest-assured">
<title>Maven and Rest Assured 2.0</title>
<simpara>By default, Rest Assured 3.x is added to the classpath. However, you can use Rest
Assured 2.x by adding it to the plugins classpath, as shown here:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;configuration&gt;
&lt;packageWithBaseClasses&gt;com.example&lt;/packageWithBaseClasses&gt;
&lt;/configuration&gt;
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-verifier&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
&lt;groupId&gt;com.jayway.restassured&lt;/groupId&gt;
&lt;artifactId&gt;rest-assured&lt;/artifactId&gt;
&lt;version&gt;2.5.0&lt;/version&gt;
&lt;scope&gt;compile&lt;/scope&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
&lt;groupId&gt;com.jayway.restassured&lt;/groupId&gt;
&lt;artifactId&gt;spring-mock-mvc&lt;/artifactId&gt;
&lt;version&gt;2.5.0&lt;/version&gt;
&lt;scope&gt;compile&lt;/scope&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;/plugin&gt;
&lt;dependencies&gt;
&lt;!-- all dependencies --&gt;
&lt;!-- you can exclude rest-assured from spring-cloud-contract-verifier --&gt;
&lt;dependency&gt;
&lt;groupId&gt;com.jayway.restassured&lt;/groupId&gt;
&lt;artifactId&gt;rest-assured&lt;/artifactId&gt;
&lt;version&gt;2.5.0&lt;/version&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
&lt;groupId&gt;com.jayway.restassured&lt;/groupId&gt;
&lt;artifactId&gt;spring-mock-mvc&lt;/artifactId&gt;
&lt;version&gt;2.5.0&lt;/version&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;</programlisting>
<simpara>That way, the plugin automatically sees that Rest Assured 3.x is present on the classpath
and modifies the imports accordingly.</simpara>
</section>
<section xml:id="maven-snapshot-versions">
<title>Snapshot versions for Maven</title>
<simpara>For Snapshot and Milestone versions, you have to add the following section to your
<literal>pom.xml</literal>, as shown here:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;repositories&gt;
&lt;repository&gt;
&lt;id&gt;spring-snapshots&lt;/id&gt;
&lt;name&gt;Spring Snapshots&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/snapshot&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;true&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/repository&gt;
&lt;repository&gt;
&lt;id&gt;spring-milestones&lt;/id&gt;
&lt;name&gt;Spring Milestones&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/milestone&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/repository&gt;
&lt;repository&gt;
&lt;id&gt;spring-releases&lt;/id&gt;
&lt;name&gt;Spring Releases&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/release&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/repository&gt;
&lt;/repositories&gt;
&lt;pluginRepositories&gt;
&lt;pluginRepository&gt;
&lt;id&gt;spring-snapshots&lt;/id&gt;
&lt;name&gt;Spring Snapshots&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/snapshot&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;true&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/pluginRepository&gt;
&lt;pluginRepository&gt;
&lt;id&gt;spring-milestones&lt;/id&gt;
&lt;name&gt;Spring Milestones&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/milestone&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/pluginRepository&gt;
&lt;pluginRepository&gt;
&lt;id&gt;spring-releases&lt;/id&gt;
&lt;name&gt;Spring Releases&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/release&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/pluginRepository&gt;
&lt;/pluginRepositories&gt;</programlisting>
</section>
<section xml:id="maven-add-stubs">
<title>Add stubs</title>
<simpara>By default, Spring Cloud Contract Verifier is looking for stubs in the
<literal>src/test/resources/contracts</literal> directory. The directory containing stub definitions is
treated as a class name, and each stub definition is treated as a single test. We assume
that it contains at least one directory to be used as test class name. If there is more
than one level of nested directories, all except the last one is used as package name.
For example, with following structure:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">src/test/resources/contracts/myservice/shouldCreateUser.groovy
src/test/resources/contracts/myservice/shouldReturnUser.groovy</programlisting>
<simpara>Spring Cloud Contract Verifier creates a test class named <literal>defaultBasePackage.MyService</literal>
with two methods</simpara>
<itemizedlist>
<listitem>
<simpara><literal>shouldCreateUser()</literal></simpara>
</listitem>
<listitem>
<simpara><literal>shouldReturnUser()</literal></simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="maven-run-plugin">
<title>Run plugin</title>
<simpara>The plugin goal <literal>generateTests</literal> is assigned to be invoked in the phase called
<literal>generate-test-sources</literal>. If you want it to be part of your build process, you need not do
anything. If you just want to generate tests, invoke the <literal>generateTests</literal> goal.</simpara>
</section>
<section xml:id="maven-configure-plugin">
<title>Configure plugin</title>
<simpara>To change the default configuration, just add a <literal>configuration</literal> section to the plugin
definition or the <literal>execution</literal> definition, as shown here:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;executions&gt;
&lt;execution&gt;
&lt;goals&gt;
&lt;goal&gt;convert&lt;/goal&gt;
&lt;goal&gt;generateStubs&lt;/goal&gt;
&lt;goal&gt;generateTests&lt;/goal&gt;
&lt;/goals&gt;
&lt;/execution&gt;
&lt;/executions&gt;
&lt;configuration&gt;
&lt;basePackageForTests&gt;org.springframework.cloud.verifier.twitter.place&lt;/basePackageForTests&gt;
&lt;baseClassForTests&gt;org.springframework.cloud.verifier.twitter.place.BaseMockMvcSpec&lt;/baseClassForTests&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</programlisting>
</section>
<section xml:id="maven-configuration-options">
<title>Configuration Options</title>
<itemizedlist>
<listitem>
<simpara><emphasis role="strong">testMode</emphasis>: Defines the mode for acceptance tests. By default, the mode is MockMvc,
which is based on Spring&#8217;s MockMvc. It can also be changed to <emphasis role="strong">WebTestClient</emphasis>, <emphasis role="strong">JaxRsClient</emphasis> or to
<emphasis role="strong">Explicit</emphasis> for real HTTP calls.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">basePackageForTests</emphasis>: Specifies the base package for all generated tests. If not set,
the value is picked from <literal>baseClassForTests&#8217;s package and from `packageWithBaseClasses</literal>.
If neither of these values are set, then the value is set to
<literal>org.springframework.cloud.contract.verifier.tests</literal>.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">ruleClassForTests</emphasis>: Specifies a rule that should be added to the generated test
classes.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">baseClassForTests</emphasis>: Creates a base class for all generated tests. By default, if you
use Spock classes, the class is <literal>spock.lang.Specification</literal>.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">contractsDirectory</emphasis>: Specifies a directory containing contracts written with the
GroovyDSL. The default directory is <literal>/src/test/resources/contracts</literal>.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">generatedTestSourcesDir</emphasis>: Specifies the test source directory where tests generated
from the Groovy DSL should be placed. By default its value is
<literal>$buildDir/generated-test-sources/contracts</literal>.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">generatedTestResourcesDir</emphasis>: Specifies the test resource directory where resources used by the tests generated</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">testFramework</emphasis>: Specifies the target test framework to be used. Currently, Spock, JUnit 4 (<literal>TestFramework.JUNIT</literal>) and
JUnit 5 are supported with JUnit 4 being the default framework.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">packageWithBaseClasses</emphasis>: Defines a package where all the base classes reside. This
setting takes precedence over <emphasis role="strong">baseClassForTests</emphasis>. The convention is such that, if you
have a contract under (for example) <literal>src/test/resources/contract/foo/bar/baz/</literal> and set
the value of the <literal>packageWithBaseClasses</literal> property to <literal>com.example.base</literal>, then Spring
Cloud Contract Verifier assumes that there is a <literal>BarBazBase</literal> class under the
<literal>com.example.base</literal> package. In other words, the system takes the last two parts of the
package, if they exist, and forms a class with a <literal>Base</literal> suffix.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">baseClassMappings</emphasis>: Specifies a list of base class mappings that provide
<literal>contractPackageRegex</literal>, which is checked against the package where the contract is
located, and <literal>baseClassFQN</literal>, which maps to the fully qualified name of the base class for
the matched contract. For example, if you have a contract under
<literal>src/test/resources/contract/foo/bar/baz/</literal> and map the property
<literal>.* &#8594; com.example.base.BaseClass</literal>, then the test class generated from these contracts
extends <literal>com.example.base.BaseClass</literal>. This setting takes precedence over
<emphasis role="strong">packageWithBaseClasses</emphasis> and <emphasis role="strong">baseClassForTests</emphasis>.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">contractsProperties</emphasis>: a map containing properties to be passed to Spring Cloud Contract
components. Those properties might be used by e.g. inbuilt or custom Stub Downloaders.</simpara>
</listitem>
</itemizedlist>
<simpara>If you want to download your contract definitions from a Maven repository, you can use
the following options:</simpara>
<itemizedlist>
<listitem>
<simpara><emphasis role="strong">contractDependency</emphasis>: The contract dependency that contains all the packaged contracts.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">contractsPath</emphasis>: The path to the concrete contracts in the JAR with packaged contracts.
Defaults to <literal>groupid/artifactid</literal> where <literal>gropuid</literal> is slash separated.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">contractsMode</emphasis>: Picks the mode in which stubs will be found and registered</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">deleteStubsAfterTest</emphasis>: If set to <literal>false</literal> will not remove any downloaded
contracts from temporary directories</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">contractsRepositoryUrl</emphasis>: URL to a repo with the artifacts that have contracts. If it is not provided,
use the current Maven ones.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">contractsRepositoryUsername</emphasis>: The user name to be used to connect to the repo with contracts.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">contractsRepositoryPassword</emphasis>: The password to be used to connect to the repo with contracts.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">contractsRepositoryProxyHost</emphasis>: The proxy host to be used to connect to the repo with contracts.</simpara>
</listitem>
<listitem>
<simpara><emphasis role="strong">contractsRepositoryProxyPort</emphasis>: The proxy port to be used to connect to the repo with contracts.</simpara>
</listitem>
</itemizedlist>
<simpara>We cache only non-snapshot, explicitly provided versions (for example
<literal>+</literal> or <literal>1.0.0.BUILD-SNAPSHOT</literal> won&#8217;t get cached). By default, this feature is turned on.</simpara>
</section>
<section xml:id="maven-single-base">
<title>Single Base Class for All Tests</title>
<simpara>When using Spring Cloud Contract Verifier in default MockMvc, you need to create a base
specification for all generated acceptance tests. In this class, you need to point to an
endpoint, which should be verified.</simpara>
<programlisting language="groovy" linenumbering="unnumbered">package org.mycompany.tests
import org.mycompany.ExampleSpringController
import com.jayway.restassured.module.mockmvc.RestAssuredMockMvc
import spock.lang.Specification
class MvcSpec extends Specification {
def setup() {
RestAssuredMockMvc.standaloneSetup(new ExampleSpringController())
}
}</programlisting>
<simpara>You can also setup the whole context if necessary.</simpara>
<programlisting language="java" linenumbering="unnumbered">import io.restassured.module.mockmvc.RestAssuredMockMvc;
import org.junit.Before;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.web.context.WebApplicationContext;
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT, classes = SomeConfig.class, properties="some=property")
public abstract class BaseTestClass {
@Autowired
WebApplicationContext context;
@Before
public void setup() {
RestAssuredMockMvc.webAppContextSetup(this.context);
}
}</programlisting>
<simpara>If you use <literal>EXPLICIT</literal> mode, you can use a base class to initialize the whole tested app
similarly, as you might find in regular integration tests.</simpara>
<programlisting language="java" linenumbering="unnumbered">import io.restassured.RestAssured;
import org.junit.Before;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.web.server.LocalServerPort
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.web.context.WebApplicationContext;
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT, classes = SomeConfig.class, properties="some=property")
public abstract class BaseTestClass {
@LocalServerPort
int port;
@Before
public void setup() {
RestAssured.baseURI = "http://localhost:" + this.port;
}
}</programlisting>
<simpara>If you use the <literal>JAXRSCLIENT</literal> mode, this base class should also contain a <literal>protected WebTarget webTarget</literal> field. Right
now, the only option to test the JAX-RS API is to start a web server.</simpara>
</section>
<section xml:id="maven-different-base">
<title>Different base classes for contracts</title>
<simpara>If your base classes differ between contracts, you can tell the Spring Cloud Contract
plugin which class should get extended by the autogenerated tests. You have two options:</simpara>
<itemizedlist>
<listitem>
<simpara>Follow a convention by providing the <literal>packageWithBaseClasses</literal></simpara>
</listitem>
<listitem>
<simpara>provide explicit mapping via <literal>baseClassMappings</literal></simpara>
</listitem>
</itemizedlist>
<simpara><emphasis role="strong">By Convention</emphasis></simpara>
<simpara>The convention is such that if you have a contract under (for example)
<literal>src/test/resources/contract/foo/bar/baz/</literal> and set the value of the
<literal>packageWithBaseClasses</literal> property to <literal>com.example.base</literal>, then Spring Cloud Contract
Verifier assumes that there is a <literal>BarBazBase</literal> class under the <literal>com.example.base</literal> package.
In other words, the system takes the last two parts of the package, if they exist, and
forms a class with a <literal>Base</literal> suffix. This rule takes precedence over <emphasis role="strong">baseClassForTests</emphasis>.
Here is an example of how it works in the <literal>contracts</literal> closure:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;configuration&gt;
&lt;packageWithBaseClasses&gt;hello&lt;/packageWithBaseClasses&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</programlisting>
<simpara><emphasis role="strong">By Mapping</emphasis></simpara>
<simpara>You can manually map a regular expression of the contract&#8217;s package to fully qualified
name of the base class for the matched contract. You have to provide a list called
<literal>baseClassMappings</literal> that consists <literal>baseClassMapping</literal> objects that takes a
<literal>contractPackageRegex</literal> to <literal>baseClassFQN</literal> mapping. Consider the following example:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;configuration&gt;
&lt;baseClassForTests&gt;com.example.FooBase&lt;/baseClassForTests&gt;
&lt;baseClassMappings&gt;
&lt;baseClassMapping&gt;
&lt;contractPackageRegex&gt;.*com.*&lt;/contractPackageRegex&gt;
&lt;baseClassFQN&gt;com.example.TestBase&lt;/baseClassFQN&gt;
&lt;/baseClassMapping&gt;
&lt;/baseClassMappings&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</programlisting>
<simpara>Assume that you have contracts under these two locations:
* <literal>src/test/resources/contract/com/</literal>
* <literal>src/test/resources/contract/foo/</literal></simpara>
<simpara>By providing the <literal>baseClassForTests</literal>, we have a fallback in case mapping did not succeed.
(You can also provide the <literal>packageWithBaseClasses</literal> as a fallback.) That way, the tests
generated from <literal>src/test/resources/contract/com/</literal> contracts extend the
<literal>com.example.ComBase</literal>, whereas the rest of the tests extend <literal>com.example.FooBase</literal>.</simpara>
</section>
<section xml:id="maven-invoking-generated-tests">
<title>Invoking generated tests</title>
<simpara>The Spring Cloud Contract Maven Plugin generates verification code in a directory called
<literal>/generated-test-sources/contractVerifier</literal> and attaches this directory to <literal>testCompile</literal>
goal.</simpara>
<simpara>For Groovy Spock code, use the following:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.codehaus.gmavenplus&lt;/groupId&gt;
&lt;artifactId&gt;gmavenplus-plugin&lt;/artifactId&gt;
&lt;version&gt;1.5&lt;/version&gt;
&lt;executions&gt;
&lt;execution&gt;
&lt;goals&gt;
&lt;goal&gt;testCompile&lt;/goal&gt;
&lt;/goals&gt;
&lt;/execution&gt;
&lt;/executions&gt;
&lt;configuration&gt;
&lt;testSources&gt;
&lt;testSource&gt;
&lt;directory&gt;${project.basedir}/src/test/groovy&lt;/directory&gt;
&lt;includes&gt;
&lt;include&gt;**/*.groovy&lt;/include&gt;
&lt;/includes&gt;
&lt;/testSource&gt;
&lt;testSource&gt;
&lt;directory&gt;${project.build.directory}/generated-test-sources/contractVerifier&lt;/directory&gt;
&lt;includes&gt;
&lt;include&gt;**/*.groovy&lt;/include&gt;
&lt;/includes&gt;
&lt;/testSource&gt;
&lt;/testSources&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</programlisting>
<simpara>To ensure that provider side is compliant with defined contracts, you need to invoke
<literal>mvn generateTest test</literal>.</simpara>
</section>
<section xml:id="maven-pushing-stubs-to-scm">
<title>Pushing stubs to SCM</title>
<simpara>If you&#8217;re using the SCM repository to keep the contracts and
stubs, you might want to automate the step of pushing stubs to
the repository. To do that, it&#8217;s enough to add the <literal>pushStubsToScm</literal>
goal. Example:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;configuration&gt;
&lt;!-- Base class mappings etc. --&gt;
&lt;!-- We want to pick contracts from a Git repository --&gt;
&lt;contractsRepositoryUrl&gt;git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git&lt;/contractsRepositoryUrl&gt;
&lt;!-- We reuse the contract dependency section to set up the path
to the folder that contains the contract definitions. In our case the
path will be /groupId/artifactId/version/contracts --&gt;
&lt;contractDependency&gt;
&lt;groupId&gt;${project.groupId}&lt;/groupId&gt;
&lt;artifactId&gt;${project.artifactId}&lt;/artifactId&gt;
&lt;version&gt;${project.version}&lt;/version&gt;
&lt;/contractDependency&gt;
&lt;!-- The contracts mode can't be classpath --&gt;
&lt;contractsMode&gt;REMOTE&lt;/contractsMode&gt;
&lt;/configuration&gt;
&lt;executions&gt;
&lt;execution&gt;
&lt;phase&gt;package&lt;/phase&gt;
&lt;goals&gt;
&lt;!-- By default we will not push the stubs back to SCM,
you have to explicitly add it as a goal --&gt;
&lt;goal&gt;pushStubsToScm&lt;/goal&gt;
&lt;/goals&gt;
&lt;/execution&gt;
&lt;/executions&gt;
&lt;/plugin&gt;</programlisting>
<simpara>Under <xref linkend="scm-stub-downloader"/> you can find all possible
configuration options that you can pass either via
the <literal>&lt;configuration&gt;&lt;contractProperties&gt;</literal> map, a system property
or an environment variable.</simpara>
</section>
<section xml:id="maven-sts">
<title>Maven Plugin and STS</title>
<simpara>If you see the following exception while using STS:</simpara>
<informalfigure>
<mediaobject>
<imageobject>
<imagedata fileref="https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/master/docs/src/main/asciidoc/images/sts_exception.png"/>
</imageobject>
<textobject><phrase>STS Exception</phrase></textobject>
</mediaobject>
</informalfigure>
<simpara>When you click on the error marker you should see something like this:</simpara>
<programlisting language="bash" linenumbering="unnumbered"> plugin:1.1.0.M1:convert:default-convert:process-test-resources) org.apache.maven.plugin.PluginExecutionException: Execution default-convert of goal org.springframework.cloud:spring-
cloud-contract-maven-plugin:1.1.0.M1:convert failed. at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:145) at
org.eclipse.m2e.core.internal.embedder.MavenImpl.execute(MavenImpl.java:331) at org.eclipse.m2e.core.internal.embedder.MavenImpl$11.call(MavenImpl.java:1362) at
...
org.eclipse.core.internal.jobs.Worker.run(Worker.java:55) Caused by: java.lang.NullPointerException at
org.eclipse.m2e.core.internal.builder.plexusbuildapi.EclipseIncrementalBuildContext.hasDelta(EclipseIncrementalBuildContext.java:53) at
org.sonatype.plexus.build.incremental.ThreadBuildContext.hasDelta(ThreadBuildContext.java:59) at</programlisting>
<simpara>In order to fix this issue, provide the following section in your <literal>pom.xml</literal>:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;build&gt;
&lt;pluginManagement&gt;
&lt;plugins&gt;
&lt;!--This plugin's configuration is used to store Eclipse m2e settings
only. It has no influence on the Maven build itself. --&gt;
&lt;plugin&gt;
&lt;groupId&gt;org.eclipse.m2e&lt;/groupId&gt;
&lt;artifactId&gt;lifecycle-mapping&lt;/artifactId&gt;
&lt;version&gt;1.0.0&lt;/version&gt;
&lt;configuration&gt;
&lt;lifecycleMappingMetadata&gt;
&lt;pluginExecutions&gt;
&lt;pluginExecution&gt;
&lt;pluginExecutionFilter&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;versionRange&gt;[1.0,)&lt;/versionRange&gt;
&lt;goals&gt;
&lt;goal&gt;convert&lt;/goal&gt;
&lt;/goals&gt;
&lt;/pluginExecutionFilter&gt;
&lt;action&gt;
&lt;execute /&gt;
&lt;/action&gt;
&lt;/pluginExecution&gt;
&lt;/pluginExecutions&gt;
&lt;/lifecycleMappingMetadata&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;
&lt;/plugins&gt;
&lt;/pluginManagement&gt;
&lt;/build&gt;</programlisting>
</section>
<section xml:id="_maven_plugin_with_spock_tests">
<title>Maven Plugin with Spock Tests</title>
<simpara>You can select the <link xl:href="http://spockframework.org/">Spock Framework</link> for creating and executing the auto-generated contract
verification tests with both Maven and Gradle plugin. However, whereas with Gradle its really straightforward,
in Maven you will require some additional setup in order to make the tests compile and execute properly.</simpara>
<simpara>First of all, you will have to use a plugin, such as <link xl:href="https://github.com/groovy/GMavenPlus">GMavenPlus</link> plugin,
to add Groovy to your project. In GMavenPlus plugin, you will need to explicitly set test sources, including both the
path where your base test classes are defined and the path were the generated contract tests are added.
Please refer to the example below:</simpara>
<programlisting language="xml" linenumbering="unnumbered"></programlisting>
<simpara>If you uphold to the Spock convention of ending the test class names with <literal>Spec</literal>, you will also need to adjust your Maven
Surefire plugin setup, like in the following example:</simpara>
<programlisting language="xml" linenumbering="unnumbered"></programlisting>
</section>
</section>
<section xml:id="_stubs_and_transitive_dependencies">
<title>Stubs and Transitive Dependencies</title>
<simpara>The Maven and Gradle plugin that add the tasks that create the stubs jar for you. One
problem that arises is that, when reusing the stubs, you can mistakenly import all of
that stub&#8217;s dependencies. When building a Maven artifact, even though you have a couple
of different jars, all of them share one pom:</simpara>
<programlisting language="bash" linenumbering="unnumbered">├── github-webhook-0.0.1.BUILD-20160903.075506-1-stubs.jar
├── github-webhook-0.0.1.BUILD-20160903.075506-1-stubs.jar.sha1
├── github-webhook-0.0.1.BUILD-20160903.075655-2-stubs.jar
├── github-webhook-0.0.1.BUILD-20160903.075655-2-stubs.jar.sha1
├── github-webhook-0.0.1.BUILD-SNAPSHOT.jar
├── github-webhook-0.0.1.BUILD-SNAPSHOT.pom
├── github-webhook-0.0.1.BUILD-SNAPSHOT-stubs.jar
├── ...
└── ...</programlisting>
<simpara>There are three possibilities of working with those dependencies so as not to have any
issues with transitive dependencies:</simpara>
<itemizedlist>
<listitem>
<simpara>Mark all application dependencies as optional</simpara>
</listitem>
<listitem>
<simpara>Create a separate artifactid for the stubs</simpara>
</listitem>
<listitem>
<simpara>Exclude dependencies on the consumer side</simpara>
</listitem>
</itemizedlist>
<simpara><emphasis role="strong">Mark all application dependencies as optional</emphasis></simpara>
<simpara>If, in the <literal>github-webhook</literal> application, you mark all of your dependencies as optional,
when you include the <literal>github-webhook</literal> stubs in another application (or when that
dependency gets downloaded by Stub Runner) then, since all of the dependencies are
optional, they will not get downloaded.</simpara>
<simpara><emphasis role="strong">Create a separate <literal>artifactid</literal> for the stubs</emphasis></simpara>
<simpara>If you create a separate <literal>artifactid</literal>, then you can set it up in whatever way you wish.
For example, you might decide to have no dependencies at all.</simpara>
<simpara><emphasis role="strong">Exclude dependencies on the consumer side</emphasis></simpara>
<simpara>As a consumer, if you add the stub dependency to your classpath, you can explicitly
exclude the unwanted dependencies.</simpara>
</section>
<section xml:id="_scenarios">
<title>Scenarios</title>
<simpara>You can handle scenarios with Spring Cloud Contract Verifier. All you need to do is to
stick to the proper naming convention while creating your contracts. The convention
requires including an order number followed by an underscore. This will work regardles
of whether you&#8217;re working with YAML or Groovy. Example:</simpara>
<screen>my_contracts_dir\
scenario1\
1_login.groovy
2_showCart.groovy
3_logout.groovy</screen>
<simpara>Such a tree causes Spring Cloud Contract Verifier to generate WireMock&#8217;s scenario with a
name of <literal>scenario1</literal> and the three following steps:</simpara>
<orderedlist numeration="arabic">
<listitem>
<simpara>login marked as <literal>Started</literal> pointing to&#8230;&#8203;</simpara>
</listitem>
<listitem>
<simpara>showCart marked as <literal>Step1</literal> pointing to&#8230;&#8203;</simpara>
</listitem>
<listitem>
<simpara>logout marked as <literal>Step2</literal> which will close the scenario.</simpara>
</listitem>
</orderedlist>
<simpara>More details about WireMock scenarios can be found at
<link xl:href="http://wiremock.org/docs/stateful-behaviour/">http://wiremock.org/docs/stateful-behaviour/</link></simpara>
<simpara>Spring Cloud Contract Verifier also generates tests with a guaranteed order of execution.</simpara>
</section>
<section xml:id="docker-project">
<title>Docker Project</title>
<simpara>We&#8217;re publishing a <literal>springcloud/spring-cloud-contract</literal> Docker image
that contains a project that will generate tests and execute them in <literal>EXPLICIT</literal> mode
against a running application.</simpara>
<tip>
<simpara>The <literal>EXPLICIT</literal> mode means that the tests generated from contracts will send
real requests and not the mocked ones.</simpara>
</tip>
<section xml:id="_short_intro_to_maven_jars_and_binary_storage">
<title>Short intro to Maven, JARs and Binary storage</title>
<simpara>Since the Docker image can be used by non JVM projects, it&#8217;s good to
explain the basic terms behind Spring Cloud Contract packaging defaults.</simpara>
<simpara>Part of the following definitions were taken from the <link xl:href="https://maven.apache.org/glossary.html">Maven Glossary</link></simpara>
<itemizedlist>
<listitem>
<simpara><literal>Project</literal>: Maven thinks in terms of projects. Everything that you
will build are projects. Those projects follow a well defined
“Project Object Model”. Projects can depend on other projects,
in which case the latter are called “dependencies”. A project may
consistent of several subprojects, however these subprojects are still
treated equally as projects.</simpara>
</listitem>
<listitem>
<simpara><literal>Artifact</literal>: An artifact is something that is either produced or used
by a project. Examples of artifacts produced by Maven for a project
include: JARs, source and binary distributions. Each artifact
is uniquely identified by a group id and an artifact ID which is
unique within a group.</simpara>
</listitem>
<listitem>
<simpara><literal>JAR</literal>: JAR stands for Java ARchive. It&#8217;s a format based on
the ZIP file format. Spring Cloud Contract packages the contracts and generated
stubs in a JAR file.</simpara>
</listitem>
<listitem>
<simpara><literal>GroupId</literal>: A group ID is a universally unique identifier for a project.
While this is often just the project name (eg. commons-collections),
it is helpful to use a fully-qualified package name to distinguish it
from other projects with a similar name (eg. org.apache.maven).
Typically, when published to the Artifact Manager, the <literal>GroupId</literal> will get
slash separated and form part of the URL. E.g. for group id <literal>com.example</literal>
and artifact id <literal>application</literal> would be <literal>/com/example/application/</literal>.</simpara>
</listitem>
<listitem>
<simpara><literal>Classifier</literal>: The Maven dependency notation looks as follows:
<literal>groupId:artifactId:version:classifier</literal>. The classifier is additional suffix
passed to the dependency. E.g. <literal>stubs</literal>, <literal>sources</literal>. The same dependency
e.g. <literal>com.example:application</literal> can produce multiple artifacts that
differ from each other with the classifier.</simpara>
</listitem>
<listitem>
<simpara><literal>Artifact manager</literal>: When you generate binaries / sources / packages, you would
like them to be available for others to download / reference or reuse. In case
of the JVM world those artifacts would be JARs, for Ruby these are gems
and for Docker those would be Docker images. You can store those artifacts
in a manager. Examples of such managers can be <link xl:href="https://jfrog.com/artifactory/">Artifactory</link>
or <link xl:href="http://www.sonatype.org/nexus/">Nexus</link>.</simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="_how_it_works_2">
<title>How it works</title>
<simpara>The image searches for contracts under the <literal>/contracts</literal> folder.
The output from running the tests will be available under
<literal>/spring-cloud-contract/build</literal> folder (it&#8217;s useful for debugging
purposes).</simpara>
<simpara>It&#8217;s enough for you to mount your contracts, pass the environment variables
and the image will:</simpara>
<itemizedlist>
<listitem>
<simpara>generate the contract tests</simpara>
</listitem>
<listitem>
<simpara>execute the tests against the provided URL</simpara>
</listitem>
<listitem>
<simpara>generate the <link xl:href="http://wiremock.org">WireMock</link> stubs</simpara>
</listitem>
<listitem>
<simpara>(optional - turned on by default) publish the stubs to a Artifact Manager</simpara>
</listitem>
</itemizedlist>
<section xml:id="_environment_variables">
<title>Environment Variables</title>
<simpara>The Docker image requires some environment variables to point to
your running application, to the Artifact manager instance etc.</simpara>
<itemizedlist>
<listitem>
<simpara><literal>PROJECT_GROUP</literal> - your project&#8217;s group id. Defaults to <literal>com.example</literal></simpara>
</listitem>
<listitem>
<simpara><literal>PROJECT_VERSION</literal> - your project&#8217;s version. Defaults to <literal>0.0.1-SNAPSHOT</literal></simpara>
</listitem>
<listitem>
<simpara><literal>PROJECT_NAME</literal> - artifact id. Defaults to <literal>example</literal></simpara>
</listitem>
<listitem>
<simpara><literal>REPO_WITH_BINARIES_URL</literal> - URL of your Artifact Manager. Defaults to <literal><link xl:href="http://localhost:8081/artifactory/libs-release-local">http://localhost:8081/artifactory/libs-release-local</link></literal>
which is the default URL of <link xl:href="https://jfrog.com/artifactory/">Artifactory</link> running locally</simpara>
</listitem>
<listitem>
<simpara><literal>REPO_WITH_BINARIES_USERNAME</literal> - (optional) username when the Artifact Manager is secured</simpara>
</listitem>
<listitem>
<simpara><literal>REPO_WITH_BINARIES_PASSWORD</literal> - (optional) password when the Artifact Manager is secured</simpara>
</listitem>
<listitem>
<simpara><literal>PUBLISH_ARTIFACTS</literal> - if set to <literal>true</literal> then will publish artifact to binary storage. Defaults to <literal>true</literal>.</simpara>
</listitem>
</itemizedlist>
<simpara>These environment variables are used when contracts lay in an external repository. To enable
this feature you must set the <literal>EXTERNAL_CONTRACTS_ARTIFACT_ID</literal> environment variable.</simpara>
<itemizedlist>
<listitem>
<simpara><literal>EXTERNAL_CONTRACTS_GROUP_ID</literal> - group id of the project with contracts. Defaults to <literal>com.example</literal></simpara>
</listitem>
<listitem>
<simpara><literal>EXTERNAL_CONTRACTS_ARTIFACT_ID</literal>- artifact id of the project with contracts.</simpara>
</listitem>
<listitem>
<simpara><literal>EXTERNAL_CONTRACTS_CLASSIFIER</literal>- classifier of the project with contracts. Empty by default</simpara>
</listitem>
<listitem>
<simpara><literal>EXTERNAL_CONTRACTS_VERSION</literal> - version of the project with contracts. Defaults to <literal>+</literal>, equivalent to picking the latest</simpara>
</listitem>
<listitem>
<simpara><literal>EXTERNAL_CONTRACTS_REPO_WITH_BINARIES_URL</literal> - URL of your Artifact Manager. Defaults to value of <literal>REPO_WITH_BINARIES_URL</literal> env var.
If that&#8217;s not set, defaults to <literal><link xl:href="http://localhost:8081/artifactory/libs-release-local">http://localhost:8081/artifactory/libs-release-local</link></literal>
which is the default URL of <link xl:href="https://jfrog.com/artifactory/">Artifactory</link> running locally</simpara>
</listitem>
<listitem>
<simpara><literal>EXTERNAL_CONTRACTS_PATH</literal> - path to contracts for the given project, inside the project with contracts.
Defaults to slash separated <literal>EXTERNAL_CONTRACTS_GROUP_ID</literal> concatenated with <literal>/</literal> and <literal>EXTERNAL_CONTRACTS_ARTIFACT_ID</literal>. E.g.
for group id <literal>foo.bar</literal> and artifact id <literal>baz</literal>, would result in <literal>foo/bar/baz</literal> contracts path.</simpara>
</listitem>
<listitem>
<simpara><literal>EXTERNAL_CONTRACTS_WORK_OFFLINE</literal> - if set to <literal>true</literal> then will retrieve artifact with contracts
from the container&#8217;s <literal>.m2</literal>. Mount your local <literal>.m2</literal> as a volume available at the container&#8217;s <literal>/root/.m2</literal> path.
You must not set both <literal>EXTERNAL_CONTRACTS_WORK_OFFLINE</literal> and <literal>EXTERNAL_CONTRACTS_REPO_WITH_BINARIES_URL</literal>.</simpara>
</listitem>
</itemizedlist>
<simpara>These environment variables are used when tests are executed:</simpara>
<itemizedlist>
<listitem>
<simpara><literal>APPLICATION_BASE_URL</literal> - url against which tests should be executed.
Remember that it has to be accessible from the Docker container (e.g. <literal>localhost</literal>
will not work)</simpara>
</listitem>
<listitem>
<simpara><literal>APPLICATION_USERNAME</literal> - (optional) username for basic authentication to your application</simpara>
</listitem>
<listitem>
<simpara><literal>APPLICATION_PASSWORD</literal> - (optional) password for basic authentication to your application</simpara>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="_example_of_usage">
<title>Example of usage</title>
<simpara>Let&#8217;s take a look at a simple MVC application</simpara>
<programlisting language="bash" linenumbering="unnumbered">$ git clone https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs
$ cd bookstore</programlisting>
<simpara>The contracts are available under <literal>/contracts</literal> folder.</simpara>
</section>
<section xml:id="docker-server-side">
<title>Server side (nodejs)</title>
<simpara>Since we want to run tests, we could just execute:</simpara>
<programlisting language="bash" linenumbering="unnumbered">$ npm test</programlisting>
<simpara>however, for learning purposes, let&#8217;s split it into pieces:</simpara>
<programlisting language="bash" linenumbering="unnumbered"># Stop docker infra (nodejs, artifactory)
$ ./stop_infra.sh
# Start docker infra (nodejs, artifactory)
$ ./setup_infra.sh
# Kill &amp; Run app
$ pkill -f "node app"
$ nohup node app &amp;
# Prepare environment variables
$ SC_CONTRACT_DOCKER_VERSION="..."
$ APP_IP="192.168.0.100"
$ APP_PORT="3000"
$ ARTIFACTORY_PORT="8081"
$ APPLICATION_BASE_URL="http://${APP_IP}:${APP_PORT}"
$ ARTIFACTORY_URL="http://${APP_IP}:${ARTIFACTORY_PORT}/artifactory/libs-release-local"
$ CURRENT_DIR="$( pwd )"
$ CURRENT_FOLDER_NAME=${PWD##*/}
$ PROJECT_VERSION="0.0.1.RELEASE"
# Execute contract tests
$ docker run --rm -e "APPLICATION_BASE_URL=${APPLICATION_BASE_URL}" -e "PUBLISH_ARTIFACTS=true" -e "PROJECT_NAME=${CURRENT_FOLDER_NAME}" -e "REPO_WITH_BINARIES_URL=${ARTIFACTORY_URL}" -e "PROJECT_VERSION=${PROJECT_VERSION}" -v "${CURRENT_DIR}/contracts/:/contracts:ro" -v "${CURRENT_DIR}/node_modules/spring-cloud-contract/output:/spring-cloud-contract-output/" springcloud/spring-cloud-contract:"${SC_CONTRACT_DOCKER_VERSION}"
# Kill app
$ pkill -f "node app"</programlisting>
<simpara>What will happen is that via bash scripts:</simpara>
<itemizedlist>
<listitem>
<simpara>infrastructure will be set up (MongoDb, Artifactory).
In real life scenario you would just run the NodeJS application
with mocked database. In this example we want to show how we can
benefit from Spring Cloud Contract in no time.</simpara>
</listitem>
<listitem>
<simpara>due to those constraints the contracts also represent the
stateful situation</simpara>
<itemizedlist>
<listitem>
<simpara>first request is a <literal>POST</literal> that causes data to get inserted to the database</simpara>
</listitem>
<listitem>
<simpara>second request is a <literal>GET</literal> that returns a list of data with 1 previously inserted element</simpara>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<simpara>the NodeJS application will be started (on port <literal>3000</literal>)</simpara>
</listitem>
<listitem>
<simpara>contract tests will be generated via Docker and tests
will be executed against the running application</simpara>
<itemizedlist>
<listitem>
<simpara>the contracts will be taken from <literal>/contracts</literal> folder.</simpara>
</listitem>
<listitem>
<simpara>the output of the test execution is available under
<literal>node_modules/spring-cloud-contract/output</literal>.</simpara>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<simpara>the stubs will be uploaded to Artifactory. You can check them out
under <link xl:href="http://localhost:8081/artifactory/libs-release-local/com/example/bookstore/0.0.1.RELEASE/">http://localhost:8081/artifactory/libs-release-local/com/example/bookstore/0.0.1.RELEASE/</link> .
The stubs will be here <link xl:href="http://localhost:8081/artifactory/libs-release-local/com/example/bookstore/0.0.1.RELEASE/bookstore-0.0.1.RELEASE-stubs.jar">http://localhost:8081/artifactory/libs-release-local/com/example/bookstore/0.0.1.RELEASE/bookstore-0.0.1.RELEASE-stubs.jar</link>.</simpara>
</listitem>
</itemizedlist>
<simpara>To see how the client side looks like check out the <xref linkend="stubrunner-docker"/> section.</simpara>
</section>
</section>
</chapter>
<chapter xml:id="_spring_cloud_contract_verifier_messaging">
<title>Spring Cloud Contract Verifier Messaging</title>
<simpara>Spring Cloud Contract Verifier lets you verify applications that use messaging as a
means of communication. All of the integrations shown in this document work with Spring,
but you can also create one of your own and use that.</simpara>
<section xml:id="_integrations">
<title>Integrations</title>
<simpara>You can use one of the following four integration configurations:</simpara>
<itemizedlist>
<listitem>
<simpara>Apache Camel</simpara>
</listitem>
<listitem>
<simpara>Spring Integration</simpara>
</listitem>
<listitem>
<simpara>Spring Cloud Stream</simpara>
</listitem>
<listitem>
<simpara>Spring AMQP</simpara>
</listitem>
</itemizedlist>
<simpara>Since we use Spring Boot, if you have added one of these libraries to the classpath, all
the messaging configuration is automatically set up.</simpara>
<important>
<simpara>Remember to put <literal>@AutoConfigureMessageVerifier</literal> on the base class of your
generated tests. Otherwise, messaging part of Spring Cloud Contract Verifier does not
work.</simpara>
</important>
<important>
<simpara>If you want to use Spring Cloud Stream, remember to add a dependency on
<literal>org.springframework.cloud:spring-cloud-stream-test-support</literal>, as shown here:</simpara>
</important>
<formalpara role="primary">
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-stream-test-support&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;</programlisting>
</para>
</formalpara>
<formalpara role="secondary">
<title>Gradle</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">testCompile "org.springframework.cloud:spring-cloud-stream-test-support"</programlisting>
</para>
</formalpara>
</section>
<section xml:id="_manual_integration_testing">
<title>Manual Integration Testing</title>
<simpara>The main interface used by the tests is
<literal>org.springframework.cloud.contract.verifier.messaging.MessageVerifier</literal>.
It defines how to send and receive messages. You can create your own implementation to
achieve the same goal.</simpara>
<simpara>In a test, you can inject a <literal>ContractVerifierMessageExchange</literal> to send and receive
messages that follow the contract. Then add <literal>@AutoConfigureMessageVerifier</literal> to your test.
Here&#8217;s an example:</simpara>
<programlisting language="java" linenumbering="unnumbered">@RunWith(SpringTestRunner.class)
@SpringBootTest
@AutoConfigureMessageVerifier
public static class MessagingContractTests {
@Autowired
private MessageVerifier verifier;
...
}</programlisting>
<note>
<simpara>If your tests require stubs as well, then <literal>@AutoConfigureStubRunner</literal> includes the
messaging configuration, so you only need the one annotation.</simpara>
</note>
</section>
<section xml:id="_publisher_side_test_generation">
<title>Publisher-Side Test Generation</title>
<simpara>Having the <literal>input</literal> or <literal>outputMessage</literal> sections in your DSL results in creation of tests
on the publisher&#8217;s side. By default, JUnit 4 tests are created. However, there is also a
possibility to create JUnit 5 or Spock tests.</simpara>
<simpara>There are 3 main scenarios that we should take into consideration:</simpara>
<itemizedlist>
<listitem>
<simpara>Scenario 1: There is no input message that produces an output message. The output
message is triggered by a component inside the application (for example, scheduler).</simpara>
</listitem>
<listitem>
<simpara>Scenario 2: The input message triggers an output message.</simpara>
</listitem>
<listitem>
<simpara>Scenario 3: The input message is consumed and there is no output message.</simpara>
</listitem>
</itemizedlist>
<important>
<simpara>The destination passed to <literal>messageFrom</literal> or <literal>sentTo</literal> can have different
meanings for different messaging implementations. For <emphasis role="strong">Stream</emphasis> and <emphasis role="strong">Integration</emphasis> it is
first resolved as a <literal>destination</literal> of a channel. Then, if there is no such <literal>destination</literal>
it is resolved as a channel name. For <emphasis role="strong">Camel</emphasis>, that&#8217;s a certain component (for example,
<literal>jms</literal>).</simpara>
</important>
<section xml:id="_scenario_1_no_input_message">
<title>Scenario 1: No Input Message</title>
<simpara>For the given contract:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">def contractDsl = Contract.make {
label 'some_label'
input {
triggeredBy('bookReturnedTriggered()')
}
outputMessage {
sentTo('activemq:output')
body('''{ "bookName" : "foo" }''')
headers {
header('BOOK-NAME', 'foo')
messagingContentType(applicationJson())
}
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">label: some_label
input:
triggeredBy: bookReturnedTriggered
outputMessage:
sentTo: activemq:output
body:
bookName: foo
headers:
BOOK-NAME: foo
contentType: application/json</programlisting>
</para>
</formalpara>
<simpara>The following JUnit test is created:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">'''
// when:
bookReturnedTriggered();
// then:
ContractVerifierMessage response = contractVerifierMessaging.receive("activemq:output");
assertThat(response).isNotNull();
assertThat(response.getHeader("BOOK-NAME")).isNotNull();
assertThat(response.getHeader("BOOK-NAME").toString()).isEqualTo("foo");
assertThat(response.getHeader("contentType")).isNotNull();
assertThat(response.getHeader("contentType").toString()).isEqualTo("application/json");
// and:
DocumentContext parsedJson = JsonPath.parse(contractVerifierObjectMapper.writeValueAsString(response.getPayload()));
assertThatJson(parsedJson).field("bookName").isEqualTo("foo");
'''</programlisting>
<simpara>And the following Spock test would be created:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">'''
when:
bookReturnedTriggered()
then:
ContractVerifierMessage response = contractVerifierMessaging.receive('activemq:output')
assert response != null
response.getHeader('BOOK-NAME')?.toString() == 'foo'
response.getHeader('contentType')?.toString() == 'application/json'
and:
DocumentContext parsedJson = JsonPath.parse(contractVerifierObjectMapper.writeValueAsString(response.payload))
assertThatJson(parsedJson).field("bookName").isEqualTo("foo")
'''</programlisting>
</section>
<section xml:id="_scenario_2_output_triggered_by_input">
<title>Scenario 2: Output Triggered by Input</title>
<simpara>For the given contract:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">def contractDsl = Contract.make {
label 'some_label'
input {
messageFrom('jms:input')
messageBody([
bookName: 'foo'
])
messageHeaders {
header('sample', 'header')
}
}
outputMessage {
sentTo('jms:output')
body([
bookName: 'foo'
])
headers {
header('BOOK-NAME', 'foo')
}
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">label: some_label
input:
messageFrom: jms:input
messageBody:
bookName: 'foo'
messageHeaders:
sample: header
outputMessage:
sentTo: jms:output
body:
bookName: foo
headers:
BOOK-NAME: foo</programlisting>
</para>
</formalpara>
<simpara>The following JUnit test is created:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">'''
// given:
ContractVerifierMessage inputMessage = contractVerifierMessaging.create(
"{\\"bookName\\":\\"foo\\"}"
, headers()
.header("sample", "header"));
// when:
contractVerifierMessaging.send(inputMessage, "jms:input");
// then:
ContractVerifierMessage response = contractVerifierMessaging.receive("jms:output");
assertThat(response).isNotNull();
assertThat(response.getHeader("BOOK-NAME")).isNotNull();
assertThat(response.getHeader("BOOK-NAME").toString()).isEqualTo("foo");
// and:
DocumentContext parsedJson = JsonPath.parse(contractVerifierObjectMapper.writeValueAsString(response.getPayload()));
assertThatJson(parsedJson).field("bookName").isEqualTo("foo");
'''</programlisting>
<simpara>And the following Spock test would be created:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">"""\
given:
ContractVerifierMessage inputMessage = contractVerifierMessaging.create(
'''{"bookName":"foo"}''',
['sample': 'header']
)
when:
contractVerifierMessaging.send(inputMessage, 'jms:input')
then:
ContractVerifierMessage response = contractVerifierMessaging.receive('jms:output')
assert response !- null
response.getHeader('BOOK-NAME')?.toString() == 'foo'
and:
DocumentContext parsedJson = JsonPath.parse(contractVerifierObjectMapper.writeValueAsString(response.payload))
assertThatJson(parsedJson).field("bookName").isEqualTo("foo")
"""</programlisting>
</section>
<section xml:id="_scenario_3_no_output_message">
<title>Scenario 3: No Output Message</title>
<simpara>For the given contract:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">def contractDsl = Contract.make {
label 'some_label'
input {
messageFrom('jms:delete')
messageBody([
bookName: 'foo'
])
messageHeaders {
header('sample', 'header')
}
assertThat('bookWasDeleted()')
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">label: some_label
input:
messageFrom: jms:delete
messageBody:
bookName: 'foo'
messageHeaders:
sample: header
assertThat: bookWasDeleted()</programlisting>
</para>
</formalpara>
<simpara>The following JUnit test is created:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">'''
// given:
ContractVerifierMessage inputMessage = contractVerifierMessaging.create(
"{\\"bookName\\":\\"foo\\"}"
, headers()
.header("sample", "header"));
// when:
contractVerifierMessaging.send(inputMessage, "jms:delete");
// then:
bookWasDeleted();
'''</programlisting>
<simpara>And the following Spock test would be created:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">'''
given:
ContractVerifierMessage inputMessage = contractVerifierMessaging.create(
\'\'\'{"bookName":"foo"}\'\'\',
['sample': 'header']
)
when:
contractVerifierMessaging.send(inputMessage, 'jms:delete')
then:
noExceptionThrown()
bookWasDeleted()
'''</programlisting>
</section>
</section>
<section xml:id="_consumer_stub_generation">
<title>Consumer Stub Generation</title>
<simpara>Unlike the HTTP part, in messaging, we need to publish the Groovy DSL inside the JAR with
a stub. Then it is parsed on the consumer side and proper stubbed routes are created.</simpara>
<simpara>For more information, see <xref linkend="stub-runner-for-messaging"/> section.</simpara>
<formalpara role="primary">
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-starter-stream-rabbit&lt;/artifactId&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-starter-contract-stub-runner&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-stream-test-support&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;dependencyManagement&gt;
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-dependencies&lt;/artifactId&gt;
&lt;version&gt;Greenwich.BUILD-SNAPSHOT&lt;/version&gt;
&lt;type&gt;pom&lt;/type&gt;
&lt;scope&gt;import&lt;/scope&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;/dependencyManagement&gt;</programlisting>
</para>
</formalpara>
<formalpara role="secondary">
<title>Gradle</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">ext {
contractsDir = file("mappings")
stubsOutputDirRoot = file("${project.buildDir}/production/${project.name}-stubs/")
}
// Automatically added by plugin:
// copyContracts - copies contracts to the output folder from which JAR will be created
// verifierStubsJar - JAR with a provided stub suffix
// the presented publication is also added by the plugin but you can modify it as you wish
publishing {
publications {
stubs(MavenPublication) {
artifactId "${project.name}-stubs"
artifact verifierStubsJar
}
}
}</programlisting>
</para>
</formalpara>
</section>
</chapter>
<chapter xml:id="_spring_cloud_contract_stub_runner">
<title>Spring Cloud Contract Stub Runner</title>
<simpara>One of the issues that you might encounter while using Spring Cloud Contract Verifier is
passing the generated WireMock JSON stubs from the server side to the client side (or to
various clients). The same takes place in terms of client-side generation for messaging.</simpara>
<simpara>Copying the JSON files and setting the client side for messaging manually is out of the
question. That is why we introduced Spring Cloud Contract Stub Runner. It can
automatically download and run the stubs for you.</simpara>
<section xml:id="_snapshot_versions">
<title>Snapshot versions</title>
<simpara>Add the additional snapshot repository to your <literal>build.gradle</literal> file to use snapshot
versions, which are automatically uploaded after every successful build:</simpara>
<formalpara role="primary">
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;repositories&gt;
&lt;repository&gt;
&lt;id&gt;spring-snapshots&lt;/id&gt;
&lt;name&gt;Spring Snapshots&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/snapshot&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;true&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/repository&gt;
&lt;repository&gt;
&lt;id&gt;spring-milestones&lt;/id&gt;
&lt;name&gt;Spring Milestones&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/milestone&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/repository&gt;
&lt;repository&gt;
&lt;id&gt;spring-releases&lt;/id&gt;
&lt;name&gt;Spring Releases&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/release&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/repository&gt;
&lt;/repositories&gt;
&lt;pluginRepositories&gt;
&lt;pluginRepository&gt;
&lt;id&gt;spring-snapshots&lt;/id&gt;
&lt;name&gt;Spring Snapshots&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/snapshot&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;true&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/pluginRepository&gt;
&lt;pluginRepository&gt;
&lt;id&gt;spring-milestones&lt;/id&gt;
&lt;name&gt;Spring Milestones&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/milestone&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/pluginRepository&gt;
&lt;pluginRepository&gt;
&lt;id&gt;spring-releases&lt;/id&gt;
&lt;name&gt;Spring Releases&lt;/name&gt;
&lt;url&gt;https://repo.spring.io/release&lt;/url&gt;
&lt;snapshots&gt;
&lt;enabled&gt;false&lt;/enabled&gt;
&lt;/snapshots&gt;
&lt;/pluginRepository&gt;
&lt;/pluginRepositories&gt;</programlisting>
</para>
</formalpara>
<formalpara role="secondary">
<title>Gradle</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">buildscript {
repositories {
mavenCentral()
mavenLocal()
maven { url "http://repo.spring.io/snapshot" }
maven { url "http://repo.spring.io/milestone" }
maven { url "http://repo.spring.io/release" }
}</programlisting>
</para>
</formalpara>
</section>
<section xml:id="publishing-stubs-as-jars">
<title>Publishing Stubs as JARs</title>
<simpara>The easiest approach would be to centralize the way stubs are kept. For example, you can
keep them as jars in a Maven repository.</simpara>
<tip>
<simpara>For both Maven and Gradle, the setup comes ready to work. However, you can customize
it if you want to.</simpara>
</tip>
<formalpara role="primary">
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;!-- First disable the default jar setup in the properties section --&gt;
&lt;!-- we don't want the verifier to do a jar for us --&gt;
&lt;spring.cloud.contract.verifier.skip&gt;true&lt;/spring.cloud.contract.verifier.skip&gt;
&lt;!-- Next add the assembly plugin to your build --&gt;
&lt;!-- we want the assembly plugin to generate the JAR --&gt;
&lt;plugin&gt;
&lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
&lt;artifactId&gt;maven-assembly-plugin&lt;/artifactId&gt;
&lt;executions&gt;
&lt;execution&gt;
&lt;id&gt;stub&lt;/id&gt;
&lt;phase&gt;prepare-package&lt;/phase&gt;
&lt;goals&gt;
&lt;goal&gt;single&lt;/goal&gt;
&lt;/goals&gt;
&lt;inherited&gt;false&lt;/inherited&gt;
&lt;configuration&gt;
&lt;attach&gt;true&lt;/attach&gt;
&lt;descriptors&gt;
${basedir}/src/assembly/stub.xml
&lt;/descriptors&gt;
&lt;/configuration&gt;
&lt;/execution&gt;
&lt;/executions&gt;
&lt;/plugin&gt;
&lt;!-- Finally setup your assembly. Below you can find the contents of src/main/assembly/stub.xml --&gt;
&lt;assembly
xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd"&gt;
&lt;id&gt;stubs&lt;/id&gt;
&lt;formats&gt;
&lt;format&gt;jar&lt;/format&gt;
&lt;/formats&gt;
&lt;includeBaseDirectory&gt;false&lt;/includeBaseDirectory&gt;
&lt;fileSets&gt;
&lt;fileSet&gt;
&lt;directory&gt;src/main/java&lt;/directory&gt;
&lt;outputDirectory&gt;/&lt;/outputDirectory&gt;
&lt;includes&gt;
&lt;include&gt;**com/example/model/*.*&lt;/include&gt;
&lt;/includes&gt;
&lt;/fileSet&gt;
&lt;fileSet&gt;
&lt;directory&gt;${project.build.directory}/classes&lt;/directory&gt;
&lt;outputDirectory&gt;/&lt;/outputDirectory&gt;
&lt;includes&gt;
&lt;include&gt;**com/example/model/*.*&lt;/include&gt;
&lt;/includes&gt;
&lt;/fileSet&gt;
&lt;fileSet&gt;
&lt;directory&gt;${project.build.directory}/snippets/stubs&lt;/directory&gt;
&lt;outputDirectory&gt;META-INF/${project.groupId}/${project.artifactId}/${project.version}/mappings&lt;/outputDirectory&gt;
&lt;includes&gt;
&lt;include&gt;**/*&lt;/include&gt;
&lt;/includes&gt;
&lt;/fileSet&gt;
&lt;fileSet&gt;
&lt;directory&gt;${basedir}/src/test/resources/contracts&lt;/directory&gt;
&lt;outputDirectory&gt;META-INF/${project.groupId}/${project.artifactId}/${project.version}/contracts&lt;/outputDirectory&gt;
&lt;includes&gt;
&lt;include&gt;**/*.groovy&lt;/include&gt;
&lt;/includes&gt;
&lt;/fileSet&gt;
&lt;/fileSets&gt;
&lt;/assembly&gt;</programlisting>
</para>
</formalpara>
<formalpara role="secondary">
<title>Gradle</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">ext {
contractsDir = file("mappings")
stubsOutputDirRoot = file("${project.buildDir}/production/${project.name}-stubs/")
}
// Automatically added by plugin:
// copyContracts - copies contracts to the output folder from which JAR will be created
// verifierStubsJar - JAR with a provided stub suffix
// the presented publication is also added by the plugin but you can modify it as you wish
publishing {
publications {
stubs(MavenPublication) {
artifactId "${project.name}-stubs"
artifact verifierStubsJar
}
}
}</programlisting>
</para>
</formalpara>
</section>
<section xml:id="_stub_runner_core">
<title>Stub Runner Core</title>
<simpara>Runs stubs for service collaborators. Treating stubs as contracts of services allows to use stub-runner as an implementation of
<link xl:href="http://martinfowler.com/articles/consumerDrivenContracts.html">Consumer Driven Contracts</link>.</simpara>
<simpara>Stub Runner allows you to automatically download the stubs of the provided dependencies (or pick those from the classpath), start WireMock servers for them and feed them with proper stub definitions.
For messaging, special stub routes are defined.</simpara>
<section xml:id="_retrieving_stubs">
<title>Retrieving stubs</title>
<simpara>You can pick the following options of acquiring stubs</simpara>
<itemizedlist>
<listitem>
<simpara>Aether based solution that downloads JARs with stubs from Artifactory / Nexus</simpara>
</listitem>
<listitem>
<simpara>Classpath scanning solution that searches classpath via pattern to retrieve stubs</simpara>
</listitem>
<listitem>
<simpara>Write your own implementation of the <literal>org.springframework.cloud.contract.stubrunner.StubDownloaderBuilder</literal> for full customization</simpara>
</listitem>
</itemizedlist>
<simpara>The latter example is described in the <link linkend="custom_stub_runner">Custom Stub Runner</link> section.</simpara>
<section xml:id="_stub_downloading">
<title>Stub downloading</title>
<simpara>You can control the stub downloading via the <literal>stubsMode</literal> switch. It picks value from the
<literal>StubRunnerProperties.StubsMode</literal> enum. You can use the following options</simpara>
<itemizedlist>
<listitem>
<simpara><literal>StubRunnerProperties.StubsMode.CLASSPATH</literal> (default value) - will pick stubs from the classpath</simpara>
</listitem>
<listitem>
<simpara><literal>StubRunnerProperties.StubsMode.LOCAL</literal> - will pick stubs from a local storage (e.g. <literal>.m2</literal>)</simpara>
</listitem>
<listitem>
<simpara><literal>StubRunnerProperties.StubsMode.REMOTE</literal> - will pick stubs from a remote location</simpara>
</listitem>
</itemizedlist>
<simpara>Example:</simpara>
<programlisting language="java" linenumbering="unnumbered">@AutoConfigureStubRunner(repositoryRoot="http://foo.bar", ids = "com.example:beer-api-producer:+:stubs:8095", stubsMode = StubRunnerProperties.StubsMode.LOCAL)</programlisting>
</section>
<section xml:id="_classpath_scanning">
<title>Classpath scanning</title>
<simpara>If you set the <literal>stubsMode</literal> property to <literal>StubRunnerProperties.StubsMode.CLASSPATH</literal>
(or set nothing since <literal>CLASSPATH</literal> is the default value) then classpath will get scanned.
Let&#8217;s look at the following example:</simpara>
<programlisting language="java" linenumbering="unnumbered">@AutoConfigureStubRunner(ids = {
"com.example:beer-api-producer:+:stubs:8095",
"com.example.foo:bar:1.0.0:superstubs:8096"
})</programlisting>
<simpara>If you&#8217;ve added the dependencies to your classpath</simpara>
<formalpara role="primary">
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependency&gt;
&lt;groupId&gt;com.example&lt;/groupId&gt;
&lt;artifactId&gt;beer-api-producer-restdocs&lt;/artifactId&gt;
&lt;classifier&gt;stubs&lt;/classifier&gt;
&lt;version&gt;0.0.1-SNAPSHOT&lt;/version&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;exclusions&gt;
&lt;exclusion&gt;
&lt;groupId&gt;*&lt;/groupId&gt;
&lt;artifactId&gt;*&lt;/artifactId&gt;
&lt;/exclusion&gt;
&lt;/exclusions&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
&lt;groupId&gt;com.example.foo&lt;/groupId&gt;
&lt;artifactId&gt;bar&lt;/artifactId&gt;
&lt;classifier&gt;superstubs&lt;/classifier&gt;
&lt;version&gt;1.0.0&lt;/version&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;exclusions&gt;
&lt;exclusion&gt;
&lt;groupId&gt;*&lt;/groupId&gt;
&lt;artifactId&gt;*&lt;/artifactId&gt;
&lt;/exclusion&gt;
&lt;/exclusions&gt;
&lt;/dependency&gt;</programlisting>
</para>
</formalpara>
<formalpara role="secondary">
<title>Gradle</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">testCompile("com.example:beer-api-producer-restdocs:0.0.1-SNAPSHOT:stubs") {
transitive = false
}
testCompile("com.example.foo:bar:1.0.0:superstubs") {
transitive = false
}</programlisting>
</para>
</formalpara>
<simpara>Then the following locations on your classpath will get scanned. For <literal>com.example:beer-api-producer-restdocs</literal></simpara>
<itemizedlist>
<listitem>
<simpara>/META-INF/com.example/beer-api-producer-restdocs/<emphasis role="strong">*/</emphasis>.*</simpara>
</listitem>
<listitem>
<simpara>/contracts/com.example/beer-api-producer-restdocs/<emphasis role="strong">*/</emphasis>.*</simpara>
</listitem>
<listitem>
<simpara>/mappings/com.example/beer-api-producer-restdocs/<emphasis role="strong">*/</emphasis>.*</simpara>
</listitem>
</itemizedlist>
<simpara>and <literal>com.example.foo:bar</literal></simpara>
<itemizedlist>
<listitem>
<simpara>/META-INF/com.example.foo/bar/<emphasis role="strong">*/</emphasis>.*</simpara>
</listitem>
<listitem>
<simpara>/contracts/com.example.foo/bar/<emphasis role="strong">*/</emphasis>.*</simpara>
</listitem>
<listitem>
<simpara>/mappings/com.example.foo/bar/<emphasis role="strong">*/</emphasis>.*</simpara>
</listitem>
</itemizedlist>
<tip>
<simpara>As you can see you have to explicitly provide the group and artifact ids when packaging the
producer stubs.</simpara>
</tip>
<simpara>The producer would setup the contracts like this:</simpara>
<programlisting language="bash" linenumbering="unnumbered">└── src
└── test
└── resources
└── contracts
   └── com.example
      └── beer-api-producer-restdocs
      └── nested
      └── contract3.groovy</programlisting>
<simpara>To achieve proper stub packaging.</simpara>
<simpara>Or using the <link xl:href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/blob/2.0.x/producer_with_restdocs/pom.xml">Maven <literal>assembly</literal> plugin</link> or
<link xl:href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/blob/2.0.x/producer_with_restdocs/build.gradle">Gradle Jar</link> task you have to create the following
structure in your stubs jar.</simpara>
<programlisting language="bash" linenumbering="unnumbered">└── META-INF
└── com.example
└── beer-api-producer-restdocs
└── 2.0.0
├── contracts
│   └── nested
   │ └── contract2.groovy
   └── mappings
   └── mapping.json</programlisting>
<simpara>By maintaining this structure classpath gets scanned and you can profit from the messaging /
HTTP stubs without the need to download artifacts.</simpara>
</section>
</section>
<section xml:id="_running_stubs">
<title>Running stubs</title>
<section xml:id="_running_using_main_app">
<title>Running using main app</title>
<simpara>You can set the following options to the main class:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">-c, --classifier Suffix for the jar containing stubs (e.
g. 'stubs' if the stub jar would
have a 'stubs' classifier for stubs:
foobar-stubs ). Defaults to 'stubs'
(default: stubs)
--maxPort, --maxp &lt;Integer&gt; Maximum port value to be assigned to
the WireMock instance. Defaults to
15000 (default: 15000)
--minPort, --minp &lt;Integer&gt; Minimum port value to be assigned to
the WireMock instance. Defaults to
10000 (default: 10000)
-p, --password Password to user when connecting to
repository
--phost, --proxyHost Proxy host to use for repository
requests
--pport, --proxyPort [Integer] Proxy port to use for repository
requests
-r, --root Location of a Jar containing server
where you keep your stubs (e.g. http:
//nexus.
net/content/repositories/repository)
-s, --stubs Comma separated list of Ivy
representation of jars with stubs.
Eg. groupid:artifactid1,groupid2:
artifactid2:classifier
--sm, --stubsMode Stubs mode to be used. Acceptable values
[CLASSPATH, LOCAL, REMOTE]
-u, --username Username to user when connecting to
repository</programlisting>
</section>
<section xml:id="_http_stubs">
<title>HTTP Stubs</title>
<simpara>Stubs are defined in JSON documents, whose syntax is defined in <link xl:href="http://wiremock.org/stubbing.html">WireMock documentation</link></simpara>
<simpara>Example:</simpara>
<programlisting language="javascript" linenumbering="unnumbered">{
"request": {
"method": "GET",
"url": "/ping"
},
"response": {
"status": 200,
"body": "pong",
"headers": {
"Content-Type": "text/plain"
}
}
}</programlisting>
</section>
<section xml:id="_viewing_registered_mappings">
<title>Viewing registered mappings</title>
<simpara>Every stubbed collaborator exposes list of defined mappings under <literal>__/admin/</literal> endpoint.</simpara>
<simpara>You can also use the <literal>mappingsOutputFolder</literal> property to dump the mappings to files.
For annotation based approach it would look like this</simpara>
<programlisting language="java" linenumbering="unnumbered">@AutoConfigureStubRunner(ids="a.b.c:loanIssuance,a.b.c:fraudDetectionServer",
mappingsOutputFolder = "target/outputmappings/")</programlisting>
<simpara>and for the JUnit approach like this:</simpara>
<programlisting language="java" linenumbering="unnumbered">@ClassRule @Shared StubRunnerRule rule = new StubRunnerRule()
.repoRoot("http://some_url")
.downloadStub("a.b.c", "loanIssuance")
.downloadStub("a.b.c:fraudDetectionServer")
.withMappingsOutputFolder("target/outputmappings")</programlisting>
<simpara>Then if you check out the folder <literal>target/outputmappings</literal> you would see the following structure</simpara>
<programlisting language="bash" linenumbering="unnumbered">.
├── fraudDetectionServer_13705
└── loanIssuance_12255</programlisting>
<simpara>That means that there were two stubs registered. <literal>fraudDetectionServer</literal> was registered at port <literal>13705</literal>
and <literal>loanIssuance</literal> at port <literal>12255</literal>. If we take a look at one of the files we would see (for WireMock)
mappings available for the given server:</simpara>
<programlisting language="json" linenumbering="unnumbered">[{
"id" : "f9152eb9-bf77-4c38-8289-90be7d10d0d7",
"request" : {
"url" : "/name",
"method" : "GET"
},
"response" : {
"status" : 200,
"body" : "fraudDetectionServer"
},
"uuid" : "f9152eb9-bf77-4c38-8289-90be7d10d0d7"
},
...
]</programlisting>
</section>
<section xml:id="_messaging_stubs">
<title>Messaging Stubs</title>
<simpara>Depending on the provided Stub Runner dependency and the DSL the messaging routes are automatically set up.</simpara>
</section>
</section>
</section>
<section xml:id="_stub_runner_junit_rule_and_stub_runner_junit5_extension">
<title>Stub Runner JUnit Rule and Stub Runner JUnit5 Extension</title>
<simpara>Stub Runner comes with a JUnit rule thanks to which you can very easily download and run stubs for given group and artifact id:</simpara>
<programlisting language="java" linenumbering="unnumbered">@ClassRule public static StubRunnerRule rule = new StubRunnerRule()
.repoRoot(repoRoot())
.stubsMode(StubRunnerProperties.StubsMode.REMOTE)
.downloadStub("org.springframework.cloud.contract.verifier.stubs", "loanIssuance")
.downloadStub("org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer");</programlisting>
<simpara>There&#8217;s also a <literal>StubRunnerExtension</literal> available for JUnit 5. <literal>StubRunnerRule</literal> and <literal>StubRunnerExtension</literal> work in a very
similar fashion. After the rule/ extension is executed, Stub Runner connects to your Maven repository and for the given list of dependencies tries to:</simpara>
<itemizedlist>
<listitem>
<simpara>download them</simpara>
</listitem>
<listitem>
<simpara>cache them locally</simpara>
</listitem>
<listitem>
<simpara>unzip them to a temporary folder</simpara>
</listitem>
<listitem>
<simpara>start a WireMock server for each Maven dependency on a random port from the provided range of ports / provided port</simpara>
</listitem>
<listitem>
<simpara>feed the WireMock server with all JSON files that are valid WireMock definitions</simpara>
</listitem>
<listitem>
<simpara>can also send messages (remember to pass an implementation of <literal>MessageVerifier</literal> interface)</simpara>
</listitem>
</itemizedlist>
<simpara>Stub Runner uses <link xl:href="https://wiki.eclipse.org/Aether">Eclipse Aether</link> mechanism to download the Maven dependencies.
Check their <link xl:href="https://wiki.eclipse.org/Aether">docs</link> for more information.</simpara>
<simpara>Since the <literal>StubRunnerRule</literal> and <literal>StubRunnerExtension</literal> implement the <literal>StubFinder</literal> they allow you to find the started stubs:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">package org.springframework.cloud.contract.stubrunner;
import java.net.URL;
import java.util.Collection;
import java.util.Map;
import org.springframework.cloud.contract.spec.Contract;
public interface StubFinder extends StubTrigger {
/**
* For the given groupId and artifactId tries to find the matching URL of the running
* stub.
* @param groupId - might be null. In that case a search only via artifactId takes
* place
* @return URL of a running stub or throws exception if not found
*/
URL findStubUrl(String groupId, String artifactId) throws StubNotFoundException;
/**
* For the given Ivy notation {@code [groupId]:artifactId:[version]:[classifier]}
* tries to find the matching URL of the running stub. You can also pass only
* {@code artifactId}.
* @param ivyNotation - Ivy representation of the Maven artifact
* @return URL of a running stub or throws exception if not found
*/
URL findStubUrl(String ivyNotation) throws StubNotFoundException;
/**
* Returns all running stubs
*/
RunningStubs findAllRunningStubs();
/**
* Returns the list of Contracts
*/
Map&lt;StubConfiguration, Collection&lt;Contract&gt;&gt; getContracts();
}</programlisting>
<simpara>Example of usage in Spock tests:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">@ClassRule @Shared StubRunnerRule rule = new StubRunnerRule()
.stubsMode(StubRunnerProperties.StubsMode.REMOTE)
.repoRoot(StubRunnerRuleSpec.getResource("/m2repo/repository").toURI().toString())
.downloadStub("org.springframework.cloud.contract.verifier.stubs", "loanIssuance")
.downloadStub("org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer")
.withMappingsOutputFolder("target/outputmappingsforrule")
def 'should start WireMock servers'() {
expect: 'WireMocks are running'
rule.findStubUrl('org.springframework.cloud.contract.verifier.stubs', 'loanIssuance') != null
rule.findStubUrl('loanIssuance') != null
rule.findStubUrl('loanIssuance') == rule.findStubUrl('org.springframework.cloud.contract.verifier.stubs', 'loanIssuance')
rule.findStubUrl('org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer') != null
and:
rule.findAllRunningStubs().isPresent('loanIssuance')
rule.findAllRunningStubs().isPresent('org.springframework.cloud.contract.verifier.stubs', 'fraudDetectionServer')
rule.findAllRunningStubs().isPresent('org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer')
and: 'Stubs were registered'
"${rule.findStubUrl('loanIssuance').toString()}/name".toURL().text == 'loanIssuance'
"${rule.findStubUrl('fraudDetectionServer').toString()}/name".toURL().text == 'fraudDetectionServer'
}
def 'should output mappings to output folder'() {
when:
def url = rule.findStubUrl('fraudDetectionServer')
then:
new File("target/outputmappingsforrule", "fraudDetectionServer_${url.port}").exists()
}</programlisting>
<simpara>Example of usage in JUnit tests:</simpara>
<programlisting language="java" linenumbering="unnumbered">@Test
public void should_start_wiremock_servers() throws Exception {
// expect: 'WireMocks are running'
then(rule.findStubUrl("org.springframework.cloud.contract.verifier.stubs", "loanIssuance")).isNotNull();
then(rule.findStubUrl("loanIssuance")).isNotNull();
then(rule.findStubUrl("loanIssuance")).isEqualTo(rule.findStubUrl("org.springframework.cloud.contract.verifier.stubs", "loanIssuance"));
then(rule.findStubUrl("org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer")).isNotNull();
// and:
then(rule.findAllRunningStubs().isPresent("loanIssuance")).isTrue();
then(rule.findAllRunningStubs().isPresent("org.springframework.cloud.contract.verifier.stubs", "fraudDetectionServer")).isTrue();
then(rule.findAllRunningStubs().isPresent("org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer")).isTrue();
// and: 'Stubs were registered'
then(httpGet(rule.findStubUrl("loanIssuance").toString() + "/name")).isEqualTo("loanIssuance");
then(httpGet(rule.findStubUrl("fraudDetectionServer").toString() + "/name")).isEqualTo("fraudDetectionServer");
}</programlisting>
<simpara>JUnit 5 Extension example:</simpara>
<programlisting language="java" linenumbering="unnumbered">// Visible for Junit
@RegisterExtension
static StubRunnerExtension stubRunnerExtension = new StubRunnerExtension()
.repoRoot(repoRoot())
.stubsMode(StubRunnerProperties.StubsMode.REMOTE)
.downloadStub("org.springframework.cloud.contract.verifier.stubs", "loanIssuance")
.downloadStub("org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer")
.withMappingsOutputFolder("target/outputmappingsforrule");
@Test
void should_start_WireMock_servers() {
assertThat(stubRunnerExtension.findStubUrl("org.springframework.cloud.contract.verifier.stubs",
"loanIssuance")).isNotNull();
assertThat(stubRunnerExtension.findStubUrl("loanIssuance")).isNotNull();
assertThat(stubRunnerExtension.findStubUrl("loanIssuance")).isEqualTo(stubRunnerExtension
.findStubUrl("org.springframework.cloud.contract.verifier.stubs", "loanIssuance"));
assertThat(stubRunnerExtension
.findStubUrl("org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer")).isNotNull();
}</programlisting>
<simpara>Check the <emphasis role="strong">Common properties for JUnit and Spring</emphasis> for more information on how to apply global configuration of Stub Runner.</simpara>
<important>
<simpara>To use the JUnit rule or JUnit 5 extension together with messaging, you have to provide an implementation of the
<literal>MessageVerifier</literal> interface to the rule builder (e.g. <literal>rule.messageVerifier(new MyMessageVerifier())</literal>).
If you don&#8217;t do this, then whenever you try to send a message an exception will be thrown.</simpara>
</important>
<section xml:id="_maven_settings">
<title>Maven settings</title>
<simpara>The stub downloader honors Maven settings for a different local repository folder.
Authentication details for repositories and profiles are currently not taken into account, so you need to specify it using the properties mentioned above.</simpara>
</section>
<section xml:id="_providing_fixed_ports">
<title>Providing fixed ports</title>
<simpara>You can also run your stubs on fixed ports. You can do it in two different ways. One is to pass it in the properties, and the other via fluent API of
JUnit rule.</simpara>
</section>
<section xml:id="_fluent_api">
<title>Fluent API</title>
<simpara>When using the <literal>StubRunnerRule</literal> or <literal>StubRunnerExtension</literal> you can add a stub to download and then pass the port for the last downloaded stub.</simpara>
<programlisting language="java" linenumbering="unnumbered">@ClassRule public static StubRunnerRule rule = new StubRunnerRule()
.repoRoot(repoRoot())
.stubsMode(StubRunnerProperties.StubsMode.REMOTE)
.downloadStub("org.springframework.cloud.contract.verifier.stubs", "loanIssuance")
.withPort(12345)
.downloadStub("org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer:12346");</programlisting>
<simpara>You can see that for this example the following test is valid:</simpara>
<programlisting language="java" linenumbering="unnumbered">then(rule.findStubUrl("loanIssuance")).isEqualTo(URI.create("http://localhost:12345").toURL());
then(rule.findStubUrl("fraudDetectionServer")).isEqualTo(URI.create("http://localhost:12346").toURL());</programlisting>
</section>
<section xml:id="_stub_runner_with_spring">
<title>Stub Runner with Spring</title>
<simpara>Sets up Spring configuration of the Stub Runner project.</simpara>
<simpara>By providing a list of stubs inside your configuration file the Stub Runner automatically downloads
and registers in WireMock the selected stubs.</simpara>
<simpara>If you want to find the URL of your stubbed dependency you can autowire the <literal>StubFinder</literal> interface and use
its methods as presented below:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">@ContextConfiguration(classes = Config, loader = SpringBootContextLoader)
@SpringBootTest(properties = [" stubrunner.cloud.enabled=false",
'foo=${stubrunner.runningstubs.fraudDetectionServer.port}',
'fooWithGroup=${stubrunner.runningstubs.org.springframework.cloud.contract.verifier.stubs.fraudDetectionServer.port}'])
@AutoConfigureStubRunner(mappingsOutputFolder = "target/outputmappings/")
@ActiveProfiles("test")
class StubRunnerConfigurationSpec extends Specification {
@Autowired StubFinder stubFinder
@Autowired Environment environment
@StubRunnerPort("fraudDetectionServer") int fraudDetectionServerPort
@StubRunnerPort("org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer") int fraudDetectionServerPortWithGroupId
@Value('${foo}') Integer foo
@BeforeClass
@AfterClass
void setupProps() {
System.clearProperty("stubrunner.repository.root")
System.clearProperty("stubrunner.classifier")
}
def 'should start WireMock servers'() {
expect: 'WireMocks are running'
stubFinder.findStubUrl('org.springframework.cloud.contract.verifier.stubs', 'loanIssuance') != null
stubFinder.findStubUrl('loanIssuance') != null
stubFinder.findStubUrl('loanIssuance') == stubFinder.findStubUrl('org.springframework.cloud.contract.verifier.stubs', 'loanIssuance')
stubFinder.findStubUrl('loanIssuance') == stubFinder.findStubUrl('org.springframework.cloud.contract.verifier.stubs:loanIssuance')
stubFinder.findStubUrl('org.springframework.cloud.contract.verifier.stubs:loanIssuance:0.0.1-SNAPSHOT') == stubFinder.findStubUrl('org.springframework.cloud.contract.verifier.stubs:loanIssuance:0.0.1-SNAPSHOT:stubs')
stubFinder.findStubUrl('org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer') != null
and:
stubFinder.findAllRunningStubs().isPresent('loanIssuance')
stubFinder.findAllRunningStubs().isPresent('org.springframework.cloud.contract.verifier.stubs', 'fraudDetectionServer')
stubFinder.findAllRunningStubs().isPresent('org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer')
and: 'Stubs were registered'
"${stubFinder.findStubUrl('loanIssuance').toString()}/name".toURL().text == 'loanIssuance'
"${stubFinder.findStubUrl('fraudDetectionServer').toString()}/name".toURL().text == 'fraudDetectionServer'
}
def 'should throw an exception when stub is not found'() {
when:
stubFinder.findStubUrl('nonExistingService')
then:
thrown(StubNotFoundException)
when:
stubFinder.findStubUrl('nonExistingGroupId', 'nonExistingArtifactId')
then:
thrown(StubNotFoundException)
}
def 'should register started servers as environment variables'() {
expect:
environment.getProperty("stubrunner.runningstubs.loanIssuance.port") != null
stubFinder.findAllRunningStubs().getPort("loanIssuance") == (environment.getProperty("stubrunner.runningstubs.loanIssuance.port") as Integer)
and:
environment.getProperty("stubrunner.runningstubs.fraudDetectionServer.port") != null
stubFinder.findAllRunningStubs().getPort("fraudDetectionServer") == (environment.getProperty("stubrunner.runningstubs.fraudDetectionServer.port") as Integer)
and:
environment.getProperty("stubrunner.runningstubs.fraudDetectionServer.port") != null
stubFinder.findAllRunningStubs().getPort("fraudDetectionServer") == (environment.getProperty("stubrunner.runningstubs.org.springframework.cloud.contract.verifier.stubs.fraudDetectionServer.port") as Integer)
}
def 'should be able to interpolate a running stub in the passed test property'() {
given:
int fraudPort = stubFinder.findAllRunningStubs().getPort("fraudDetectionServer")
expect:
fraudPort &gt; 0
environment.getProperty("foo", Integer) == fraudPort
environment.getProperty("fooWithGroup", Integer) == fraudPort
foo == fraudPort
}
@Issue("#573")
def 'should be able to retrieve the port of a running stub via an annotation'() {
given:
int fraudPort = stubFinder.findAllRunningStubs().getPort("fraudDetectionServer")
expect:
fraudPort &gt; 0
fraudDetectionServerPort == fraudPort
fraudDetectionServerPortWithGroupId == fraudPort
}
def 'should dump all mappings to a file'() {
when:
def url = stubFinder.findStubUrl("fraudDetectionServer")
then:
new File("target/outputmappings/", "fraudDetectionServer_${url.port}").exists()
}
@Configuration
@EnableAutoConfiguration
static class Config {}
}
// end::test[]</programlisting>
<simpara>for the following configuration file:</simpara>
<programlisting language="yml" linenumbering="unnumbered">stubrunner:
repositoryRoot: classpath:m2repo/repository/
ids:
- org.springframework.cloud.contract.verifier.stubs:loanIssuance
- org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer
- org.springframework.cloud.contract.verifier.stubs:bootService
stubs-mode: remote</programlisting>
<simpara>Instead of using the properties you can also use the properties inside the <literal>@AutoConfigureStubRunner</literal>.
Below you can find an example of achieving the same result by setting values on the annotation.</simpara>
<programlisting language="groovy" linenumbering="unnumbered">@AutoConfigureStubRunner(
ids = ["org.springframework.cloud.contract.verifier.stubs:loanIssuance",
"org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer",
"org.springframework.cloud.contract.verifier.stubs:bootService"],
stubsMode = StubRunnerProperties.StubsMode.REMOTE,
repositoryRoot = "classpath:m2repo/repository/")</programlisting>
<simpara>Stub Runner Spring registers environment variables in the following manner
for every registered WireMock server. Example for Stub Runner ids
<literal>com.example:foo</literal>, <literal>com.example:bar</literal>.</simpara>
<itemizedlist>
<listitem>
<simpara><literal>stubrunner.runningstubs.foo.port</literal></simpara>
</listitem>
<listitem>
<simpara><literal>stubrunner.runningstubs.com.example.foo.port</literal></simpara>
</listitem>
<listitem>
<simpara><literal>stubrunner.runningstubs.bar.port</literal></simpara>
</listitem>
<listitem>
<simpara><literal>stubrunner.runningstubs.com.example.bar.port</literal></simpara>
</listitem>
</itemizedlist>
<simpara>Which you can reference in your code.</simpara>
<simpara>You can also use the <literal>@StubRunnerPort</literal> annotation to inject the port of a running stub.
Value of the annotation can be the <literal>groupid:artifactid</literal> or just the <literal>artifactid</literal>. Example for Stub Runner ids
<literal>com.example:foo</literal>, <literal>com.example:bar</literal>.</simpara>
<programlisting language="java" linenumbering="unnumbered">@StubRunnerPort("foo")
int fooPort;
@StubRunnerPort("com.example:bar")
int barPort;</programlisting>
</section>
</section>
<section xml:id="_stub_runner_spring_cloud">
<title>Stub Runner Spring Cloud</title>
<simpara>Stub Runner can integrate with Spring Cloud.</simpara>
<simpara>For real life examples you can check the</simpara>
<itemizedlist>
<listitem>
<simpara><link xl:href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/2.0.x/producer">producer app sample</link></simpara>
</listitem>
<listitem>
<simpara><link xl:href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/2.0.x/consumer_with_discovery">consumer app sample</link></simpara>
</listitem>
</itemizedlist>
<section xml:id="_stubbing_service_discovery">
<title>Stubbing Service Discovery</title>
<simpara>The most important feature of <literal>Stub Runner Spring Cloud</literal> is the fact that it&#8217;s stubbing</simpara>
<itemizedlist>
<listitem>
<simpara><literal>DiscoveryClient</literal></simpara>
</listitem>
<listitem>
<simpara><literal>Ribbon</literal> <literal>ServerList</literal></simpara>
</listitem>
</itemizedlist>
<simpara>that means that regardless of the fact whether you&#8217;re using Zookeeper, Consul, Eureka or anything else, you don&#8217;t need that in your tests.
We&#8217;re starting WireMock instances of your dependencies and we&#8217;re telling your application whenever you&#8217;re using <literal>Feign</literal>, load balanced <literal>RestTemplate</literal>
or <literal>DiscoveryClient</literal> directly, to call those stubbed servers instead of calling the real Service Discovery tool.</simpara>
<simpara>For example this test will pass</simpara>
<programlisting language="groovy" linenumbering="unnumbered">def 'should make service discovery work'() {
expect: 'WireMocks are running'
"${stubFinder.findStubUrl('loanIssuance').toString()}/name".toURL().text == 'loanIssuance'
"${stubFinder.findStubUrl('fraudDetectionServer').toString()}/name".toURL().text == 'fraudDetectionServer'
and: 'Stubs can be reached via load service discovery'
restTemplate.getForObject('http://loanIssuance/name', String) == 'loanIssuance'
restTemplate.getForObject('http://someNameThatShouldMapFraudDetectionServer/name', String) == 'fraudDetectionServer'
}</programlisting>
<simpara>for the following configuration file</simpara>
<programlisting language="yml" linenumbering="unnumbered">stubrunner:
idsToServiceIds:
ivyNotation: someValueInsideYourCode
fraudDetectionServer: someNameThatShouldMapFraudDetectionServer
# end::ids[]</programlisting>
<section xml:id="_test_profiles_and_service_discovery">
<title>Test profiles and service discovery</title>
<simpara>In your integration tests you typically don&#8217;t want to call neither a discovery service (e.g. Eureka)
or Config Server. That&#8217;s why you create an additional test configuration in which you want to disable
these features.</simpara>
<simpara>Due to certain limitations of <link xl:href="https://github.com/spring-cloud/spring-cloud-commons/issues/156"><literal>spring-cloud-commons</literal></link> to achieve this you have disable these properties
via a static block like presented below (example for Eureka)</simpara>
<programlisting language="java" linenumbering="unnumbered"> //Hack to work around https://github.com/spring-cloud/spring-cloud-commons/issues/156
static {
System.setProperty("eureka.client.enabled", "false");
System.setProperty("spring.cloud.config.failFast", "false");
}</programlisting>
</section>
</section>
<section xml:id="_additional_configuration">
<title>Additional Configuration</title>
<simpara>You can match the artifactId of the stub with the name of your app by using the <literal>stubrunner.idsToServiceIds:</literal> map.
You can disable Stub Runner Ribbon support by providing: <literal>stubrunner.cloud.ribbon.enabled</literal> equal to <literal>false</literal>
You can disable Stub Runner support by providing: <literal>stubrunner.cloud.enabled</literal> equal to <literal>false</literal></simpara>
<tip>
<simpara>By default all service discovery will be stubbed. That means that regardless of the fact if you have
an existing <literal>DiscoveryClient</literal> its results will be ignored. However, if you want to reuse it, just set
<literal>stubrunner.cloud.delegate.enabled</literal> to <literal>true</literal> and then your existing <literal>DiscoveryClient</literal> results will be
merged with the stubbed ones.</simpara>
</tip>
<simpara>The default Maven configuration used by Stub Runner can be tweaked either
via the following system properties or environment variables</simpara>
<itemizedlist>
<listitem>
<simpara><literal>maven.repo.local</literal> - path to the custom maven local repository location</simpara>
</listitem>
<listitem>
<simpara><literal>org.apache.maven.user-settings</literal> - path to custom maven user settings location</simpara>
</listitem>
<listitem>
<simpara><literal>org.apache.maven.global-settings</literal> - path to maven global settings location</simpara>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="_stub_runner_boot_application">
<title>Stub Runner Boot Application</title>
<simpara>Spring Cloud Contract Stub Runner Boot is a Spring Boot application that exposes REST endpoints to
trigger the messaging labels and to access started WireMock servers.</simpara>
<simpara>One of the use-cases is to run some smoke (end to end) tests on a deployed application.
You can check out the <link xl:href="https://github.com/spring-cloud/spring-cloud-pipelines">Spring Cloud Pipelines</link>
project for more information.</simpara>
<section xml:id="_how_to_use_it">
<title>How to use it?</title>
<section xml:id="_stub_runner_server">
<title>Stub Runner Server</title>
<simpara>Just add the</simpara>
<programlisting language="groovy" linenumbering="unnumbered">compile "org.springframework.cloud:spring-cloud-starter-stub-runner"</programlisting>
<simpara>Annotate a class with <literal>@EnableStubRunnerServer</literal>, build a fat-jar and you&#8217;re ready to go!</simpara>
<simpara>For the properties check the <emphasis role="strong">Stub Runner Spring</emphasis> section.</simpara>
</section>
<section xml:id="_stub_runner_server_fat_jar">
<title>Stub Runner Server Fat Jar</title>
<simpara>You can download a standalone JAR from Maven (e.g. for version 2.0.1.RELEASE), as follows:</simpara>
<programlisting language="bash" linenumbering="unnumbered">$ wget -O stub-runner.jar 'https://search.maven.org/remotecontent?filepath=org/springframework/cloud/spring-cloud-contract-stub-runner-boot/2.0.1.RELEASE/spring-cloud-contract-stub-runner-boot-2.0.1.RELEASE.jar'
$ java -jar stub-runner.jar --stubrunner.ids=... --stubrunner.repositoryRoot=...</programlisting>
</section>
<section xml:id="_spring_cloud_cli">
<title>Spring Cloud CLI</title>
<simpara>Starting from <literal>1.4.0.RELEASE</literal> version of the <link xl:href="http://cloud.spring.io/spring-cloud-cli">Spring Cloud CLI</link>
project you can start Stub Runner Boot by executing <literal>spring cloud stubrunner</literal>.</simpara>
<simpara>In order to pass the configuration just create a <literal>stubrunner.yml</literal> file in the current working directory
or a subdirectory called <literal>config</literal> or in <literal>~/.spring-cloud</literal>. The file could look like this
(example for running stubs installed locally)</simpara>
<formalpara>
<title>stubrunner.yml</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">stubrunner:
stubsMode: LOCAL
ids:
- com.example:beer-api-producer:+:9876</programlisting>
</para>
</formalpara>
<simpara>and then just call <literal>spring cloud stubrunner</literal> from your terminal window to start
the Stub Runner server. It will be available at port <literal>8750</literal>.</simpara>
</section>
</section>
<section xml:id="_endpoints">
<title>Endpoints</title>
<section xml:id="_http">
<title>HTTP</title>
<itemizedlist>
<listitem>
<simpara>GET <literal>/stubs</literal> - returns a list of all running stubs in <literal>ivy:integer</literal> notation</simpara>
</listitem>
<listitem>
<simpara>GET <literal>/stubs/{ivy}</literal> - returns a port for the given <literal>ivy</literal> notation (when calling the endpoint <literal>ivy</literal> can also be <literal>artifactId</literal> only)</simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="_messaging">
<title>Messaging</title>
<simpara>For Messaging</simpara>
<itemizedlist>
<listitem>
<simpara>GET <literal>/triggers</literal> - returns a list of all running labels in <literal>ivy : [ label1, label2 &#8230;&#8203;]</literal> notation</simpara>
</listitem>
<listitem>
<simpara>POST <literal>/triggers/{label}</literal> - executes a trigger with <literal>label</literal></simpara>
</listitem>
<listitem>
<simpara>POST <literal>/triggers/{ivy}/{label}</literal> - executes a trigger with <literal>label</literal> for the given <literal>ivy</literal> notation (when calling the endpoint <literal>ivy</literal> can also be <literal>artifactId</literal> only)</simpara>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="_example">
<title>Example</title>
<programlisting language="groovy" linenumbering="unnumbered">@ContextConfiguration(classes = StubRunnerBoot, loader = SpringBootContextLoader)
@SpringBootTest(properties = "spring.cloud.zookeeper.enabled=false")
@ActiveProfiles("test")
class StubRunnerBootSpec extends Specification {
@Autowired StubRunning stubRunning
def setup() {
RestAssuredMockMvc.standaloneSetup(new HttpStubsController(stubRunning),
new TriggerController(stubRunning))
}
def 'should return a list of running stub servers in "full ivy:port" notation'() {
when:
String response = RestAssuredMockMvc.get('/stubs').body.asString()
then:
def root = new JsonSlurper().parseText(response)
root.'org.springframework.cloud.contract.verifier.stubs:bootService:0.0.1-SNAPSHOT:stubs' instanceof Integer
}
def 'should return a port on which a [#stubId] stub is running'() {
when:
def response = RestAssuredMockMvc.get("/stubs/${stubId}")
then:
response.statusCode == 200
Integer.valueOf(response.body.asString()) &gt; 0
where:
stubId &lt;&lt; ['org.springframework.cloud.contract.verifier.stubs:bootService:+:stubs',
'org.springframework.cloud.contract.verifier.stubs:bootService:0.0.1-SNAPSHOT:stubs',
'org.springframework.cloud.contract.verifier.stubs:bootService:+',
'org.springframework.cloud.contract.verifier.stubs:bootService',
'bootService']
}
def 'should return 404 when missing stub was called'() {
when:
def response = RestAssuredMockMvc.get("/stubs/a:b:c:d")
then:
response.statusCode == 404
}
def 'should return a list of messaging labels that can be triggered when version and classifier are passed'() {
when:
String response = RestAssuredMockMvc.get('/triggers').body.asString()
then:
def root = new JsonSlurper().parseText(response)
root.'org.springframework.cloud.contract.verifier.stubs:bootService:0.0.1-SNAPSHOT:stubs'?.containsAll(["delete_book","return_book_1","return_book_2"])
}
def 'should trigger a messaging label'() {
given:
StubRunning stubRunning = Mock()
RestAssuredMockMvc.standaloneSetup(new HttpStubsController(stubRunning), new TriggerController(stubRunning))
when:
def response = RestAssuredMockMvc.post("/triggers/delete_book")
then:
response.statusCode == 200
and:
1 * stubRunning.trigger('delete_book')
}
def 'should trigger a messaging label for a stub with [#stubId] ivy notation'() {
given:
StubRunning stubRunning = Mock()
RestAssuredMockMvc.standaloneSetup(new HttpStubsController(stubRunning), new TriggerController(stubRunning))
when:
def response = RestAssuredMockMvc.post("/triggers/$stubId/delete_book")
then:
response.statusCode == 200
and:
1 * stubRunning.trigger(stubId, 'delete_book')
where:
stubId &lt;&lt; ['org.springframework.cloud.contract.verifier.stubs:bootService:stubs', 'org.springframework.cloud.contract.verifier.stubs:bootService', 'bootService']
}
def 'should throw exception when trigger is missing'() {
when:
RestAssuredMockMvc.post("/triggers/missing_label")
then:
Exception e = thrown(Exception)
e.message.contains("Exception occurred while trying to return [missing_label] label.")
e.message.contains("Available labels are")
e.message.contains("org.springframework.cloud.contract.verifier.stubs:loanIssuance:0.0.1-SNAPSHOT:stubs=[]")
e.message.contains("org.springframework.cloud.contract.verifier.stubs:bootService:0.0.1-SNAPSHOT:stubs=")
}
}</programlisting>
</section>
<section xml:id="_stub_runner_boot_with_service_discovery">
<title>Stub Runner Boot with Service Discovery</title>
<simpara>One of the possibilities of using Stub Runner Boot is to use it as a feed of stubs for "smoke-tests". What does it mean?
Let&#8217;s assume that you don&#8217;t want to deploy 50 microservice to a test environment in order
to check if your application is working fine. You&#8217;ve already executed a suite of tests during the build process
but you would also like to ensure that the packaging of your application is fine. What you can do
is to deploy your application to an environment, start it and run a couple of tests on it to see if
it&#8217;s working fine. We can call those tests smoke-tests since their idea is to check only a handful
of testing scenarios.</simpara>
<simpara>The problem with this approach is such that if you&#8217;re doing microservices most likely you&#8217;re
using a service discovery tool. Stub Runner Boot allows you to solve this issue by starting the
required stubs and register them in a service discovery tool. Let&#8217;s take a look at an example of
such a setup with Eureka. Let&#8217;s assume that Eureka was already running.</simpara>
<programlisting language="java" linenumbering="unnumbered">@SpringBootApplication
@EnableStubRunnerServer
@EnableEurekaClient
@AutoConfigureStubRunner
public class StubRunnerBootEurekaExample {
public static void main(String[] args) {
SpringApplication.run(StubRunnerBootEurekaExample.class, args);
}
}</programlisting>
<simpara>As you can see we want to start a Stub Runner Boot server <literal>@EnableStubRunnerServer</literal>, enable Eureka client <literal>@EnableEurekaClient</literal>
and we want to have the stub runner feature turned on <literal>@AutoConfigureStubRunner</literal>.</simpara>
<simpara>Now let&#8217;s assume that we want to start this application so that the stubs get automatically registered.
We can do it by running the app <literal>java -jar ${SYSTEM_PROPS} stub-runner-boot-eureka-example.jar</literal> where
<literal>${SYSTEM_PROPS}</literal> would contain the following list of properties</simpara>
<programlisting language="bash" linenumbering="unnumbered">-Dstubrunner.repositoryRoot=http://repo.spring.io/snapshots (1)
-Dstubrunner.cloud.stubbed.discovery.enabled=false (2)
-Dstubrunner.ids=org.springframework.cloud.contract.verifier.stubs:loanIssuance,org.springframework.cloud.contract.verifier.stubs:fraudDetectionServer,org.springframework.cloud.contract.verifier.stubs:bootService (3)
-Dstubrunner.idsToServiceIds.fraudDetectionServer=someNameThatShouldMapFraudDetectionServer (4)
(1) - we tell Stub Runner where all the stubs reside
(2) - we don't want the default behaviour where the discovery service is stubbed. That's why the stub registration will be picked
(3) - we provide a list of stubs to download
(4) - we provide a list of artifactId to serviceId mapping</programlisting>
<simpara>That way your deployed application can send requests to started WireMock servers via the service
discovery. Most likely points 1-3 could be set by default in <literal>application.yml</literal> cause they are not
likely to change. That way you can provide only the list of stubs to download whenever you start
the Stub Runner Boot.</simpara>
</section>
</section>
<section xml:id="_stubs_per_consumer">
<title>Stubs Per Consumer</title>
<simpara>There are cases in which 2 consumers of the same endpoint want to have 2 different responses.</simpara>
<tip>
<simpara>This approach also allows you to immediately know which consumer is using which part of your API.
You can remove part of a response that your API produces and you can see which of your autogenerated tests
fails. If none fails then you can safely delete that part of the response cause nobody is using it.</simpara>
</tip>
<simpara>Let&#8217;s look at the following example for contract defined for the producer called <literal>producer</literal>.
There are 2 consumers: <literal>foo-consumer</literal> and <literal>bar-consumer</literal>.</simpara>
<simpara><emphasis role="strong">Consumer <literal>foo-service</literal></emphasis></simpara>
<programlisting language="groovy" linenumbering="unnumbered">request {
url '/foo'
method GET()
}
response {
status OK()
body(
foo: "foo"
}
}</programlisting>
<simpara><emphasis role="strong">Consumer <literal>bar-service</literal></emphasis></simpara>
<programlisting language="groovy" linenumbering="unnumbered">request {
url '/foo'
method GET()
}
response {
status OK()
body(
bar: "bar"
}
}</programlisting>
<simpara>You can&#8217;t produce for the same request 2 different responses. That&#8217;s why you can properly package the
contracts and then profit from the <literal>stubsPerConsumer</literal> feature.</simpara>
<simpara>On the producer side the consumers can have a folder that contains contracts related only to them.
By setting the <literal>stubrunner.stubs-per-consumer</literal> flag to <literal>true</literal> we no longer register all stubs but only those that
correspond to the consumer application&#8217;s name. In other words we&#8217;ll scan the path of every stub and
if it contains the subfolder with name of the consumer in the path only then will it get registered.</simpara>
<simpara>On the <literal>foo</literal> producer side the contracts would look like this</simpara>
<programlisting language="bash" linenumbering="unnumbered">.
└── contracts
├── bar-consumer
│   ├── bookReturnedForBar.groovy
│   └── shouldCallBar.groovy
└── foo-consumer
├── bookReturnedForFoo.groovy
└── shouldCallFoo.groovy</programlisting>
<simpara>Being the <literal>bar-consumer</literal> consumer you can either set the <literal>spring.application.name</literal> or the <literal>stubrunner.consumer-name</literal> to <literal>bar-consumer</literal>
Or set the test as follows:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">@ContextConfiguration(classes = Config, loader = SpringBootContextLoader)
@SpringBootTest(properties = ["spring.application.name=bar-consumer"])
@AutoConfigureStubRunner(ids = "org.springframework.cloud.contract.verifier.stubs:producerWithMultipleConsumers",
repositoryRoot = "classpath:m2repo/repository/",
stubsMode = StubRunnerProperties.StubsMode.REMOTE,
stubsPerConsumer = true)
class StubRunnerStubsPerConsumerSpec extends Specification {
...
}</programlisting>
<simpara>Then only the stubs registered under a path that contains the <literal>bar-consumer</literal> in its name (i.e. those from the
<literal>src/test/resources/contracts/bar-consumer/some/contracts/&#8230;&#8203;</literal> folder) will be allowed to be referenced.</simpara>
<simpara>Or set the consumer name explicitly</simpara>
<programlisting language="groovy" linenumbering="unnumbered">@ContextConfiguration(classes = Config, loader = SpringBootContextLoader)
@SpringBootTest
@AutoConfigureStubRunner(ids = "org.springframework.cloud.contract.verifier.stubs:producerWithMultipleConsumers",
repositoryRoot = "classpath:m2repo/repository/",
consumerName = "foo-consumer",
stubsMode = StubRunnerProperties.StubsMode.REMOTE,
stubsPerConsumer = true)
class StubRunnerStubsPerConsumerWithConsumerNameSpec extends Specification {
...
}</programlisting>
<simpara>Then only the stubs registered under a path that contains the <literal>foo-consumer</literal> in its name (i.e. those from the
<literal>src/test/resources/contracts/foo-consumer/some/contracts/&#8230;&#8203;</literal> folder) will be allowed to be referenced.</simpara>
<simpara>You can check out <link xl:href="https://github.com/spring-cloud/spring-cloud-contract/issues/224">issue 224</link> for more
information about the reasons behind this change.</simpara>
</section>
<section xml:id="_common">
<title>Common</title>
<simpara>This section briefly describes common properties, including:</simpara>
<itemizedlist>
<listitem>
<simpara><xref linkend="common-properties-junit-spring"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="stub-runner-stub-ids"/></simpara>
</listitem>
</itemizedlist>
<section xml:id="common-properties-junit-spring">
<title>Common Properties for JUnit and Spring</title>
<simpara>You can set repetitive properties by using system properties or Spring configuration
properties. Here are their names with their default values:</simpara>
<informaltable frame="topbot" rowsep="1" colsep="1">
<tgroup cols="3">
<colspec colname="col_1" colwidth="33.3333*"/>
<colspec colname="col_2" colwidth="33.3333*"/>
<colspec colname="col_3" colwidth="33.3334*"/>
<thead>
<row>
<entry align="left" valign="top">Property name</entry>
<entry align="left" valign="top">Default value</entry>
<entry align="left" valign="top">Description</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top"><simpara>stubrunner.minPort</simpara></entry>
<entry align="left" valign="top"><simpara>10000</simpara></entry>
<entry align="left" valign="top"><simpara>Minimum value of a port for a started WireMock with stubs.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>stubrunner.maxPort</simpara></entry>
<entry align="left" valign="top"><simpara>15000</simpara></entry>
<entry align="left" valign="top"><simpara>Maximum value of a port for a started WireMock with stubs.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>stubrunner.repositoryRoot</simpara></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><simpara>Maven repo URL. If blank, then call the local maven repo.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>stubrunner.classifier</simpara></entry>
<entry align="left" valign="top"><simpara>stubs</simpara></entry>
<entry align="left" valign="top"><simpara>Default classifier for the stub artifacts.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>stubrunner.stubsMode</simpara></entry>
<entry align="left" valign="top"><simpara>CLASSPATH</simpara></entry>
<entry align="left" valign="top"><simpara>The way you want to fetch and register the stubs</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>stubrunner.ids</simpara></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><simpara>Array of Ivy notation stubs to download.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>stubrunner.username</simpara></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><simpara>Optional username to access the tool that stores the JARs with
stubs.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>stubrunner.password</simpara></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><simpara>Optional password to access the tool that stores the JARs with
stubs.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>stubrunner.stubsPerConsumer</simpara></entry>
<entry align="left" valign="top"><simpara>false</simpara></entry>
<entry align="left" valign="top"><simpara>Set to <literal>true</literal> if you want to use different stubs for
each consumer instead of registering all stubs for every consumer.</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>stubrunner.consumerName</simpara></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><simpara>If you want to use a stub for each consumer and want to
override the consumer name just change this value.</simpara></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="stub-runner-stub-ids">
<title>Stub Runner Stubs IDs</title>
<simpara>You can provide the stubs to download via the <literal>stubrunner.ids</literal> system property. They
follow this pattern:</simpara>
<programlisting language="java" linenumbering="unnumbered">groupId:artifactId:version:classifier:port</programlisting>
<simpara>Note that <literal>version</literal>, <literal>classifier</literal> and <literal>port</literal> are optional.</simpara>
<itemizedlist>
<listitem>
<simpara>If you do not provide the <literal>port</literal>, a random one will be picked.</simpara>
</listitem>
<listitem>
<simpara>If you do not provide the <literal>classifier</literal>, the default is used. (Note that you can
pass an empty classifier this way: <literal>groupId:artifactId:version:</literal>).</simpara>
</listitem>
<listitem>
<simpara>If you do not provide the <literal>version</literal>, then the <literal>+</literal> will be passed and the latest one is
downloaded.</simpara>
</listitem>
</itemizedlist>
<simpara><literal>port</literal> means the port of the WireMock server.</simpara>
<important>
<simpara>Starting with version 1.0.4, you can provide a range of versions that you
would like the Stub Runner to take into consideration. You can read more about the
<link xl:href="https://wiki.eclipse.org/Aether/New_and_Noteworthy#Version_Ranges">Aether versioning
ranges here</link>.</simpara>
</important>
</section>
</section>
<section xml:id="stubrunner-docker">
<title>Stub Runner Docker</title>
<simpara>We&#8217;re publishing a <literal>spring-cloud/spring-cloud-contract-stub-runner</literal> Docker image
that will start the standalone version of Stub Runner.</simpara>
<simpara>If you want to learn more about the basics of Maven, artifact ids,
group ids, classifiers and Artifact Managers, just click here <xref linkend="docker-project"/>.</simpara>
<section xml:id="_how_to_use_it_2">
<title>How to use it</title>
<simpara>Just execute the docker image. You can pass any of the <xref linkend="common-properties-junit-spring"/>
as environment variables. The convention is that all the
letters should be upper case. The camel case notation should
and the dot (<literal>.</literal>) should be separated via underscore (<literal>_</literal>). E.g.
the <literal>stubrunner.repositoryRoot</literal> property should be represented
as a <literal>STUBRUNNER_REPOSITORY_ROOT</literal> environment variable.</simpara>
</section>
<section xml:id="_example_of_client_side_usage_in_a_non_jvm_project">
<title>Example of client side usage in a non JVM project</title>
<simpara>We&#8217;d like to use the stubs created in this <xref linkend="docker-server-side"/> step.
Let&#8217;s assume that we want to run the stubs on port <literal>9876</literal>. The NodeJS code
is available here:</simpara>
<programlisting language="bash" linenumbering="unnumbered">$ git clone https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs
$ cd bookstore</programlisting>
<simpara>Let&#8217;s run the Stub Runner Boot application with the stubs.</simpara>
<programlisting language="bash" linenumbering="unnumbered"># Provide the Spring Cloud Contract Docker version
$ SC_CONTRACT_DOCKER_VERSION="..."
# The IP at which the app is running and Docker container can reach it
$ APP_IP="192.168.0.100"
# Spring Cloud Contract Stub Runner properties
$ STUBRUNNER_PORT="8083"
# Stub coordinates 'groupId:artifactId:version:classifier:port'
$ STUBRUNNER_IDS="com.example:bookstore:0.0.1.RELEASE:stubs:9876"
$ STUBRUNNER_REPOSITORY_ROOT="http://${APP_IP}:8081/artifactory/libs-release-local"
# Run the docker with Stub Runner Boot
$ docker run --rm -e "STUBRUNNER_IDS=${STUBRUNNER_IDS}" -e "STUBRUNNER_REPOSITORY_ROOT=${STUBRUNNER_REPOSITORY_ROOT}" -e "STUBRUNNER_STUBS_MODE=REMOTE" -p "${STUBRUNNER_PORT}:${STUBRUNNER_PORT}" -p "9876:9876" springcloud/spring-cloud-contract-stub-runner:"${SC_CONTRACT_DOCKER_VERSION}"</programlisting>
<simpara>What&#8217;s happening is that</simpara>
<itemizedlist>
<listitem>
<simpara>a standalone Stub Runner application got started</simpara>
</listitem>
<listitem>
<simpara>it downloaded the stub with coordinates <literal>com.example:bookstore:0.0.1.RELEASE:stubs</literal> on port <literal>9876</literal></simpara>
</listitem>
<listitem>
<simpara>it got downloaded from Artifactory running at <literal><link xl:href="http://192.168.0.100:8081/artifactory/libs-release-local">http://192.168.0.100:8081/artifactory/libs-release-local</link></literal></simpara>
</listitem>
<listitem>
<simpara>after a while Stub Runner will be running on port <literal>8083</literal></simpara>
</listitem>
<listitem>
<simpara>and the stubs will be running at port <literal>9876</literal></simpara>
</listitem>
</itemizedlist>
<simpara>On the server side we built a stateful stub. Let&#8217;s use curl to assert
that the stubs are setup properly.</simpara>
<programlisting language="bash" linenumbering="unnumbered"># let's execute the first request (no response is returned)
$ curl -H "Content-Type:application/json" -X POST --data '{ "title" : "Title", "genre" : "Genre", "description" : "Description", "author" : "Author", "publisher" : "Publisher", "pages" : 100, "image_url" : "https://d213dhlpdb53mu.cloudfront.net/assets/pivotal-square-logo-41418bd391196c3022f3cd9f3959b3f6d7764c47873d858583384e759c7db435.svg", "buy_url" : "https://pivotal.io" }' http://localhost:9876/api/books
# Now time for the second request
$ curl -X GET http://localhost:9876/api/books
# You will receive contents of the JSON</programlisting>
<important>
<simpara>If you want use the stubs that you have built locally, on your host,
then you should pass the environment variable <literal>-e STUBRUNNER_STUBS_MODE=LOCAL</literal> and mount
the volume of your local m2 <literal>-v "${HOME}/.m2/:/root/.m2:ro"</literal></simpara>
</important>
</section>
</section>
</chapter>
<chapter xml:id="stub-runner-for-messaging">
<title>Stub Runner for Messaging</title>
<simpara>Stub Runner can run the published stubs in memory. It can integrate with the following
frameworks:</simpara>
<itemizedlist>
<listitem>
<simpara>Spring Integration</simpara>
</listitem>
<listitem>
<simpara>Spring Cloud Stream</simpara>
</listitem>
<listitem>
<simpara>Apache Camel</simpara>
</listitem>
<listitem>
<simpara>Spring AMQP</simpara>
</listitem>
</itemizedlist>
<simpara>It also provides entry points to integrate with any other solution on the market.</simpara>
<important>
<simpara>If you have multiple frameworks on the classpath Stub Runner will need to
define which one should be used. Let&#8217;s assume that you have both AMQP, Spring Cloud Stream and Spring Integration
on the classpath. Then you need to set <literal>stubrunner.stream.enabled=false</literal> and <literal>stubrunner.integration.enabled=false</literal>.
That way the only remaining framework is Spring AMQP.</simpara>
</important>
<section xml:id="_stub_triggering">
<title>Stub triggering</title>
<simpara>To trigger a message, use the <literal>StubTrigger</literal> interface:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">package org.springframework.cloud.contract.stubrunner;
import java.util.Collection;
import java.util.Map;
public interface StubTrigger {
/**
* Triggers an event by a given label for a given {@code groupid:artifactid} notation.
* You can use only {@code artifactId} too.
*
* Feature related to messaging.
* @return true - if managed to run a trigger
*/
boolean trigger(String ivyNotation, String labelName);
/**
* Triggers an event by a given label.
*
* Feature related to messaging.
* @return true - if managed to run a trigger
*/
boolean trigger(String labelName);
/**
* Triggers all possible events.
*
* Feature related to messaging.
* @return true - if managed to run a trigger
*/
boolean trigger();
/**
* Returns a mapping of ivy notation of a dependency to all the labels it has.
*
* Feature related to messaging.
*/
Map&lt;String, Collection&lt;String&gt;&gt; labels();
}</programlisting>
<simpara>For convenience, the <literal>StubFinder</literal> interface extends <literal>StubTrigger</literal>, so you only need one
or the other in your tests.</simpara>
<simpara><literal>StubTrigger</literal> gives you the following options to trigger a message:</simpara>
<itemizedlist>
<listitem>
<simpara><xref linkend="trigger-label"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="trigger-group-artifact-ids"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="trigger-artifact-ids"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="trigger-all-messages"/></simpara>
</listitem>
</itemizedlist>
<section xml:id="trigger-label">
<title>Trigger by Label</title>
<programlisting language="groovy" linenumbering="unnumbered">stubFinder.trigger('return_book_1')</programlisting>
</section>
<section xml:id="trigger-group-artifact-ids">
<title>Trigger by Group and Artifact Ids</title>
<programlisting language="groovy" linenumbering="unnumbered">stubFinder.trigger('org.springframework.cloud.contract.verifier.stubs:streamService', 'return_book_1')</programlisting>
</section>
<section xml:id="trigger-artifact-ids">
<title>Trigger by Artifact Ids</title>
<programlisting language="groovy" linenumbering="unnumbered">stubFinder.trigger('streamService', 'return_book_1')</programlisting>
</section>
<section xml:id="trigger-all-messages">
<title>Trigger All Messages</title>
<programlisting language="groovy" linenumbering="unnumbered">stubFinder.trigger()</programlisting>
</section>
</section>
<section xml:id="_stub_runner_camel">
<title>Stub Runner Camel</title>
<simpara>Spring Cloud Contract Verifier Stub Runner&#8217;s messaging module gives you an easy way to integrate with Apache Camel.
For the provided artifacts it will automatically download the stubs and register the required
routes.</simpara>
<section xml:id="_adding_it_to_the_project">
<title>Adding it to the project</title>
<simpara>It&#8217;s enough to have both Apache Camel and Spring Cloud Contract Stub Runner on classpath.
Remember to annotate your test class with <literal>@AutoConfigureStubRunner</literal>.</simpara>
</section>
<section xml:id="_disabling_the_functionality">
<title>Disabling the functionality</title>
<simpara>If you need to disable this functionality just pass <literal>stubrunner.camel.enabled=false</literal> property.</simpara>
</section>
<section xml:id="_examples">
<title>Examples</title>
<section xml:id="_stubs_structure">
<title>Stubs structure</title>
<simpara>Let us assume that we have the following Maven repository with a deployed stubs for the
<literal>camelService</literal> application.</simpara>
<programlisting language="bash" linenumbering="unnumbered">└── .m2
└── repository
└── io
└── codearte
└── accurest
└── stubs
└── camelService
├── 0.0.1-SNAPSHOT
│   ├── camelService-0.0.1-SNAPSHOT.pom
│   ├── camelService-0.0.1-SNAPSHOT-stubs.jar
│   └── maven-metadata-local.xml
└── maven-metadata-local.xml</programlisting>
<simpara>And the stubs contain the following structure:</simpara>
<programlisting language="bash" linenumbering="unnumbered">├── META-INF
│   └── MANIFEST.MF
└── repository
├── accurest
│   ├── bookDeleted.groovy
│   ├── bookReturned1.groovy
│   └── bookReturned2.groovy
└── mappings</programlisting>
<simpara>Let&#8217;s consider the following contracts (let' number it with <emphasis role="strong">1</emphasis>):</simpara>
<programlisting language="groovy" linenumbering="unnumbered">Contract.make {
label 'return_book_1'
input {
triggeredBy('bookReturnedTriggered()')
}
outputMessage {
sentTo('jms:output')
body('''{ "bookName" : "foo" }''')
headers {
header('BOOK-NAME', 'foo')
}
}
}</programlisting>
<simpara>and number <emphasis role="strong">2</emphasis></simpara>
<programlisting language="groovy" linenumbering="unnumbered">Contract.make {
label 'return_book_2'
input {
messageFrom('jms:input')
messageBody([
bookName: 'foo'
])
messageHeaders {
header('sample', 'header')
}
}
outputMessage {
sentTo('jms:output')
body([
bookName: 'foo'
])
headers {
header('BOOK-NAME', 'foo')
}
}
}</programlisting>
</section>
<section xml:id="_scenario_1_no_input_message_2">
<title>Scenario 1 (no input message)</title>
<simpara>So as to trigger a message via the <literal>return_book_1</literal> label we&#8217;ll use the <literal>StubTigger</literal> interface as follows</simpara>
<programlisting language="groovy" linenumbering="unnumbered">stubFinder.trigger('return_book_1')</programlisting>
<simpara>Next we&#8217;ll want to listen to the output of the message sent to <literal>jms:output</literal></simpara>
<programlisting language="groovy" linenumbering="unnumbered">Exchange receivedMessage = consumerTemplate.receive('jms:output', 5000)</programlisting>
<simpara>And the received message would pass the following assertions</simpara>
<programlisting language="groovy" linenumbering="unnumbered">receivedMessage != null
assertThatBodyContainsBookNameFoo(receivedMessage.in.body)
receivedMessage.in.headers.get('BOOK-NAME') == 'foo'</programlisting>
</section>
<section xml:id="_scenario_2_output_triggered_by_input_2">
<title>Scenario 2 (output triggered by input)</title>
<simpara>Since the route is set for you it&#8217;s enough to just send a message to the <literal>jms:output</literal> destination.</simpara>
<programlisting language="groovy" linenumbering="unnumbered">producerTemplate.sendBodyAndHeaders('jms:input', new BookReturned('foo'), [sample: 'header'])</programlisting>
<simpara>Next we&#8217;ll want to listen to the output of the message sent to <literal>jms:output</literal></simpara>
<programlisting language="groovy" linenumbering="unnumbered">Exchange receivedMessage = consumerTemplate.receive('jms:output', 5000)</programlisting>
<simpara>And the received message would pass the following assertions</simpara>
<programlisting language="groovy" linenumbering="unnumbered">receivedMessage != null
assertThatBodyContainsBookNameFoo(receivedMessage.in.body)
receivedMessage.in.headers.get('BOOK-NAME') == 'foo'</programlisting>
</section>
<section xml:id="_scenario_3_input_with_no_output">
<title>Scenario 3 (input with no output)</title>
<simpara>Since the route is set for you it&#8217;s enough to just send a message to the <literal>jms:output</literal> destination.</simpara>
<programlisting language="groovy" linenumbering="unnumbered">producerTemplate.sendBodyAndHeaders('jms:delete', new BookReturned('foo'), [sample: 'header'])</programlisting>
</section>
</section>
</section>
<section xml:id="_stub_runner_integration">
<title>Stub Runner Integration</title>
<simpara>Spring Cloud Contract Verifier Stub Runner&#8217;s messaging module gives you an easy way to
integrate with Spring Integration. For the provided artifacts, it automatically downloads
the stubs and registers the required routes.</simpara>
<section xml:id="_adding_the_runner_to_the_project">
<title>Adding the Runner to the Project</title>
<simpara>You can have both Spring Integration and Spring Cloud Contract Stub Runner on the
classpath. Remember to annotate your test class with <literal>@AutoConfigureStubRunner</literal>.</simpara>
</section>
<section xml:id="_disabling_the_functionality_2">
<title>Disabling the functionality</title>
<simpara>If you need to disable this functionality, set the
<literal>stubrunner.integration.enabled=false</literal> property.</simpara>
<simpara>Assume that you have the following Maven repository with deployed stubs for the
<literal>integrationService</literal> application:</simpara>
<programlisting language="bash" linenumbering="unnumbered">└── .m2
└── repository
└── io
└── codearte
└── accurest
└── stubs
└── integrationService
├── 0.0.1-SNAPSHOT
│   ├── integrationService-0.0.1-SNAPSHOT.pom
│   ├── integrationService-0.0.1-SNAPSHOT-stubs.jar
│   └── maven-metadata-local.xml
└── maven-metadata-local.xml</programlisting>
<simpara>Further assume the stubs contain the following structure:</simpara>
<programlisting language="bash" linenumbering="unnumbered">├── META-INF
│   └── MANIFEST.MF
└── repository
├── accurest
│   ├── bookDeleted.groovy
│   ├── bookReturned1.groovy
│   └── bookReturned2.groovy
└── mappings</programlisting>
<simpara>Consider the following contracts (numbered <emphasis role="strong">1</emphasis>):</simpara>
<programlisting language="groovy" linenumbering="unnumbered">Contract.make {
label 'return_book_1'
input {
triggeredBy('bookReturnedTriggered()')
}
outputMessage {
sentTo('output')
body('''{ "bookName" : "foo" }''')
headers {
header('BOOK-NAME', 'foo')
}
}
}</programlisting>
<simpara>Now consider <emphasis role="strong">2</emphasis>:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">Contract.make {
label 'return_book_2'
input {
messageFrom('input')
messageBody([
bookName: 'foo'
])
messageHeaders {
header('sample', 'header')
}
}
outputMessage {
sentTo('output')
body([
bookName: 'foo'
])
headers {
header('BOOK-NAME', 'foo')
}
}
}</programlisting>
<simpara>and the following Spring Integration Route:</simpara>
<programlisting language="xml" linenumbering="unnumbered">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans:beans xmlns="http://www.springframework.org/schema/integration"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:beans="http://www.springframework.org/schema/beans"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/integration
http://www.springframework.org/schema/integration/spring-integration.xsd"&gt;
&lt;!-- REQUIRED FOR TESTING --&gt;
&lt;bridge input-channel="output"
output-channel="outputTest"/&gt;
&lt;channel id="outputTest"&gt;
&lt;queue/&gt;
&lt;/channel&gt;
&lt;/beans:beans&gt;</programlisting>
<simpara>These examples lend themselves to three scenarios:</simpara>
<itemizedlist>
<listitem>
<simpara><xref linkend="integration-scenario-1"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="integration-scenario-2"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="integration-scenario-3"/></simpara>
</listitem>
</itemizedlist>
<section xml:id="integration-scenario-1">
<title>Scenario 1 (no input message)</title>
<simpara>To trigger a message via the <literal>return_book_1</literal> label, use the <literal>StubTigger</literal> interface, as
follows:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">stubFinder.trigger('return_book_1')</programlisting>
<simpara>To listen to the output of the message sent to <literal>output</literal>:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">Message&lt;?&gt; receivedMessage = messaging.receive('outputTest')</programlisting>
<simpara>The received message would pass the following assertions:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">receivedMessage != null
assertJsons(receivedMessage.payload)
receivedMessage.headers.get('BOOK-NAME') == 'foo'</programlisting>
</section>
<section xml:id="integration-scenario-2">
<title>Scenario 2 (output triggered by input)</title>
<simpara>Since the route is set for you, you can send a message to the <literal>output</literal>
destination:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">messaging.send(new BookReturned('foo'), [sample: 'header'], 'input')</programlisting>
<simpara>To listen to the output of the message sent to <literal>output</literal>:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">Message&lt;?&gt; receivedMessage = messaging.receive('outputTest')</programlisting>
<simpara>The received message passes the following assertions:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">receivedMessage != null
assertJsons(receivedMessage.payload)
receivedMessage.headers.get('BOOK-NAME') == 'foo'</programlisting>
</section>
<section xml:id="integration-scenario-3">
<title>Scenario 3 (input with no output)</title>
<simpara>Since the route is set for you, you can send a message to the <literal>input</literal> destination:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">messaging.send(new BookReturned('foo'), [sample: 'header'], 'delete')</programlisting>
</section>
</section>
</section>
<section xml:id="_stub_runner_stream">
<title>Stub Runner Stream</title>
<simpara>Spring Cloud Contract Verifier Stub Runner&#8217;s messaging module gives you an easy way to
integrate with Spring Stream. For the provided artifacts, it automatically downloads the
stubs and registers the required routes.</simpara>
<warning>
<simpara>If Stub Runner&#8217;s integration with Stream the <literal>messageFrom</literal> or <literal>sentTo</literal> Strings
are resolved first as a <literal>destination</literal> of a channel and no such <literal>destination</literal> exists, the
destination is resolved as a channel name.</simpara>
</warning>
<important>
<simpara>If you want to use Spring Cloud Stream remember, to add a dependency on
<literal>org.springframework.cloud:spring-cloud-stream-test-support</literal>.</simpara>
</important>
<formalpara role="primary">
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-stream-test-support&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;</programlisting>
</para>
</formalpara>
<formalpara role="secondary">
<title>Gradle</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">testCompile "org.springframework.cloud:spring-cloud-stream-test-support"</programlisting>
</para>
</formalpara>
<section xml:id="_adding_the_runner_to_the_project_2">
<title>Adding the Runner to the Project</title>
<simpara>You can have both Spring Cloud Stream and Spring Cloud Contract Stub Runner on the
classpath. Remember to annotate your test class with <literal>@AutoConfigureStubRunner</literal>.</simpara>
</section>
<section xml:id="_disabling_the_functionality_3">
<title>Disabling the functionality</title>
<simpara>If you need to disable this functionality, set the <literal>stubrunner.stream.enabled=false</literal>
property.</simpara>
<simpara>Assume that you have the following Maven repository with a deployed stubs for the
<literal>streamService</literal> application:</simpara>
<programlisting language="bash" linenumbering="unnumbered">└── .m2
└── repository
└── io
└── codearte
└── accurest
└── stubs
└── streamService
├── 0.0.1-SNAPSHOT
│   ├── streamService-0.0.1-SNAPSHOT.pom
│   ├── streamService-0.0.1-SNAPSHOT-stubs.jar
│   └── maven-metadata-local.xml
└── maven-metadata-local.xml</programlisting>
<simpara>Further assume the stubs contain the following structure:</simpara>
<programlisting language="bash" linenumbering="unnumbered">├── META-INF
│   └── MANIFEST.MF
└── repository
├── accurest
│   ├── bookDeleted.groovy
│   ├── bookReturned1.groovy
│   └── bookReturned2.groovy
└── mappings</programlisting>
<simpara>Consider the following contracts (numbered <emphasis role="strong">1</emphasis>):</simpara>
<programlisting language="groovy" linenumbering="unnumbered">Contract.make {
label 'return_book_1'
input { triggeredBy('bookReturnedTriggered()') }
outputMessage {
sentTo('returnBook')
body('''{ "bookName" : "foo" }''')
headers { header('BOOK-NAME', 'foo') }
}
}</programlisting>
<simpara>Now consider <emphasis role="strong">2</emphasis>:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">Contract.make {
label 'return_book_2'
input {
messageFrom('bookStorage')
messageBody([
bookName: 'foo'
])
messageHeaders { header('sample', 'header') }
}
outputMessage {
sentTo('returnBook')
body([
bookName: 'foo'
])
headers { header('BOOK-NAME', 'foo') }
}
}</programlisting>
<simpara>Now consider the following Spring configuration:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">stubrunner.repositoryRoot: classpath:m2repo/repository/
stubrunner.ids: org.springframework.cloud.contract.verifier.stubs:streamService:0.0.1-SNAPSHOT:stubs
stubrunner.stubs-mode: remote
spring:
cloud:
stream:
bindings:
output:
destination: returnBook
input:
destination: bookStorage
server:
port: 0
debug: true</programlisting>
<simpara>These examples lend themselves to three scenarios:</simpara>
<itemizedlist>
<listitem>
<simpara><xref linkend="stream-scenario-1"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="stream-scenario-2"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="stream-scenario-3"/></simpara>
</listitem>
</itemizedlist>
<section xml:id="stream-scenario-1">
<title>Scenario 1 (no input message)</title>
<simpara>To trigger a message via the <literal>return_book_1</literal> label, use the <literal>StubTrigger</literal> interface as
follows:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">stubFinder.trigger('return_book_1')</programlisting>
<simpara>To listen to the output of the message sent to a channel whose <literal>destination</literal> is
<literal>returnBook</literal>:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">Message&lt;?&gt; receivedMessage = messaging.receive('returnBook')</programlisting>
<simpara>The received message passes the following assertions:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">receivedMessage != null
assertJsons(receivedMessage.payload)
receivedMessage.headers.get('BOOK-NAME') == 'foo'</programlisting>
</section>
<section xml:id="stream-scenario-2">
<title>Scenario 2 (output triggered by input)</title>
<simpara>Since the route is set for you, you can send a message to the <literal>bookStorage</literal>
<literal>destination</literal>:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">messaging.send(new BookReturned('foo'), [sample: 'header'], 'bookStorage')</programlisting>
<simpara>To listen to the output of the message sent to <literal>returnBook</literal>:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">Message&lt;?&gt; receivedMessage = messaging.receive('returnBook')</programlisting>
<simpara>The received message passes the following assertions:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">receivedMessage != null
assertJsons(receivedMessage.payload)
receivedMessage.headers.get('BOOK-NAME') == 'foo'</programlisting>
</section>
<section xml:id="stream-scenario-3">
<title>Scenario 3 (input with no output)</title>
<simpara>Since the route is set for you, you can send a message to the <literal>output</literal>
destination:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">messaging.send(new BookReturned('foo'), [sample: 'header'], 'delete')</programlisting>
</section>
</section>
</section>
<section xml:id="_stub_runner_spring_amqp">
<title>Stub Runner Spring AMQP</title>
<simpara>Spring Cloud Contract Verifier Stub Runner&#8217;s messaging module provides an easy way to
integrate with Spring AMQP&#8217;s Rabbit Template. For the provided artifacts, it
automatically downloads the stubs and registers the required routes.</simpara>
<simpara>The integration tries to work standalone (that is, without interaction with a running
RabbitMQ message broker). It expects a <literal>RabbitTemplate</literal> on the application context and
uses it as a spring boot test named <literal>@SpyBean</literal>. As a result, it can use the mockito spy
functionality to verify and inspect messages sent by the application.</simpara>
<simpara>On the message consumer side, the stub runner considers all <literal>@RabbitListener</literal> annotated
endpoints and all <literal>SimpleMessageListenerContainer</literal> objects on the application context.</simpara>
<simpara>As messages are usually sent to exchanges in AMQP, the message contract contains the
exchange name as the destination. Message listeners on the other side are bound to
queues. Bindings connect an exchange to a queue. If message contracts are triggered, the
Spring AMQP stub runner integration looks for bindings on the application context that
match this exchange. Then it collects the queues from the Spring exchanges and tries to
find message listeners bound to these queues. The message is triggered for all matching
message listeners.</simpara>
<simpara>If you need to work with routing keys, it&#8217;s enough to pass them via the <literal>amqp_receivedRoutingKey</literal>
messaging header.</simpara>
<section xml:id="_adding_the_runner_to_the_project_3">
<title>Adding the Runner to the Project</title>
<simpara>You can have both Spring AMQP and Spring Cloud Contract Stub Runner on the classpath and
set the property <literal>stubrunner.amqp.enabled=true</literal>. Remember to annotate your test class
with <literal>@AutoConfigureStubRunner</literal>.</simpara>
<important>
<simpara>If you already have Stream and Integration on the classpath, you need
to disable them explicitly by setting the <literal>stubrunner.stream.enabled=false</literal> and
<literal>stubrunner.integration.enabled=false</literal> properties.</simpara>
</important>
<simpara>Assume that you have the following Maven repository with a deployed stubs for the
<literal>spring-cloud-contract-amqp-test</literal> application.</simpara>
<programlisting language="bash" linenumbering="unnumbered">└── .m2
└── repository
└── com
└── example
└── spring-cloud-contract-amqp-test
├── 0.4.0-SNAPSHOT
│   ├── spring-cloud-contract-amqp-test-0.4.0-SNAPSHOT.pom
│   ├── spring-cloud-contract-amqp-test-0.4.0-SNAPSHOT-stubs.jar
│   └── maven-metadata-local.xml
└── maven-metadata-local.xml</programlisting>
<simpara>Further assume that the stubs contain the following structure:</simpara>
<programlisting language="bash" linenumbering="unnumbered">├── META-INF
│   └── MANIFEST.MF
└── contracts
└── shouldProduceValidPersonData.groovy</programlisting>
<simpara>Consider the following contract:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">Contract.make {
// Human readable description
description 'Should produce valid person data'
// Label by means of which the output message can be triggered
label 'contract-test.person.created.event'
// input to the contract
input {
// the contract will be triggered by a method
triggeredBy('createPerson()')
}
// output message of the contract
outputMessage {
// destination to which the output message will be sent
sentTo 'contract-test.exchange'
headers {
header('contentType': 'application/json')
header('__TypeId__': 'org.springframework.cloud.contract.stubrunner.messaging.amqp.Person')
}
// the body of the output message
body ([
id: $(consumer(9), producer(regex("[0-9]+"))),
name: "me"
])
}
}</programlisting>
<simpara>Now consider the following Spring configuration:</simpara>
<programlisting language="yaml" linenumbering="unnumbered">stubrunner:
repositoryRoot: classpath:m2repo/repository/
ids: org.springframework.cloud.contract.verifier.stubs.amqp:spring-cloud-contract-amqp-test:0.4.0-SNAPSHOT:stubs
stubs-mode: remote
amqp:
enabled: true
server:
port: 0</programlisting>
<section xml:id="_triggering_the_message">
<title>Triggering the message</title>
<simpara>To trigger a message using the contract above, use the <literal>StubTrigger</literal> interface as
follows:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">stubTrigger.trigger("contract-test.person.created.event")</programlisting>
<simpara>The message has a destination of <literal>contract-test.exchange</literal>, so the Spring AMQP stub runner
integration looks for bindings related to this exchange.</simpara>
<programlisting language="java" linenumbering="unnumbered">@Bean
public Binding binding() {
return BindingBuilder.bind(new Queue("test.queue"))
.to(new DirectExchange("contract-test.exchange")).with("#");
}</programlisting>
<simpara>The binding definition binds the queue <literal>test.queue</literal>. As a result, the following listener
definition is matched and invoked with the contract message.</simpara>
<programlisting language="java" linenumbering="unnumbered">@Bean
public SimpleMessageListenerContainer simpleMessageListenerContainer(
ConnectionFactory connectionFactory,
MessageListenerAdapter listenerAdapter) {
SimpleMessageListenerContainer container = new SimpleMessageListenerContainer();
container.setConnectionFactory(connectionFactory);
container.setQueueNames("test.queue");
container.setMessageListener(listenerAdapter);
return container;
}</programlisting>
<simpara>Also, the following annotated listener matches and is invoked:</simpara>
<programlisting language="java" linenumbering="unnumbered">@RabbitListener(bindings = @QueueBinding(value = @Queue(value = "test.queue"), exchange = @Exchange(value = "contract-test.exchange", ignoreDeclarationExceptions = "true")))
public void handlePerson(Person person) {
this.person = person;
}</programlisting>
<note>
<simpara>The message is directly handed over to the <literal>onMessage</literal> method of the
<literal>MessageListener</literal> associated with the matching <literal>SimpleMessageListenerContainer</literal>.</simpara>
</note>
</section>
<section xml:id="_spring_amqp_test_configuration">
<title>Spring AMQP Test Configuration</title>
<simpara>In order to avoid Spring AMQP trying to connect to a running broker during our tests
configure a mock <literal>ConnectionFactory</literal>.</simpara>
<simpara>To disable the mocked ConnectionFactory, set the following property:
<literal>stubrunner.amqp.mockConnection=false</literal></simpara>
<programlisting language="yaml" linenumbering="unnumbered">stubrunner:
amqp:
mockConnection: false</programlisting>
</section>
</section>
</section>
</chapter>
<chapter xml:id="contract-dsl">
<title>Contract DSL</title>
<simpara>Spring Cloud Contract supports out of the box 2 types of DSL. One written in
<literal>Groovy</literal> and one written in <literal>YAML</literal>.</simpara>
<simpara>If you decide to write the contract in Groovy, do not be alarmed if you have not used Groovy
before. Knowledge of the language is not really needed, as the Contract DSL uses only a
tiny subset of it (only literals, method calls and closures). Also, the DSL is statically
typed, to make it programmer-readable without any knowledge of the DSL itself.</simpara>
<important>
<simpara>Remember that, inside the Groovy contract file, you have to provide the fully
qualified name to the <literal>Contract</literal> class and <literal>make</literal> static imports, such as
<literal>org.springframework.cloud.spec.Contract.make { &#8230;&#8203; }</literal>. You can also provide an import to
the <literal>Contract</literal> class: <literal>import org.springframework.cloud.spec.Contract</literal> and then call
<literal>Contract.make { &#8230;&#8203; }</literal>.</simpara>
</important>
<tip>
<simpara>Spring Cloud Contract supports defining multiple contracts in a single file.</simpara>
</tip>
<simpara>The following is a complete example of a Groovy contract definition:</simpara>
<programlisting language="groovy" linenumbering="unnumbered"></programlisting>
<simpara>The following is a complete example of a YAML contract definition:</simpara>
<programlisting language="yml" linenumbering="unnumbered">description: Some description
name: some name
priority: 8
ignored: true
request:
url: /foo
queryParameters:
a: b
b: c
method: PUT
headers:
foo: bar
fooReq: baz
body:
foo: bar
matchers:
body:
- path: $.foo
type: by_regex
value: bar
headers:
- key: foo
regex: bar
response:
status: 200
headers:
foo2: bar
foo3: foo33
fooRes: baz
body:
foo2: bar
foo3: baz
nullValue: null
matchers:
body:
- path: $.foo2
type: by_regex
value: bar
- path: $.foo3
type: by_command
value: executeMe($it)
- path: $.nullValue
type: by_null
value: null
headers:
- key: foo2
regex: bar
- key: foo3
command: andMeToo($it)</programlisting>
<tip>
<simpara>You can compile contracts to stubs mapping using standalone maven command:
<literal>mvn org.springframework.cloud:spring-cloud-contract-maven-plugin:convert</literal></simpara>
</tip>
<section xml:id="_limitations">
<title>Limitations</title>
<warning>
<simpara>Spring Cloud Contract Verifier does not properly support XML. Please use JSON or
help us implement this feature.</simpara>
</warning>
<warning>
<simpara>The support for verifying the size of JSON arrays is experimental. If you want
to turn it on, please set the value of the following system property to <literal>true</literal>:
<literal>spring.cloud.contract.verifier.assert.size</literal>. By default, this feature is set to <literal>false</literal>.
You can also provide the <literal>assertJsonSize</literal> property in the plugin configuration.</simpara>
</warning>
<warning>
<simpara>Because JSON structure can have any form, it can be impossible to parse it
properly when using the Groovy DSL and the <literal>value(consumer(&#8230;&#8203;), producer(&#8230;&#8203;))</literal> notation in <literal>GString</literal>. That
is why you should use the Groovy Map notation.</simpara>
</warning>
</section>
<section xml:id="_common_top_level_elements">
<title>Common Top-Level elements</title>
<simpara>The following sections describe the most common top-level elements:</simpara>
<itemizedlist>
<listitem>
<simpara><xref linkend="contract-dsl-description"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="contract-dsl-name"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="contract-dsl-ignoring-contracts"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="contract-dsl-passing-values-from-files"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="contract-dsl-http-top-level-elements"/></simpara>
</listitem>
</itemizedlist>
<section xml:id="contract-dsl-description">
<title>Description</title>
<simpara>You can add a <literal>description</literal> to your contract. The description is arbitrary text. The
following code shows an example:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered"> org.springframework.cloud.contract.spec.Contract.make {
description('''
given:
An input
when:
Sth happens
then:
Output
''')
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">description: Some description
name: some name
priority: 8
ignored: true
request:
url: /foo
queryParameters:
a: b
b: c
method: PUT
headers:
foo: bar
fooReq: baz
body:
foo: bar
matchers:
body:
- path: $.foo
type: by_regex
value: bar
headers:
- key: foo
regex: bar
response:
status: 200
headers:
foo2: bar
foo3: foo33
fooRes: baz
body:
foo2: bar
foo3: baz
nullValue: null
matchers:
body:
- path: $.foo2
type: by_regex
value: bar
- path: $.foo3
type: by_command
value: executeMe($it)
- path: $.nullValue
type: by_null
value: null
headers:
- key: foo2
regex: bar
- key: foo3
command: andMeToo($it)</programlisting>
</para>
</formalpara>
</section>
<section xml:id="contract-dsl-name">
<title>Name</title>
<simpara>You can provide a name for your contract. Assume that you provided the following name:
<literal>should register a user</literal>. If you do so, the name of the autogenerated test is
<literal>validate_should_register_a_user</literal>. Also, the name of the stub in a WireMock stub is
<literal>should_register_a_user.json</literal>.</simpara>
<important>
<simpara>You must ensure that the name does not contain any characters that make the
generated test not compile. Also, remember that, if you provide the same name for
multiple contracts, your autogenerated tests fail to compile and your generated stubs
override each other.</simpara>
</important>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
name("some_special_name")
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">name: some name</programlisting>
</para>
</formalpara>
</section>
<section xml:id="contract-dsl-ignoring-contracts">
<title>Ignoring Contracts</title>
<simpara>If you want to ignore a contract, you can either set a value of ignored contracts in the
plugin configuration or set the <literal>ignored</literal> property on the contract itself:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
ignored()
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">ignored: true</programlisting>
</para>
</formalpara>
</section>
<section xml:id="contract-dsl-passing-values-from-files">
<title>Passing Values from Files</title>
<simpara>Starting with version <literal>1.2.0</literal>, you can pass values from files. Assume that you have the
following resources in our project.</simpara>
<programlisting language="bash" linenumbering="unnumbered">└── src
    └── test
       └── resources
          └── contracts
    ├── readFromFile.groovy
    ├── request.json
    └── response.json</programlisting>
<simpara>Further assume that your contract is as follows:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">import org.springframework.cloud.contract.spec.Contract
Contract.make {
request {
method('PUT')
headers {
contentType(applicationJson())
}
body(file("request.json"))
url("/1")
}
response {
status OK()
body(file("response.json"))
headers {
contentType(applicationJson())
}
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">request:
method: GET
url: /foo
bodyFromFile: request.json
response:
status: 200
bodyFromFile: response.json</programlisting>
</para>
</formalpara>
<simpara>Further assume that the JSON files is as follows:</simpara>
<simpara><emphasis role="strong">request.json</emphasis></simpara>
<programlisting language="json" linenumbering="unnumbered">{
"status": "REQUEST"
}</programlisting>
<simpara><emphasis role="strong">response.json</emphasis></simpara>
<programlisting language="json" linenumbering="unnumbered">{
"status": "RESPONSE"
}</programlisting>
<simpara>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.</simpara>
<simpara>If you need to pass the contents of a file in a binary form
it&#8217;s enough for you to use the <literal>fileAsBytes</literal> method in Groovy DSL or <literal>bodyFromFileAsBytes</literal> field in YAML.</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">import org.springframework.cloud.contract.spec.Contract
Contract.make {
request {
url("/1")
method(PUT())
headers {
contentType(applicationOctetStream())
}
body(fileAsBytes("request.pdf"))
}
response {
status 200
body(fileAsBytes("response.pdf"))
headers {
contentType(applicationOctetStream())
}
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">request:
url: /1
method: PUT
headers:
Content-Type: application/octet-stream
bodyFromFileAsBytes: request.pdf
response:
status: 200
bodyFromFileAsBytes: response.pdf
headers:
Content-Type: application/octet-stream</programlisting>
</para>
</formalpara>
<important>
<simpara>You should use this approach whenever you want to work with binary payloads both for HTTP and messaging.</simpara>
</important>
</section>
<section xml:id="contract-dsl-http-top-level-elements">
<title>HTTP Top-Level Elements</title>
<simpara>The following methods can be called in the top-level closure of a contract definition.
<literal>request</literal> and <literal>response</literal> are mandatory. <literal>priority</literal> is optional.</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
// Definition of HTTP request part of the contract
// (this can be a valid request or invalid depending
// on type of contract being specified).
request {
method GET()
url "/foo"
//...
}
// Definition of HTTP response part of the contract
// (a service implementing this contract should respond
// with following response after receiving request
// specified in "request" part above).
response {
status 200
//...
}
// Contract priority, which can be used for overriding
// contracts (1 is highest). Priority is optional.
priority 1
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">priority: 8
request:
...
response:
...</programlisting>
</para>
</formalpara>
<important>
<simpara>If you want to make your contract have a <emphasis role="strong">higher</emphasis> value of priority
you need to pass a <emphasis role="strong">lower</emphasis> number to the <literal>priority</literal> tag / method. E.g. <literal>priority</literal> with
value <literal>5</literal> has <emphasis role="strong">higher</emphasis> priority than <literal>priority</literal> with value <literal>10</literal>.</simpara>
</important>
</section>
</section>
<section xml:id="_request">
<title>Request</title>
<simpara>The HTTP protocol requires only <emphasis role="strong">method and url</emphasis> to be specified in a request. The
same information is mandatory in request definition of the Contract.</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
request {
// HTTP request method (GET/POST/PUT/DELETE).
method 'GET'
// Path component of request URL is specified as follows.
urlPath('/users')
}
response {
//...
status 200
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">method: PUT
url: /foo</programlisting>
</para>
</formalpara>
<simpara>It is possible to specify an absolute rather than relative <literal>url</literal>, but using <literal>urlPath</literal> is
the recommended way, as doing so makes the tests <emphasis role="strong">host-independent</emphasis>.</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
request {
method 'GET'
// Specifying `url` and `urlPath` in one contract is illegal.
url('http://localhost:8888/users')
}
response {
//...
status 200
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">request:
method: PUT
urlPath: /foo</programlisting>
</para>
</formalpara>
<simpara><literal>request</literal> may contain <emphasis role="strong">query parameters</emphasis>.</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
request {
//...
method GET()
urlPath('/users') {
// Each parameter is specified in form
// `'paramName' : paramValue` where parameter value
// may be a simple literal or one of matcher functions,
// all of which are used in this example.
queryParameters {
// If a simple literal is used as value
// default matcher function is used (equalTo)
parameter 'limit': 100
// `equalTo` function simply compares passed value
// using identity operator (==).
parameter 'filter': equalTo("email")
// `containing` function matches strings
// that contains passed substring.
parameter 'gender': value(consumer(containing("[mf]")), producer('mf'))
// `matching` function tests parameter
// against passed regular expression.
parameter 'offset': value(consumer(matching("[0-9]+")), producer(123))
// `notMatching` functions tests if parameter
// does not match passed regular expression.
parameter 'loginStartsWith': value(consumer(notMatching(".{0,2}")), producer(3))
}
}
//...
}
response {
//...
status 200
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">request:
...
queryParameters:
a: b
b: c
headers:
foo: bar
fooReq: baz
cookies:
foo: bar
fooReq: baz
body:
foo: bar
matchers:
body:
- path: $.foo
type: by_regex
value: bar
headers:
- key: foo
regex: bar
response:
status: 200
fixedDelayMilliseconds: 1000
headers:
foo2: bar
foo3: foo33
fooRes: baz
body:
foo2: bar
foo3: baz
nullValue: null
matchers:
body:
- path: $.foo2
type: by_regex
value: bar
- path: $.foo3
type: by_command
value: executeMe($it)
- path: $.nullValue
type: by_null
value: null
headers:
- key: foo2
regex: bar
- key: foo3
command: andMeToo($it)
cookies:
- key: foo2
regex: bar
- key: foo3
predefined:</programlisting>
</para>
</formalpara>
<simpara><literal>request</literal> may contain additional <emphasis role="strong">request headers</emphasis>, as shown in the following example:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
request {
//...
method GET()
url "/foo"
// Each header is added in form `'Header-Name' : 'Header-Value'`.
// there are also some helper methods
headers {
header 'key': 'value'
contentType(applicationJson())
}
//...
}
response {
//...
status 200
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">request:
...
headers:
foo: bar
fooReq: baz</programlisting>
</para>
</formalpara>
<simpara><literal>request</literal> may contain additional <emphasis role="strong">request cookies</emphasis>, as shown in the following example:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
request {
//...
method GET()
url "/foo"
// Each Cookies is added in form `'Cookie-Key' : 'Cookie-Value'`.
// there are also some helper methods
cookies {
cookie 'key': 'value'
cookie('another_key', 'another_value')
}
//...
}
response {
//...
status 200
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">request:
...
cookies:
foo: bar
fooReq: baz</programlisting>
</para>
</formalpara>
<simpara><literal>request</literal> may contain a <emphasis role="strong">request body</emphasis>:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
request {
//...
method GET()
url "/foo"
// Currently only JSON format of request body is supported.
// Format will be determined from a header or body's content.
body '''{ "login" : "john", "name": "John The Contract" }'''
}
response {
//...
status 200
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">request:
...
body:
foo: bar</programlisting>
</para>
</formalpara>
<simpara><literal>request</literal> may contain <emphasis role="strong">multipart</emphasis> elements. To include multipart elements, use the
<literal>multipart</literal> method/section, as shown in the following examples</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered"></programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">request:
method: PUT
url: /multipart
headers:
Content-Type: multipart/form-data;boundary=AaB03x
multipart:
params:
# key (parameter name), value (parameter value) pair
formParameter: '"formParameterValue"'
someBooleanParameter: true
named:
- paramName: file
fileName: filename.csv
fileContent: file content
matchers:
multipart:
params:
- key: formParameter
regex: ".+"
- key: someBooleanParameter
predefined: any_boolean
named:
- paramName: file
fileName:
predefined: non_empty
fileContent:
predefined: non_empty
response:
status: 200</programlisting>
</para>
</formalpara>
<simpara>In the preceding example, we define parameters in either of two ways:</simpara>
<itemizedlist>
<title>Groovy DSL</title>
<listitem>
<simpara>Directly, by using the map notation, where the value can be a dynamic property (such as
<literal>formParameter: $(consumer(&#8230;&#8203;), producer(&#8230;&#8203;))</literal>).</simpara>
</listitem>
<listitem>
<simpara>By using the <literal>named(&#8230;&#8203;)</literal> method that lets you set a named parameter. A named parameter
can set a <literal>name</literal> and <literal>content</literal>. You can call it either via a method with two arguments,
such as <literal>named("fileName", "fileContent")</literal>, or via a map notation, such as
<literal>named(name: "fileName", content: "fileContent")</literal>.</simpara>
</listitem>
</itemizedlist>
<itemizedlist>
<title>YAML</title>
<listitem>
<simpara>The multipart parameters are set via <literal>multipart.params</literal> section</simpara>
</listitem>
<listitem>
<simpara>The named parameters (the <literal>fileName</literal> and <literal>fileContent</literal> for a given parameter name)
can be set via the <literal>multipart.named</literal> section. That section contains
the <literal>paramName</literal> (name of the parameter), <literal>fileName</literal> (name of the file),
<literal>fileContent</literal> (content of the file) fields</simpara>
</listitem>
<listitem>
<simpara>The dynamic bits can be set via the <literal>matchers.multipart</literal> section</simpara>
<itemizedlist>
<listitem>
<simpara>for parameters use the <literal>params</literal> section that can accept
<literal>regex</literal> or a <literal>predefined</literal> regular expression</simpara>
</listitem>
<listitem>
<simpara>for named params use the <literal>named</literal> section where first you
define the parameter name via <literal>paramName</literal> and then you can pass the
parametrization of either <literal>fileName</literal> or <literal>fileContent</literal> via
<literal>regex</literal> or a <literal>predefined</literal> regular expression</simpara>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<simpara>From this contract, the generated test is as follows:</simpara>
<programlisting language="java" linenumbering="unnumbered">// given:
MockMvcRequestSpecification request = given()
.header("Content-Type", "multipart/form-data;boundary=AaB03x")
.param("formParameter", "\"formParameterValue\"")
.param("someBooleanParameter", "true")
.multiPart("file", "filename.csv", "file content".getBytes());
// when:
ResponseOptions response = given().spec(request)
.put("/multipart");
// then:
assertThat(response.statusCode()).isEqualTo(200);</programlisting>
<simpara>The WireMock stub is as follows:</simpara>
<programlisting language="json" linenumbering="unnumbered"> '''
{
"request" : {
"url" : "/multipart",
"method" : "PUT",
"headers" : {
"Content-Type" : {
"matches" : "multipart/form-data;boundary=AaB03x.*"
}
},
"bodyPatterns" : [ {
"matches" : ".*--(.*)\\r\\nContent-Disposition: form-data; name=\\"formParameter\\"\\r\\n(Content-Type: .*\\r\\n)?(Content-Transfer-Encoding: .*\\r\\n)?(Content-Length: \\\\d+\\r\\n)?\\r\\n\\".+\\"\\r\\n--\\\\1.*"
}, {
"matches" : ".*--(.*)\\r\\nContent-Disposition: form-data; name=\\"someBooleanParameter\\"\\r\\n(Content-Type: .*\\r\\n)?(Content-Transfer-Encoding: .*\\r\\n)?(Content-Length: \\\\d+\\r\\n)?\\r\\n(true|false)\\r\\n--\\\\1.*"
}, {
"matches" : ".*--(.*)\\r\\nContent-Disposition: form-data; name=\\"file\\"; filename=\\"[\\\\S\\\\s]+\\"\\r\\n(Content-Type: .*\\r\\n)?(Content-Transfer-Encoding: .*\\r\\n)?(Content-Length: \\\\d+\\r\\n)?\\r\\n[\\\\S\\\\s]+\\r\\n--\\\\1.*"
} ]
},
"response" : {
"status" : 200,
"transformers" : [ "response-template", "foo-transformer" ]
}
}
'''</programlisting>
</section>
<section xml:id="_response">
<title>Response</title>
<simpara>The response must contain an <emphasis role="strong">HTTP status code</emphasis> and may contain other information. The
following code shows an example:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
request {
//...
method GET()
url "/foo"
}
response {
// Status code sent by the server
// in response to request specified above.
status OK()
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">response:
...
status: 200</programlisting>
</para>
</formalpara>
<simpara>Besides status, the response may contain <emphasis role="strong">headers</emphasis>, <emphasis role="strong">cookies</emphasis> and a <emphasis role="strong">body</emphasis>, both of which are
specified the same way as in the request (see the previous paragraph).</simpara>
<tip>
<simpara>Via the Groovy DSL you can reference the <literal>org.springframework.cloud.contract.spec.internal.HttpStatus</literal>
methods to provide a meaningful status instead of a digit. E.g. you can call
<literal>OK()</literal> for a status <literal>200</literal> or <literal>BAD_REQUEST()</literal> for <literal>400</literal>.</simpara>
</tip>
</section>
<section xml:id="_dynamic_properties">
<title>Dynamic properties</title>
<simpara>The contract can contain some dynamic properties: timestamps, IDs, and so on. You do not
want to force the consumers to stub their clocks to always return the same value of time
so that it gets matched by the stub.</simpara>
<simpara>For Groovy DSL you can provide the dynamic parts in your contracts
in two ways: pass them directly in the body or set them in a separate section called
<literal>bodyMatchers</literal>.</simpara>
<note>
<simpara>Before 2.0.0 these were set using <literal>testMatchers</literal> and <literal>stubMatchers</literal>,
check out the <link xl:href="https://github.com/spring-cloud/spring-cloud-contract/wiki/Spring-Cloud-Contract-2.0-Migration-Guide">migration guide</link> for more information.</simpara>
</note>
<simpara>For YAML you can only use the <literal>matchers</literal> section.</simpara>
<section xml:id="_dynamic_properties_inside_the_body">
<title>Dynamic properties inside the body</title>
<important>
<simpara>This section is valid only for Groovy DSL. Check out the
<xref linkend="contract-matchers"/> section for YAML examples of a similar feature.</simpara>
</important>
<simpara>You can set the properties inside the body either with the <literal>value</literal> method or, if you use
the Groovy map notation, with <literal>$()</literal>. The following example shows how to set dynamic
properties with the value method:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">value(consumer(...), producer(...))
value(c(...), p(...))
value(stub(...), test(...))
value(client(...), server(...))</programlisting>
<simpara>The following example shows how to set dynamic properties with <literal>$()</literal>:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">$(consumer(...), producer(...))
$(c(...), p(...))
$(stub(...), test(...))
$(client(...), server(...))</programlisting>
<simpara>Both approaches work equally well. <literal>stub</literal> and <literal>client</literal> methods are aliases over the <literal>consumer</literal>
method. Subsequent sections take a closer look at what you can do with those values.</simpara>
</section>
<section xml:id="_regular_expressions">
<title>Regular expressions</title>
<important>
<simpara>This section is valid only for Groovy DSL. Check out the
<xref linkend="contract-matchers"/> section for YAML examples of a similar feature.</simpara>
</important>
<simpara>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.</simpara>
<simpara>The following example shows how to use regular expressions to write a request:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
request {
method('GET')
url $(consumer(~/\/[0-9]{2}/), producer('/12'))
}
response {
status OK()
body(
id: $(anyNumber()),
surname: $(
consumer('Kowalsky'),
producer(regex('[a-zA-Z]+'))
),
name: 'Jan',
created: $(consumer('2014-02-02 12:23:43'), producer(execute('currentDate(it)'))),
correlationId: value(consumer('5d1f9fef-e0dc-4f3d-a7e4-72d2220dd827'),
producer(regex('[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}'))
)
)
headers {
header 'Content-Type': 'text/plain'
}
}
}</programlisting>
<simpara>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:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
request {
method 'PUT'
url value(consumer(regex('/foo/[0-9]{5}')))
body([
requestElement: $(consumer(regex('[0-9]{5}')))
])
headers {
header('header', $(consumer(regex('application\\/vnd\\.fraud\\.v1\\+json;.*'))))
}
}
response {
status OK()
body([
responseElement: $(producer(regex('[0-9]{7}')))
])
headers {
contentType("application/vnd.fraud.v1+json")
}
}
}</programlisting>
<simpara>In the preceding example, the opposite side of the communication has the respective data
generated for request and response.</simpara>
<simpara>Spring Cloud Contract comes with a series of predefined regular expressions that you can
use in your contracts, as shown in the following example:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">protected static final Pattern TRUE_OR_FALSE = Pattern.compile(/(true|false)/)
protected static final Pattern ALPHA_NUMERIC = Pattern.compile('[a-zA-Z0-9]+')
protected static final Pattern ONLY_ALPHA_UNICODE = Pattern.compile(/[\p{L}]*/)
protected static final Pattern NUMBER = Pattern.compile('-?(\\d*\\.\\d+|\\d+)')
protected static final Pattern INTEGER = Pattern.compile('-?(\\d+)')
protected static final Pattern POSITIVE_INT = Pattern.compile('([1-9]\\d*)')
protected static final Pattern DOUBLE = Pattern.compile('-?(\\d*\\.\\d+)')
protected static final Pattern HEX = Pattern.compile('[a-fA-F0-9]+')
protected static final Pattern IP_ADDRESS = Pattern.compile('([01]?\\d\\d?|2[0-4]\\d|25[0-5])\\.([01]?\\d\\d?|2[0-4]\\d|25[0-5])\\.([01]?\\d\\d?|2[0-4]\\d|25[0-5])\\.([01]?\\d\\d?|2[0-4]\\d|25[0-5])')
protected static final Pattern HOSTNAME_PATTERN = Pattern.compile('((http[s]?|ftp):/)/?([^:/\\s]+)(:[0-9]{1,5})?')
protected static final Pattern EMAIL = Pattern.compile('[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,6}')
protected static final Pattern URL = UrlHelper.URL
protected static final Pattern HTTPS_URL = UrlHelper.HTTPS_URL
protected static final Pattern UUID = Pattern.compile('[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}')
protected static final Pattern ANY_DATE = Pattern.compile('(\\d\\d\\d\\d)-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])')
protected static final Pattern ANY_DATE_TIME = Pattern.compile('([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])')
protected static final Pattern ANY_TIME = Pattern.compile('(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])')
protected static final Pattern NON_EMPTY = Pattern.compile(/[\S\s]+/)
protected static final Pattern NON_BLANK = Pattern.compile(/^\s*\S[\S\s]*/)
protected static final Pattern ISO8601_WITH_OFFSET = Pattern.compile(/([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\.\d{3})?(Z|[+-][01]\d:[0-5]\d)/)
protected static Pattern anyOf(String... values){
return Pattern.compile(values.collect({"^$it\$"}).join("|"))
}
Pattern onlyAlphaUnicode() {
return ONLY_ALPHA_UNICODE
}
Pattern alphaNumeric() {
return ALPHA_NUMERIC
}
Pattern number() {
return NUMBER
}
Pattern positiveInt() {
return POSITIVE_INT
}
Pattern anyBoolean() {
return TRUE_OR_FALSE
}
Pattern anInteger() {
return INTEGER
}
Pattern aDouble() {
return DOUBLE
}
Pattern ipAddress() {
return IP_ADDRESS
}
Pattern hostname() {
return HOSTNAME_PATTERN
}
Pattern email() {
return EMAIL
}
Pattern url() {
return URL
}
Pattern httpsUrl() {
return HTTPS_URL
}
Pattern uuid(){
return UUID
}
Pattern isoDate() {
return ANY_DATE
}
Pattern isoDateTime() {
return ANY_DATE_TIME
}
Pattern isoTime() {
return ANY_TIME
}
Pattern iso8601WithOffset() {
return ISO8601_WITH_OFFSET
}
Pattern nonEmpty() {
return NON_EMPTY
}
Pattern nonBlank() {
return NON_BLANK
}</programlisting>
<simpara>In your contract, you can use it as shown in the following example:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">Contract dslWithOptionalsInString = Contract.make {
priority 1
request {
method POST()
url '/users/password'
headers {
contentType(applicationJson())
}
body(
email: $(consumer(optional(regex(email()))), producer('abc@abc.com')),
callback_url: $(consumer(regex(hostname())), producer('http://partners.com'))
)
}
response {
status 404
headers {
contentType(applicationJson())
}
body(
code: value(consumer("123123"), producer(optional("123123"))),
message: "User not found by email = [${value(producer(regex(email())), consumer('not.existing@user.com'))}]"
)
}
}</programlisting>
<simpara>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 <literal>any</literal> prefix:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">T anyAlphaUnicode()
T anyAlphaNumeric()
T anyNumber()
T anyInteger()
T anyPositiveInt()
T anyDouble()
T anyHex()
T aBoolean()
T anyIpAddress()
T anyHostname()
T anyEmail()
T anyUrl()
T anyHttpsUrl()
T anyUuid()
T anyDate()
T anyDateTime()
T anyTime()
T anyIso8601WithOffset()
T anyNonBlankString()
T anyNonEmptyString()
T anyOf(String... values)</programlisting>
<simpara>and this is an example of how you can reference those methods:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">Contract contractDsl = Contract.make {
label 'trigger_event'
input {
triggeredBy('toString()')
}
outputMessage {
sentTo 'topic.rateablequote'
body([
alpha: $(anyAlphaUnicode()),
number: $(anyNumber()),
anInteger: $(anyInteger()),
positiveInt: $(anyPositiveInt()),
aDouble: $(anyDouble()),
aBoolean: $(aBoolean()),
ip: $(anyIpAddress()),
hostname: $(anyHostname()),
email: $(anyEmail()),
url: $(anyUrl()),
httpsUrl: $(anyHttpsUrl()),
uuid: $(anyUuid()),
date: $(anyDate()),
dateTime: $(anyDateTime()),
time: $(anyTime()),
iso8601WithOffset: $(anyIso8601WithOffset()),
nonBlankString: $(anyNonBlankString()),
nonEmptyString: $(anyNonEmptyString()),
anyOf: $(anyOf('foo', 'bar'))
])
}
}</programlisting>
</section>
<section xml:id="_passing_optional_parameters">
<title>Passing Optional Parameters</title>
<important>
<simpara>This section is valid only for Groovy DSL. Check out the
<xref linkend="contract-matchers"/> section for YAML examples of a similar feature.</simpara>
</important>
<simpara>It is possible to provide optional parameters in your contract. However, you can provide
optional parameters only for the following:</simpara>
<itemizedlist>
<listitem>
<simpara><emphasis>STUB</emphasis> side of the Request</simpara>
</listitem>
<listitem>
<simpara><emphasis>TEST</emphasis> side of the Response</simpara>
</listitem>
</itemizedlist>
<simpara>The following example shows how to provide optional parameters:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
priority 1
request {
method 'POST'
url '/users/password'
headers {
contentType(applicationJson())
}
body(
email: $(consumer(optional(regex(email()))), producer('abc@abc.com')),
callback_url: $(consumer(regex(hostname())), producer('http://partners.com'))
)
}
response {
status 404
headers {
header 'Content-Type': 'application/json'
}
body(
code: value(consumer("123123"), producer(optional("123123")))
)
}
}</programlisting>
<simpara>By wrapping a part of the body with the <literal>optional()</literal> method, you create a regular
expression that must be present 0 or more times.</simpara>
<simpara>If you use Spock for, the following test would be generated from the previous example:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">"""
given:
def request = given()
.header("Content-Type", "application/json")
.body('''{"email":"abc@abc.com","callback_url":"http://partners.com"}''')
when:
def response = given().spec(request)
.post("/users/password")
then:
response.statusCode == 404
response.header('Content-Type') == 'application/json'
and:
DocumentContext parsedJson = JsonPath.parse(response.body.asString())
assertThatJson(parsedJson).field("['code']").matches("(123123)?")
"""</programlisting>
<simpara>The following stub would also be generated:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">'''
{
"request" : {
"url" : "/users/password",
"method" : "POST",
"bodyPatterns" : [ {
"matchesJsonPath" : "$[?(@.['email'] =~ /([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\\\.[a-zA-Z]{2,6})?/)]"
}, {
"matchesJsonPath" : "$[?(@.['callback_url'] =~ /((http[s]?|ftp):\\\\/)\\\\/?([^:\\\\/\\\\s]+)(:[0-9]{1,5})?/)]"
} ],
"headers" : {
"Content-Type" : {
"equalTo" : "application/json"
}
}
},
"response" : {
"status" : 404,
"body" : "{\\"code\\":\\"123123\\",\\"message\\":\\"User not found by email == [not.existing@user.com]\\"}",
"headers" : {
"Content-Type" : "application/json"
}
},
"priority" : 1
}
'''</programlisting>
</section>
<section xml:id="_executing_custom_methods_on_the_server_side">
<title>Executing Custom Methods on the Server Side</title>
<important>
<simpara>This section is valid only for Groovy DSL. Check out the
<xref linkend="contract-matchers"/> section for YAML examples of a similar feature.</simpara>
</important>
<simpara>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:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
request {
method 'PUT'
url $(consumer(regex('^/api/[0-9]{2}$')), producer('/api/12'))
headers {
header 'Content-Type': 'application/json'
}
body '''\
[{
"text": "Gonna see you at Warsaw"
}]
'''
}
response {
body (
path: $(consumer('/api/12'), producer(regex('^/api/[0-9]{2}$'))),
correlationId: $(consumer('1223456'), producer(execute('isProperCorrelationId($it)')))
)
status OK()
}
}</programlisting>
<simpara>The following code shows the base class portion of the test case:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">abstract class BaseMockMvcSpec extends Specification {
def setup() {
RestAssuredMockMvc.standaloneSetup(new PairIdController())
}
void isProperCorrelationId(Integer correlationId) {
assert correlationId == 123456
}
void isEmpty(String value) {
assert value == null
}
}</programlisting>
<important>
<simpara>You cannot use both a String and <literal>execute</literal> to perform concatenation. For
example, calling <literal>header('Authorization', 'Bearer ' + execute('authToken()'))</literal> leads to
improper results. Instead, call <literal>header('Authorization', execute('authToken()'))</literal> and
ensure that the <literal>authToken()</literal> method returns everything you need.</simpara>
</important>
<simpara>The type of the object read from the JSON can be one of the following, depending on the
JSON path:</simpara>
<itemizedlist>
<listitem>
<simpara><literal>String</literal>: If you point to a <literal>String</literal> value in the JSON.</simpara>
</listitem>
<listitem>
<simpara><literal>JSONArray</literal>: If you point to a <literal>List</literal> in the JSON.</simpara>
</listitem>
<listitem>
<simpara><literal>Map</literal>: If you point to a <literal>Map</literal> in the JSON.</simpara>
</listitem>
<listitem>
<simpara><literal>Number</literal>: If you point to <literal>Integer</literal>, <literal>Double</literal> etc. in the JSON.</simpara>
</listitem>
<listitem>
<simpara><literal>Boolean</literal>: If you point to a <literal>Boolean</literal> in the JSON.</simpara>
</listitem>
</itemizedlist>
<simpara>In the request part of the contract, you can specify that the <literal>body</literal> should be taken from
a method.</simpara>
<important>
<simpara>You must provide both the consumer and the producer side. The <literal>execute</literal> part
is applied for the whole body - not for parts of it.</simpara>
</important>
<simpara>The following example shows how to read an object from JSON:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">Contract contractDsl = Contract.make {
request {
method 'GET'
url '/something'
body(
$(c('foo'), p(execute('hashCode()')))
)
}
response {
status OK()
}
}</programlisting>
<simpara>The preceding example results in calling the <literal>hashCode()</literal> method in the request body.
It should resemble the following code:</simpara>
<programlisting language="java" linenumbering="unnumbered">// given:
MockMvcRequestSpecification request = given()
.body(hashCode());
// when:
ResponseOptions response = given().spec(request)
.get("/something");
// then:
assertThat(response.statusCode()).isEqualTo(200);</programlisting>
</section>
<section xml:id="_referencing_the_request_from_the_response">
<title>Referencing the Request from the Response</title>
<simpara>The best situation is to provide fixed values, but sometimes you need to reference a
request in your response.</simpara>
<simpara>If you&#8217;re writing contracts using Groovy DSL, you can use the <literal>fromRequest()</literal> method, which lets
you reference a bunch of elements from the HTTP request. You can use the following
options:</simpara>
<itemizedlist>
<listitem>
<simpara><literal>fromRequest().url()</literal>: Returns the request URL and query parameters.</simpara>
</listitem>
<listitem>
<simpara><literal>fromRequest().query(String key)</literal>: Returns the first query parameter with a given name.</simpara>
</listitem>
<listitem>
<simpara><literal>fromRequest().query(String key, int index)</literal>: Returns the nth query parameter with a
given name.</simpara>
</listitem>
<listitem>
<simpara><literal>fromRequest().path()</literal>: Returns the full path.</simpara>
</listitem>
<listitem>
<simpara><literal>fromRequest().path(int index)</literal>: Returns the nth path element.</simpara>
</listitem>
<listitem>
<simpara><literal>fromRequest().header(String key)</literal>: Returns the first header with a given name.</simpara>
</listitem>
<listitem>
<simpara><literal>fromRequest().header(String key, int index)</literal>: Returns the nth header with a given name.</simpara>
</listitem>
<listitem>
<simpara><literal>fromRequest().body()</literal>: Returns the full request body.</simpara>
</listitem>
<listitem>
<simpara><literal>fromRequest().body(String jsonPath)</literal>: Returns the element from the request that
matches the JSON Path.</simpara>
</listitem>
</itemizedlist>
<simpara>If you&#8217;re using the YAML contract definition you have to use the
<link xl:href="http://handlebarsjs.com/">Handlebars</link> <literal>{{{ }}}</literal> notation with custom, Spring Cloud Contract
functions to achieve this.</simpara>
<itemizedlist>
<listitem>
<simpara><literal>{{{ request.url }}}</literal>: Returns the request URL and query parameters.</simpara>
</listitem>
<listitem>
<simpara><literal>{{{ request.query.key.[index] }}}</literal>: Returns the nth query parameter with a given name.
E.g. for key <literal>foo</literal>, first entry <literal>{{{ request.query.foo.[0] }}}</literal></simpara>
</listitem>
<listitem>
<simpara><literal>{{{ request.path }}}</literal>: Returns the full path.</simpara>
</listitem>
<listitem>
<simpara><literal>{{{ request.path.[index] }}}</literal>: Returns the nth path element. E.g.
for first entry <literal>`</literal>{{{ request.path.[0] }}}</simpara>
</listitem>
<listitem>
<simpara><literal>{{{ request.headers.key }}}</literal>: Returns the first header with a given name.</simpara>
</listitem>
<listitem>
<simpara><literal>{{{ request.headers.key.[index] }}}</literal>: Returns the nth header with a given name.</simpara>
</listitem>
<listitem>
<simpara><literal>{{{ request.body }}}</literal>: Returns the full request body.</simpara>
</listitem>
<listitem>
<simpara><literal>{{{ jsonpath this 'your.json.path' }}}</literal>: Returns the element from the request that
matches the JSON Path. E.g. for json path <literal>$.foo</literal> - <literal>{{{ jsonpath this '$.foo' }}}</literal></simpara>
</listitem>
</itemizedlist>
<simpara>Consider the following contract:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered"></programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">request:
method: GET
url: /api/v1/xxxx
queryParameters:
foo:
- bar
- bar2
headers:
Authorization:
- secret
- secret2
body:
foo: bar
baz: 5
response:
status: 200
headers:
Authorization: "foo {{{ request.headers.Authorization.0 }}} bar"
body:
url: "{{{ request.url }}}"
path: "{{{ request.path }}}"
pathIndex: "{{{ request.path.1 }}}"
param: "{{{ request.query.foo }}}"
paramIndex: "{{{ request.query.foo.1 }}}"
authorization: "{{{ request.headers.Authorization.0 }}}"
authorization2: "{{{ request.headers.Authorization.1 }}"
fullBody: "{{{ request.body }}}"
responseFoo: "{{{ jsonpath this '$.foo' }}}"
responseBaz: "{{{ jsonpath this '$.baz' }}}"
responseBaz2: "Bla bla {{{ jsonpath this '$.foo' }}} bla bla"</programlisting>
</para>
</formalpara>
<simpara>Running a JUnit test generation leads to a test that resembles the following example:</simpara>
<programlisting language="java" linenumbering="unnumbered">// given:
MockMvcRequestSpecification request = given()
.header("Authorization", "secret")
.header("Authorization", "secret2")
.body("{\"foo\":\"bar\",\"baz\":5}");
// when:
ResponseOptions response = given().spec(request)
.queryParam("foo","bar")
.queryParam("foo","bar2")
.get("/api/v1/xxxx");
// then:
assertThat(response.statusCode()).isEqualTo(200);
assertThat(response.header("Authorization")).isEqualTo("foo secret bar");
// and:
DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
assertThatJson(parsedJson).field("['fullBody']").isEqualTo("{\"foo\":\"bar\",\"baz\":5}");
assertThatJson(parsedJson).field("['authorization']").isEqualTo("secret");
assertThatJson(parsedJson).field("['authorization2']").isEqualTo("secret2");
assertThatJson(parsedJson).field("['path']").isEqualTo("/api/v1/xxxx");
assertThatJson(parsedJson).field("['param']").isEqualTo("bar");
assertThatJson(parsedJson).field("['paramIndex']").isEqualTo("bar2");
assertThatJson(parsedJson).field("['pathIndex']").isEqualTo("v1");
assertThatJson(parsedJson).field("['responseBaz']").isEqualTo(5);
assertThatJson(parsedJson).field("['responseFoo']").isEqualTo("bar");
assertThatJson(parsedJson).field("['url']").isEqualTo("/api/v1/xxxx?foo=bar&amp;foo=bar2");
assertThatJson(parsedJson).field("['responseBaz2']").isEqualTo("Bla bla bar bla bla");</programlisting>
<simpara>As you can see, elements from the request have been properly referenced in the response.</simpara>
<simpara>The generated WireMock stub should resemble the following example:</simpara>
<programlisting language="json" linenumbering="unnumbered">{
"request" : {
"urlPath" : "/api/v1/xxxx",
"method" : "POST",
"headers" : {
"Authorization" : {
"equalTo" : "secret2"
}
},
"queryParameters" : {
"foo" : {
"equalTo" : "bar2"
}
},
"bodyPatterns" : [ {
"matchesJsonPath" : "$[?(@.['baz'] == 5)]"
}, {
"matchesJsonPath" : "$[?(@.['foo'] == 'bar')]"
} ]
},
"response" : {
"status" : 200,
"body" : "{\"authorization\":\"{{{request.headers.Authorization.[0]}}}\",\"path\":\"{{{request.path}}}\",\"responseBaz\":{{{jsonpath this '$.baz'}}} ,\"param\":\"{{{request.query.foo.[0]}}}\",\"pathIndex\":\"{{{request.path.[1]}}}\",\"responseBaz2\":\"Bla bla {{{jsonpath this '$.foo'}}} bla bla\",\"responseFoo\":\"{{{jsonpath this '$.foo'}}}\",\"authorization2\":\"{{{request.headers.Authorization.[1]}}}\",\"fullBody\":\"{{{escapejsonbody}}}\",\"url\":\"{{{request.url}}}\",\"paramIndex\":\"{{{request.query.foo.[1]}}}\"}",
"headers" : {
"Authorization" : "{{{request.headers.Authorization.[0]}}};foo"
},
"transformers" : [ "response-template" ]
}
}</programlisting>
<simpara>Sending a request such as the one presented in the <literal>request</literal> part of the contract results
in sending the following response body:</simpara>
<programlisting language="json" linenumbering="unnumbered">{
"url" : "/api/v1/xxxx?foo=bar&amp;foo=bar2",
"path" : "/api/v1/xxxx",
"pathIndex" : "v1",
"param" : "bar",
"paramIndex" : "bar2",
"authorization" : "secret",
"authorization2" : "secret2",
"fullBody" : "{\"foo\":\"bar\",\"baz\":5}",
"responseFoo" : "bar",
"responseBaz" : 5,
"responseBaz2" : "Bla bla bar bla bla"
}</programlisting>
<important>
<simpara>This feature works only with WireMock having a version greater than or equal
to 2.5.1. The Spring Cloud Contract Verifier uses WireMock&#8217;s
<literal>response-template</literal> response transformer. It uses Handlebars to convert the Mustache <literal>{{{ }}}</literal> templates into
proper values. Additionally, it registers two helper functions:</simpara>
</important>
<itemizedlist>
<listitem>
<simpara><literal>escapejsonbody</literal>: Escapes the request body in a format that can be embedded in a JSON.</simpara>
</listitem>
<listitem>
<simpara><literal>jsonpath</literal>: For a given parameter, find an object in the request body.</simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="_registering_your_own_wiremock_extension">
<title>Registering Your Own WireMock Extension</title>
<simpara>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
<literal>org.springframework.cloud.contract.verifier.dsl.wiremock.WireMockExtensions</literal> interface.
Since we use the spring.factories extension approach, you can create an entry in
<literal>META-INF/spring.factories</literal> file similar to the following:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.verifier.dsl.wiremock.WireMockExtensions=\
org.springframework.cloud.contract.stubrunner.provider.wiremock.TestWireMockExtensions
org.springframework.cloud.contract.spec.ContractConverter=\
org.springframework.cloud.contract.stubrunner.TestCustomYamlContractConverter</programlisting>
<simpara>The following is an example of a custom extension:</simpara>
<formalpara>
<title>TestWireMockExtensions.groovy</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">package org.springframework.cloud.contract.verifier.dsl.wiremock
import com.github.tomakehurst.wiremock.extension.Extension
/**
* Extension that registers the default transformer and the custom one
*/
class TestWireMockExtensions implements WireMockExtensions {
@Override
List&lt;Extension&gt; extensions() {
return [
new DefaultResponseTransformer(),
new CustomExtension()
]
}
}
class CustomExtension implements Extension {
@Override
String getName() {
return "foo-transformer"
}
}</programlisting>
</para>
</formalpara>
<important>
<simpara>Remember to override the <literal>applyGlobally()</literal> method and set it to <literal>false</literal> if you
want the transformation to be applied only for a mapping that explicitly requires it.</simpara>
</important>
</section>
<section xml:id="contract-matchers">
<title>Dynamic Properties in the Matchers Sections</title>
<simpara>If you work with <link xl:href="https://docs.pact.io/">Pact</link>, 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.</simpara>
<simpara>You can use the <literal>bodyMatchers</literal> section for two reasons:</simpara>
<itemizedlist>
<listitem>
<simpara>Define the dynamic values that should end up in a stub.
You can set it in the <literal>request</literal> or <literal>inputMessage</literal> part of your contract.</simpara>
</listitem>
<listitem>
<simpara>Verify the result of your test.
This section is present in the <literal>response</literal> or <literal>outputMessage</literal> side of the
contract.</simpara>
</listitem>
</itemizedlist>
<simpara>Currently, Spring Cloud Contract Verifier supports only JSON Path-based matchers with the
following matching possibilities:</simpara>
<itemizedlist>
<title>Groovy DSL</title>
<listitem>
<simpara>For the stubs(in tests on the Consumer&#8217;s side):</simpara>
<itemizedlist>
<listitem>
<simpara><literal>byEquality()</literal>: The value taken from the consumer&#8217;s request via the provided JSON Path must be
equal to the value provided in the contract.</simpara>
</listitem>
<listitem>
<simpara><literal>byRegex(&#8230;&#8203;)</literal>: The value taken from the consumer&#8217;s request via the provided JSON Path must
match the regex.</simpara>
</listitem>
<listitem>
<simpara><literal>byDate()</literal>: The value taken from the consumer&#8217;s request via the provided JSON Path must
match the regex for an ISO Date value.</simpara>
</listitem>
<listitem>
<simpara><literal>byTimestamp()</literal>: The value taken from the consumer&#8217;s request via the provided JSON Path must
match the regex for an ISO DateTime value.</simpara>
</listitem>
<listitem>
<simpara><literal>byTime()</literal>: The value taken from the consumer&#8217;s request via the provided JSON Path must
match the regex for an ISO Time value.</simpara>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<simpara>For the verification(in generated tests on the Producer&#8217;s side):</simpara>
<itemizedlist>
<listitem>
<simpara><literal>byEquality()</literal>: The value taken from the producer&#8217;s response via the provided JSON Path must be
equal to the provided value in the contract.</simpara>
</listitem>
<listitem>
<simpara><literal>byRegex(&#8230;&#8203;)</literal>: The value taken from the producer&#8217;s response via the provided JSON Path must
match the regex.</simpara>
</listitem>
<listitem>
<simpara><literal>byDate()</literal>: The value taken from the producer&#8217;s response via the provided JSON Path must match
the regex for an ISO Date value.</simpara>
</listitem>
<listitem>
<simpara><literal>byTimestamp()</literal>: The value taken from the producer&#8217;s response via the provided JSON Path must
match the regex for an ISO DateTime value.</simpara>
</listitem>
<listitem>
<simpara><literal>byTime()</literal>: The value taken from the producer&#8217;s response via the provided JSON Path must match
the regex for an ISO Time value.</simpara>
</listitem>
<listitem>
<simpara><literal>byType()</literal>: The value taken from the producer&#8217;s response via the provided JSON Path needs to be
of the same type as the type defined in the body of the response in the contract.
<literal>byType</literal> can take a closure, in which you can set <literal>minOccurrence</literal> and <literal>maxOccurrence</literal>. For the request side, you should use the closure to assert size of the collection.
That way, you can assert the size of the flattened collection. To check the size of an
unflattened collection, use a custom method with the <literal>byCommand(&#8230;&#8203;)</literal> testMatcher.</simpara>
</listitem>
<listitem>
<simpara><literal>byCommand(&#8230;&#8203;)</literal>: The value taken from the producer&#8217;s response via the provided JSON Path is
passed as an input to the custom method that you provide. For example,
<literal>byCommand('foo($it)')</literal> results in calling a <literal>foo</literal> method to which the value matching the
JSON Path gets passed. The type of the object read from the JSON can be one of the
following, depending on the JSON path:</simpara>
<itemizedlist>
<listitem>
<simpara><literal>String</literal>: If you point to a <literal>String</literal> value.</simpara>
</listitem>
<listitem>
<simpara><literal>JSONArray</literal>: If you point to a <literal>List</literal>.</simpara>
</listitem>
<listitem>
<simpara><literal>Map</literal>: If you point to a <literal>Map</literal>.</simpara>
</listitem>
<listitem>
<simpara><literal>Number</literal>: If you point to <literal>Integer</literal>, <literal>Double</literal>, or other kind of number.</simpara>
</listitem>
<listitem>
<simpara><literal>Boolean</literal>: If you point to a <literal>Boolean</literal>.</simpara>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<simpara><literal>byNull()</literal>: The value taken from the response via the provided JSON Path must be null</simpara>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<formalpara>
<title>YAML</title>
<para><emphasis>Please read the Groovy section for detailed explanation of
what the types mean</emphasis></para>
</formalpara>
<simpara>For YAML the structure of a matcher looks like this</simpara>
<programlisting language="yml" linenumbering="unnumbered">- path: $.foo
type: by_regex
value: bar</programlisting>
<simpara>Or if you want to use one of the predefined regular expressions
<literal>[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]</literal>:</simpara>
<programlisting language="yml" linenumbering="unnumbered">- path: $.foo
type: by_regex
predefined: only_alpha_unicode</programlisting>
<simpara>Below you can find the allowed list of `type`s.</simpara>
<itemizedlist>
<listitem>
<simpara>For <literal>stubMatchers</literal>:</simpara>
<itemizedlist>
<listitem>
<simpara><literal>by_equality</literal></simpara>
</listitem>
<listitem>
<simpara><literal>by_regex</literal></simpara>
</listitem>
<listitem>
<simpara><literal>by_date</literal></simpara>
</listitem>
<listitem>
<simpara><literal>by_timestamp</literal></simpara>
</listitem>
<listitem>
<simpara><literal>by_time</literal></simpara>
</listitem>
<listitem>
<simpara><literal>by_type</literal></simpara>
<itemizedlist>
<listitem>
<simpara>there are 2 additional fields accepted: <literal>minOccurrence</literal> and <literal>maxOccurrence</literal>.</simpara>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<simpara>For <literal>testMatchers</literal>:</simpara>
<itemizedlist>
<listitem>
<simpara><literal>by_equality</literal></simpara>
</listitem>
<listitem>
<simpara><literal>by_regex</literal></simpara>
</listitem>
<listitem>
<simpara><literal>by_date</literal></simpara>
</listitem>
<listitem>
<simpara><literal>by_timestamp</literal></simpara>
</listitem>
<listitem>
<simpara><literal>by_time</literal></simpara>
</listitem>
<listitem>
<simpara><literal>by_type</literal></simpara>
<itemizedlist>
<listitem>
<simpara>there are 2 additional fields accepted: <literal>minOccurrence</literal> and <literal>maxOccurrence</literal>.</simpara>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<simpara><literal>by_command</literal></simpara>
</listitem>
<listitem>
<simpara><literal>by_null</literal></simpara>
</listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<simpara>Consider the following example:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">Contract contractDsl = Contract.make {
request {
method 'GET'
urlPath '/get'
body([
duck : 123,
alpha : 'abc',
number : 123,
aBoolean : true,
date : '2017-01-01',
dateTime : '2017-01-01T01:23:45',
time : '01:02:34',
valueWithoutAMatcher: 'foo',
valueWithTypeMatch : 'string',
key : [
'complex.key': 'foo'
]
])
bodyMatchers {
jsonPath('$.duck', byRegex("[0-9]{3}"))
jsonPath('$.duck', byEquality())
jsonPath('$.alpha', byRegex(onlyAlphaUnicode()))
jsonPath('$.alpha', byEquality())
jsonPath('$.number', byRegex(number()))
jsonPath('$.aBoolean', byRegex(anyBoolean()))
jsonPath('$.date', byDate())
jsonPath('$.dateTime', byTimestamp())
jsonPath('$.time', byTime())
jsonPath("\$.['key'].['complex.key']", byEquality())
}
headers {
contentType(applicationJson())
}
}
response {
status OK()
body([
duck : 123,
alpha : 'abc',
number : 123,
positiveInteger : 1234567890,
negativeInteger : -1234567890,
positiveDecimalNumber: 123.4567890,
negativeDecimalNumber: -123.4567890,
aBoolean : true,
date : '2017-01-01',
dateTime : '2017-01-01T01:23:45',
time : "01:02:34",
valueWithoutAMatcher : 'foo',
valueWithTypeMatch : 'string',
valueWithMin : [
1, 2, 3
],
valueWithMax : [
1, 2, 3
],
valueWithMinMax : [
1, 2, 3
],
valueWithMinEmpty : [],
valueWithMaxEmpty : [],
key : [
'complex.key': 'foo'
],
nullValue : null
])
bodyMatchers {
// asserts the jsonpath value against manual regex
jsonPath('$.duck', byRegex("[0-9]{3}"))
// asserts the jsonpath value against the provided value
jsonPath('$.duck', byEquality())
// asserts the jsonpath value against some default regex
jsonPath('$.alpha', byRegex(onlyAlphaUnicode()))
jsonPath('$.alpha', byEquality())
jsonPath('$.number', byRegex(number()))
jsonPath('$.positiveInteger', byRegex(anInteger()))
jsonPath('$.negativeInteger', byRegex(anInteger()))
jsonPath('$.positiveDecimalNumber', byRegex(aDouble()))
jsonPath('$.negativeDecimalNumber', byRegex(aDouble()))
jsonPath('$.aBoolean', byRegex(anyBoolean()))
// asserts vs inbuilt time related regex
jsonPath('$.date', byDate())
jsonPath('$.dateTime', byTimestamp())
jsonPath('$.time', byTime())
// asserts that the resulting type is the same as in response body
jsonPath('$.valueWithTypeMatch', byType())
jsonPath('$.valueWithMin', byType {
// results in verification of size of array (min 1)
minOccurrence(1)
})
jsonPath('$.valueWithMax', byType {
// results in verification of size of array (max 3)
maxOccurrence(3)
})
jsonPath('$.valueWithMinMax', byType {
// results in verification of size of array (min 1 &amp; max 3)
minOccurrence(1)
maxOccurrence(3)
})
jsonPath('$.valueWithMinEmpty', byType {
// results in verification of size of array (min 0)
minOccurrence(0)
})
jsonPath('$.valueWithMaxEmpty', byType {
// results in verification of size of array (max 0)
maxOccurrence(0)
})
// will execute a method `assertThatValueIsANumber`
jsonPath('$.duck', byCommand('assertThatValueIsANumber($it)'))
jsonPath("\$.['key'].['complex.key']", byEquality())
jsonPath('$.nullValue', byNull())
}
headers {
contentType(applicationJson())
header('Some-Header', $(c('someValue'), p(regex('[a-zA-Z]{9}'))))
}
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">request:
method: GET
urlPath: /get/1
headers:
Content-Type: application/json
cookies:
foo: 2
bar: 3
queryParameters:
limit: 10
offset: 20
filter: 'email'
sort: name
search: 55
age: 99
name: John.Doe
email: 'bob@email.com'
body:
duck: 123
alpha: "abc"
number: 123
aBoolean: true
date: "2017-01-01"
dateTime: "2017-01-01T01:23:45"
time: "01:02:34"
valueWithoutAMatcher: "foo"
valueWithTypeMatch: "string"
key:
"complex.key": 'foo'
nullValue: null
valueWithMin:
- 1
- 2
- 3
valueWithMax:
- 1
- 2
- 3
valueWithMinMax:
- 1
- 2
- 3
valueWithMinEmpty: []
valueWithMaxEmpty: []
matchers:
url:
regex: /get/[0-9]
# predefined:
# execute a method
#command: 'equals($it)'
queryParameters:
- key: limit
type: equal_to
value: 20
- key: offset
type: containing
value: 20
- key: sort
type: equal_to
value: name
- key: search
type: not_matching
value: '^[0-9]{2}$'
- key: age
type: not_matching
value: '^\\w*$'
- key: name
type: matching
value: 'John.*'
- key: hello
type: absent
cookies:
- key: foo
regex: '[0-9]'
- key: bar
command: 'equals($it)'
headers:
- key: Content-Type
regex: "application/json.*"
body:
- path: $.duck
type: by_regex
value: "[0-9]{3}"
- path: $.duck
type: by_equality
- path: $.alpha
type: by_regex
predefined: only_alpha_unicode
- path: $.alpha
type: by_equality
- path: $.number
type: by_regex
predefined: number
- path: $.aBoolean
type: by_regex
predefined: any_boolean
- path: $.date
type: by_date
- path: $.dateTime
type: by_timestamp
- path: $.time
type: by_time
- path: "$.['key'].['complex.key']"
type: by_equality
- path: $.nullvalue
type: by_null
- path: $.valueWithMin
type: by_type
minOccurrence: 1
- path: $.valueWithMax
type: by_type
maxOccurrence: 3
- path: $.valueWithMinMax
type: by_type
minOccurrence: 1
maxOccurrence: 3
response:
status: 200
cookies:
foo: 1
bar: 2
body:
duck: 123
alpha: "abc"
number: 123
aBoolean: true
date: "2017-01-01"
dateTime: "2017-01-01T01:23:45"
time: "01:02:34"
valueWithoutAMatcher: "foo"
valueWithTypeMatch: "string"
valueWithMin:
- 1
- 2
- 3
valueWithMax:
- 1
- 2
- 3
valueWithMinMax:
- 1
- 2
- 3
valueWithMinEmpty: []
valueWithMaxEmpty: []
key:
'complex.key' : 'foo'
nulValue: null
matchers:
headers:
- key: Content-Type
regex: "application/json.*"
cookies:
- key: foo
regex: '[0-9]'
- key: bar
command: 'equals($it)'
body:
- path: $.duck
type: by_regex
value: "[0-9]{3}"
- path: $.duck
type: by_equality
- path: $.alpha
type: by_regex
predefined: only_alpha_unicode
- path: $.alpha
type: by_equality
- path: $.number
type: by_regex
predefined: number
- path: $.aBoolean
type: by_regex
predefined: any_boolean
- path: $.date
type: by_date
- path: $.dateTime
type: by_timestamp
- path: $.time
type: by_time
- path: $.valueWithTypeMatch
type: by_type
- path: $.valueWithMin
type: by_type
minOccurrence: 1
- path: $.valueWithMax
type: by_type
maxOccurrence: 3
- path: $.valueWithMinMax
type: by_type
minOccurrence: 1
maxOccurrence: 3
- path: $.valueWithMinEmpty
type: by_type
minOccurrence: 0
- path: $.valueWithMaxEmpty
type: by_type
maxOccurrence: 0
- path: $.duck
type: by_command
value: assertThatValueIsANumber($it)
- path: $.nullValue
type: by_null
value: null
headers:
Content-Type: application/json</programlisting>
</para>
</formalpara>
<simpara>In the preceding example, you can see the dynamic portions of the contract in the
<literal>matchers</literal> sections. For the request part, you can see that, for all fields but
<literal>valueWithoutAMatcher</literal>, the values of the regular expressions that the stub should
contain are explicitly set. For the <literal>valueWithoutAMatcher</literal>, the verification takes place
in the same way as without the use of matchers. In that case, the test performs an
equality check.</simpara>
<simpara>For the response side in the <literal>bodyMatchers</literal> section, we define the dynamic parts in a
similar manner. The only difference is that the <literal>byType</literal> 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):</simpara>
<itemizedlist>
<listitem>
<simpara>For <literal>$.valueWithTypeMatch</literal>, the engine checks whether the type is the same.</simpara>
</listitem>
<listitem>
<simpara>For <literal>$.valueWithMin</literal>, the engine check the type and asserts whether the size is greater
than or equal to the minimum occurrence.</simpara>
</listitem>
<listitem>
<simpara>For <literal>$.valueWithMax</literal>, the engine checks the type and asserts whether the size is
smaller than or equal to the maximum occurrence.</simpara>
</listitem>
<listitem>
<simpara>For <literal>$.valueWithMinMax</literal>, the engine checks the type and asserts whether the size is
between the min and maximum occurrence.</simpara>
</listitem>
</itemizedlist>
<simpara>The resulting test would resemble the following example (note that an <literal>and</literal> section
separates the autogenerated assertions and the assertion from matchers):</simpara>
<programlisting language="java" linenumbering="unnumbered">// given:
MockMvcRequestSpecification request = given()
.header("Content-Type", "application/json")
.body("{\"duck\":123,\"alpha\":\"abc\",\"number\":123,\"aBoolean\":true,\"date\":\"2017-01-01\",\"dateTime\":\"2017-01-01T01:23:45\",\"time\":\"01:02:34\",\"valueWithoutAMatcher\":\"foo\",\"valueWithTypeMatch\":\"string\",\"key\":{\"complex.key\":\"foo\"}}");
// when:
ResponseOptions response = given().spec(request)
.get("/get");
// then:
assertThat(response.statusCode()).isEqualTo(200);
assertThat(response.header("Content-Type")).matches("application/json.*");
// and:
DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
assertThatJson(parsedJson).field("['valueWithoutAMatcher']").isEqualTo("foo");
// and:
assertThat(parsedJson.read("$.duck", String.class)).matches("[0-9]{3}");
assertThat(parsedJson.read("$.duck", Integer.class)).isEqualTo(123);
assertThat(parsedJson.read("$.alpha", String.class)).matches("[\\p{L}]*");
assertThat(parsedJson.read("$.alpha", String.class)).isEqualTo("abc");
assertThat(parsedJson.read("$.number", String.class)).matches("-?(\\d*\\.\\d+|\\d+)");
assertThat(parsedJson.read("$.aBoolean", String.class)).matches("(true|false)");
assertThat(parsedJson.read("$.date", String.class)).matches("(\\d\\d\\d\\d)-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])");
assertThat(parsedJson.read("$.dateTime", String.class)).matches("([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])");
assertThat(parsedJson.read("$.time", String.class)).matches("(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])");
assertThat((Object) parsedJson.read("$.valueWithTypeMatch")).isInstanceOf(java.lang.String.class);
assertThat((Object) parsedJson.read("$.valueWithMin")).isInstanceOf(java.util.List.class);
assertThat((java.lang.Iterable) parsedJson.read("$.valueWithMin", java.util.Collection.class)).as("$.valueWithMin").hasSizeGreaterThanOrEqualTo(1);
assertThat((Object) parsedJson.read("$.valueWithMax")).isInstanceOf(java.util.List.class);
assertThat((java.lang.Iterable) parsedJson.read("$.valueWithMax", java.util.Collection.class)).as("$.valueWithMax").hasSizeLessThanOrEqualTo(3);
assertThat((Object) parsedJson.read("$.valueWithMinMax")).isInstanceOf(java.util.List.class);
assertThat((java.lang.Iterable) parsedJson.read("$.valueWithMinMax", java.util.Collection.class)).as("$.valueWithMinMax").hasSizeBetween(1, 3);
assertThat((Object) parsedJson.read("$.valueWithMinEmpty")).isInstanceOf(java.util.List.class);
assertThat((java.lang.Iterable) parsedJson.read("$.valueWithMinEmpty", java.util.Collection.class)).as("$.valueWithMinEmpty").hasSizeGreaterThanOrEqualTo(0);
assertThat((Object) parsedJson.read("$.valueWithMaxEmpty")).isInstanceOf(java.util.List.class);
assertThat((java.lang.Iterable) parsedJson.read("$.valueWithMaxEmpty", java.util.Collection.class)).as("$.valueWithMaxEmpty").hasSizeLessThanOrEqualTo(0);
assertThatValueIsANumber(parsedJson.read("$.duck"));
assertThat(parsedJson.read("$.['key'].['complex.key']", String.class)).isEqualTo("foo");</programlisting>
<important>
<simpara>Notice that, for the <literal>byCommand</literal> method, the example calls the
<literal>assertThatValueIsANumber</literal>. This method must be defined in the test base class or be
statically imported to your tests. Notice that the <literal>byCommand</literal> call was converted to
<literal>assertThatValueIsANumber(parsedJson.read("$.duck"));</literal>. That means that the engine took
the method name and passed the proper JSON path as a parameter to it.</simpara>
</important>
<simpara>The resulting WireMock stub is in the following example:</simpara>
<programlisting language="json" linenumbering="unnumbered"> '''
{
"request" : {
"urlPath" : "/get",
"method" : "POST",
"headers" : {
"Content-Type" : {
"matches" : "application/json.*"
}
},
"bodyPatterns" : [ {
"matchesJsonPath" : "$.['list'].['some'].['nested'][?(@.['anothervalue'] == 4)]"
}, {
"matchesJsonPath" : "$[?(@.['valueWithoutAMatcher'] == 'foo')]"
}, {
"matchesJsonPath" : "$[?(@.['valueWithTypeMatch'] == 'string')]"
}, {
"matchesJsonPath" : "$.['list'].['someother'].['nested'][?(@.['json'] == 'with value')]"
}, {
"matchesJsonPath" : "$.['list'].['someother'].['nested'][?(@.['anothervalue'] == 4)]"
}, {
"matchesJsonPath" : "$[?(@.duck =~ /([0-9]{3})/)]"
}, {
"matchesJsonPath" : "$[?(@.duck == 123)]"
}, {
"matchesJsonPath" : "$[?(@.alpha =~ /([\\\\p{L}]*)/)]"
}, {
"matchesJsonPath" : "$[?(@.alpha == 'abc')]"
}, {
"matchesJsonPath" : "$[?(@.number =~ /(-?(\\\\d*\\\\.\\\\d+|\\\\d+))/)]"
}, {
"matchesJsonPath" : "$[?(@.aBoolean =~ /((true|false))/)]"
}, {
"matchesJsonPath" : "$[?(@.date =~ /((\\\\d\\\\d\\\\d\\\\d)-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01]))/)]"
}, {
"matchesJsonPath" : "$[?(@.dateTime =~ /(([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9]))/)]"
}, {
"matchesJsonPath" : "$[?(@.time =~ /((2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9]))/)]"
}, {
"matchesJsonPath" : "$.list.some.nested[?(@.json =~ /(.*)/)]"
}, {
"matchesJsonPath" : "$[?(@.valueWithMin.size() &gt;= 1)]"
}, {
"matchesJsonPath" : "$[?(@.valueWithMax.size() &lt;= 3)]"
}, {
"matchesJsonPath" : "$[?(@.valueWithMinMax.size() &gt;= 1 &amp;&amp; @.valueWithMinMax.size() &lt;= 3)]"
}, {
"matchesJsonPath" : "$[?(@.valueWithOccurrence.size() &gt;= 4 &amp;&amp; @.valueWithOccurrence.size() &lt;= 4)]"
} ]
},
"response" : {
"status" : 200,
"body" : "{\\"date\\":\\"2017-01-01\\",\\"dateTime\\":\\"2017-01-01T01:23:45\\",\\"aBoolean\\":true,\\"valueWithMax\\":[1,2,3],\\"valueWithOccurrence\\":[1,2,3,4],\\"number\\":123,\\"duck\\":123,\\"alpha\\":\\"abc\\",\\"valueWithMin\\":[1,2,3],\\"time\\":\\"01:02:34\\",\\"valueWithTypeMatch\\":\\"string\\",\\"valueWithMinMax\\":[1,2,3],\\"valueWithoutAMatcher\\":\\"foo\\"}",
"headers" : {
"Content-Type" : "application/json"
},
"transformers" : [ "response-template" ]
}
}
'''</programlisting>
<important>
<simpara>If you use a <literal>matcher</literal>, then the part of the request and response that the
<literal>matcher</literal> addresses with the JSON Path gets removed from the assertion. In the case of
verifying a collection, you must create matchers for <emphasis role="strong">all</emphasis> the elements of the
collection.</simpara>
</important>
<simpara>Consider the following example:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">Contract.make {
request {
method 'GET'
url("/foo")
}
response {
status OK()
body(events: [[
operation : 'EXPORT',
eventId : '16f1ed75-0bcc-4f0d-a04d-3121798faf99',
status : 'OK'
], [
operation : 'INPUT_PROCESSING',
eventId : '3bb4ac82-6652-462f-b6d1-75e424a0024a',
status : 'OK'
]
]
)
bodyMatchers {
jsonPath('$.events[0].operation', byRegex('.+'))
jsonPath('$.events[0].eventId', byRegex('^([a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})$'))
jsonPath('$.events[0].status', byRegex('.+'))
}
}
}</programlisting>
<simpara>The preceding code leads to creating the following test (the code block shows only the assertion section):</simpara>
<programlisting language="java" linenumbering="unnumbered">and:
DocumentContext parsedJson = JsonPath.parse(response.body.asString())
assertThatJson(parsedJson).array("['events']").contains("['eventId']").isEqualTo("16f1ed75-0bcc-4f0d-a04d-3121798faf99")
assertThatJson(parsedJson).array("['events']").contains("['operation']").isEqualTo("EXPORT")
assertThatJson(parsedJson).array("['events']").contains("['operation']").isEqualTo("INPUT_PROCESSING")
assertThatJson(parsedJson).array("['events']").contains("['eventId']").isEqualTo("3bb4ac82-6652-462f-b6d1-75e424a0024a")
assertThatJson(parsedJson).array("['events']").contains("['status']").isEqualTo("OK")
and:
assertThat(parsedJson.read("\$.events[0].operation", String.class)).matches(".+")
assertThat(parsedJson.read("\$.events[0].eventId", String.class)).matches("^([a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12})\$")
assertThat(parsedJson.read("\$.events[0].status", String.class)).matches(".+")</programlisting>
<simpara>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 <literal>$.events</literal>
collection and assert it with the <literal>byCommand(&#8230;&#8203;)</literal> method.</simpara>
</section>
</section>
<section xml:id="_jax_rs_support">
<title>JAX-RS Support</title>
<simpara>The Spring Cloud Contract Verifier supports the JAX-RS 2 Client API. The base class needs
to define <literal>protected WebTarget webTarget</literal> and server initialization. The only option for
testing JAX-RS API is to start a web server. Also, a request with a body needs to have a
content type set. Otherwise, the default of <literal>application/octet-stream</literal> gets used.</simpara>
<simpara>In order to use JAX-RS mode, use the following settings:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">testMode == 'JAXRSCLIENT'</programlisting>
<simpara>The following example shows a generated test API:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">'''
// when:
Response response = webTarget
.path("/users")
.queryParam("limit", "10")
.queryParam("offset", "20")
.queryParam("filter", "email")
.queryParam("sort", "name")
.queryParam("search", "55")
.queryParam("age", "99")
.queryParam("name", "Denis.Stepanov")
.queryParam("email", "bob@email.com")
.request()
.method("GET");
String responseAsString = response.readEntity(String.class);
// then:
assertThat(response.getStatus()).isEqualTo(200);
// and:
DocumentContext parsedJson = JsonPath.parse(responseAsString);
assertThatJson(parsedJson).field("['property1']").isEqualTo("a");
'''</programlisting>
</section>
<section xml:id="_async_support">
<title>Async Support</title>
<simpara>If you&#8217;re using asynchronous communication on the server side (your controllers are
returning <literal>Callable</literal>, <literal>DeferredResult</literal>, and so on), then, inside your contract, you must
provide an <literal>async()</literal> method in the <literal>response</literal> section. The following code shows an example:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
request {
method GET()
url '/get'
}
response {
status OK()
body 'Passed'
async()
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">response:
async: true</programlisting>
</para>
</formalpara>
<simpara>You can also use the <literal>fixedDelayMilliseconds</literal> method / property to add delay to your stubs.</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
request {
method GET()
url '/get'
}
response {
status 200
body 'Passed'
fixedDelayMilliseconds 1000
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">response:
fixedDelayMilliseconds: 1000</programlisting>
</para>
</formalpara>
</section>
<section xml:id="_working_with_context_paths">
<title>Working with Context Paths</title>
<simpara>Spring Cloud Contract supports context paths.</simpara>
<important>
<simpara>The only change needed to fully support context paths is the switch on the
<emphasis role="strong">PRODUCER</emphasis> side. Also, the autogenerated tests must use <emphasis role="strong">EXPLICIT</emphasis> mode. The consumer
side remains untouched. In order for the generated test to pass, you must use <emphasis role="strong">EXPLICIT</emphasis>
mode.</simpara>
</important>
<formalpara role="primary">
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;configuration&gt;
&lt;testMode&gt;EXPLICIT&lt;/testMode&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</programlisting>
</para>
</formalpara>
<formalpara role="secondary">
<title>Gradle</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">contracts {
testMode = 'EXPLICIT'
}</programlisting>
</para>
</formalpara>
<simpara>That way, you generate a test that <emphasis role="strong">DOES NOT</emphasis> use MockMvc. It means that you generate
real requests and you need to setup your generated test&#8217;s base class to work on a real
socket.</simpara>
<simpara>Consider the following contract:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">org.springframework.cloud.contract.spec.Contract.make {
request {
method 'GET'
url '/my-context-path/url'
}
response {
status OK()
}
}</programlisting>
<simpara>The following example shows how to set up a base class and Rest Assured:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">import io.restassured.RestAssured;
import org.junit.Before;
import org.springframework.boot.web.server.LocalServerPort;
import org.springframework.boot.test.context.SpringBootTest;
@SpringBootTest(classes = ContextPathTestingBaseClass.class, webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class ContextPathTestingBaseClass {
@LocalServerPort int port;
@Before
public void setup() {
RestAssured.baseURI = "http://localhost";
RestAssured.port = this.port;
}
}</programlisting>
<simpara>If you do it this way:</simpara>
<itemizedlist>
<listitem>
<simpara>All of your requests in the autogenerated tests are sent to the real endpoint with your
context path included (for example, <literal>/my-context-path/url</literal>).</simpara>
</listitem>
<listitem>
<simpara>Your contracts reflect that you have a context path. Your generated stubs also have
that information (for example, in the stubs, you have to call <literal>/my-context-path/url</literal>).</simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="_working_with_web_flux">
<title>Working with Web Flux</title>
<simpara>Spring Cloud Contract requires the usage of <literal>EXPLICIT</literal> mode in your generated tests
to work with Web Flux.</simpara>
<formalpara role="primary">
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;configuration&gt;
&lt;testMode&gt;EXPLICIT&lt;/testMode&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</programlisting>
</para>
</formalpara>
<formalpara role="secondary">
<title>Gradle</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">contracts {
testMode = 'EXPLICIT'
}</programlisting>
</para>
</formalpara>
<simpara>The following example shows how to set up a base class and Rest Assured for Web Flux:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">@RunWith(SpringRunner.class)
@SpringBootTest(classes = BeerRestBase.Config.class,
webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT,
properties = "server.port=0")
public abstract class BeerRestBase {
// your tests go here
// in this config class you define all controllers and mocked services
@Configuration
@EnableAutoConfiguration
static class Config {
@Bean
PersonCheckingService personCheckingService() {
return personToCheck -&gt; personToCheck.age &gt;= 20;
}
@Bean
ProducerController producerController() {
return new ProducerController(personCheckingService());
}
}
}</programlisting>
</section>
<section xml:id="_messaging_top_level_elements">
<title>Messaging Top-Level Elements</title>
<simpara>The DSL for messaging looks a little bit different than the one that focuses on HTTP. The
following sections explain the differences:</simpara>
<itemizedlist>
<listitem>
<simpara><xref linkend="contract-dsl-output-triggered-method"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="contract-dsl-output-triggered-message"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="contract-dsl-consumer-producer"/></simpara>
</listitem>
<listitem>
<simpara><xref linkend="contract-dsl-common"/></simpara>
</listitem>
</itemizedlist>
<section xml:id="contract-dsl-output-triggered-method">
<title>Output Triggered by a Method</title>
<simpara>The output message can be triggered by calling a method (such as a <literal>Scheduler</literal> when a was
started and a message was sent), as shown in the following example:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">def dsl = Contract.make {
// Human readable description
description 'Some description'
// Label by means of which the output message can be triggered
label 'some_label'
// input to the contract
input {
// the contract will be triggered by a method
triggeredBy('bookReturnedTriggered()')
}
// output message of the contract
outputMessage {
// destination to which the output message will be sent
sentTo('output')
// the body of the output message
body('''{ "bookName" : "foo" }''')
// the headers of the output message
headers {
header('BOOK-NAME', 'foo')
}
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered"># Human readable description
description: Some description
# Label by means of which the output message can be triggered
label: some_label
input:
# the contract will be triggered by a method
triggeredBy: bookReturnedTriggered()
# output message of the contract
outputMessage:
# destination to which the output message will be sent
sentTo: output
# the body of the output message
body:
bookName: foo
# the headers of the output message
headers:
BOOK-NAME: foo</programlisting>
</para>
</formalpara>
<simpara>In the previous example case, the output message is sent to <literal>output</literal> if a method called
<literal>bookReturnedTriggered</literal> is executed. On the message <emphasis role="strong">publisher&#8217;s</emphasis> side, we generate a
test that calls that method to trigger the message. On the <emphasis role="strong">consumer</emphasis> side, you can use
the <literal>some_label</literal> to trigger the message.</simpara>
</section>
<section xml:id="contract-dsl-output-triggered-message">
<title>Output Triggered by a Message</title>
<simpara>The output message can be triggered by receiving a message, as shown in the following
example:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">def dsl = Contract.make {
description 'Some Description'
label 'some_label'
// input is a message
input {
// the message was received from this destination
messageFrom('input')
// has the following body
messageBody([
bookName: 'foo'
])
// and the following headers
messageHeaders {
header('sample', 'header')
}
}
outputMessage {
sentTo('output')
body([
bookName: 'foo'
])
headers {
header('BOOK-NAME', 'foo')
}
}
}</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered"># Human readable description
description: Some description
# Label by means of which the output message can be triggered
label: some_label
# input is a message
input:
messageFrom: input
# has the following body
messageBody:
bookName: 'foo'
# and the following headers
messageHeaders:
sample: 'header'
# output message of the contract
outputMessage:
# destination to which the output message will be sent
sentTo: output
# the body of the output message
body:
bookName: foo
# the headers of the output message
headers:
BOOK-NAME: foo</programlisting>
</para>
</formalpara>
<simpara>In the preceding example, the output message is sent to <literal>output</literal> if a proper message is
received on the <literal>input</literal> destination. On the message <emphasis role="strong">publisher&#8217;s</emphasis> side, the engine
generates a test that sends the input message to the defined destination. On the
<emphasis role="strong">consumer</emphasis> side, you can either send a message to the input destination or use a label
(<literal>some_label</literal> in the example) to trigger the message.</simpara>
</section>
<section xml:id="contract-dsl-consumer-producer">
<title>Consumer/Producer</title>
<important>
<simpara>This section is valid only for Groovy DSL.</simpara>
</important>
<simpara>In HTTP, you have a notion of <literal>client</literal>/<literal>stub and `server</literal>/<literal>test</literal> notation. You can also
use those paradigms in messaging. In addition, Spring Cloud Contract Verifier also
provides the <literal>consumer</literal> and <literal>producer</literal> methods, as presented in the following example
(note that you can use either <literal>$</literal> or <literal>value</literal> methods to provide <literal>consumer</literal> and <literal>producer</literal>
parts):</simpara>
<programlisting language="groovy" linenumbering="unnumbered">Contract.make {
label 'some_label'
input {
messageFrom value(consumer('jms:output'), producer('jms:input'))
messageBody([
bookName: 'foo'
])
messageHeaders {
header('sample', 'header')
}
}
outputMessage {
sentTo $(consumer('jms:input'), producer('jms:output'))
body([
bookName: 'foo'
])
}
}</programlisting>
</section>
<section xml:id="contract-dsl-common">
<title>Common</title>
<simpara>In the <literal>input</literal> or <literal>outputMessage</literal> section you can call <literal>assertThat</literal> with the name
of a <literal>method</literal> (e.g. <literal>assertThatMessageIsOnTheQueue()</literal>) that you have defined in the
base class or in a static import. Spring Cloud Contract will execute that method
in the generated test.</simpara>
</section>
</section>
<section xml:id="_multiple_contracts_in_one_file">
<title>Multiple Contracts in One File</title>
<simpara>You can define multiple contracts in one file. Such a contract might resemble the
following example:</simpara>
<formalpara>
<title>Groovy DSL</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">import org.springframework.cloud.contract.spec.Contract
[
Contract.make {
name("should post a user")
request {
method 'POST'
url('/users/1')
}
response {
status OK()
}
},
Contract.make {
request {
method 'POST'
url('/users/2')
}
response {
status OK()
}
}
]</programlisting>
</para>
</formalpara>
<formalpara>
<title>YAML</title>
<para>
<programlisting language="yml" linenumbering="unnumbered">---
name: should post a user
request:
method: POST
url: /users/1
response:
status: 200
---
request:
method: POST
url: /users/2
response:
status: 200</programlisting>
</para>
</formalpara>
<simpara>In the preceding example, one contract has the <literal>name</literal> field and the other does not. This
leads to generation of two tests that look more or less like this:</simpara>
<programlisting language="java" linenumbering="unnumbered">package org.springframework.cloud.contract.verifier.tests.com.hello;
import com.example.TestBase;
import com.jayway.jsonpath.DocumentContext;
import com.jayway.jsonpath.JsonPath;
import com.jayway.restassured.module.mockmvc.specification.MockMvcRequestSpecification;
import com.jayway.restassured.response.ResponseOptions;
import org.junit.Test;
import static com.jayway.restassured.module.mockmvc.RestAssuredMockMvc.*;
import static com.toomuchcoding.jsonassert.JsonAssertion.assertThatJson;
import static org.assertj.core.api.Assertions.assertThat;
public class V1Test extends TestBase {
@Test
public void validate_should_post_a_user() throws Exception {
// given:
MockMvcRequestSpecification request = given();
// when:
ResponseOptions response = given().spec(request)
.post("/users/1");
// then:
assertThat(response.statusCode()).isEqualTo(200);
}
@Test
public void validate_withList_1() throws Exception {
// given:
MockMvcRequestSpecification request = given();
// when:
ResponseOptions response = given().spec(request)
.post("/users/2");
// then:
assertThat(response.statusCode()).isEqualTo(200);
}
}</programlisting>
<simpara>Notice that, for the contract that has the <literal>name</literal> field, the generated test method is named
<literal>validate_should_post_a_user</literal>. For the one that does not have the name, it is called
<literal>validate_withList_1</literal>. It corresponds to the name of the file <literal>WithList.groovy</literal> and the
index of the contract in the list.</simpara>
<simpara>The generated stubs is shown in the following example:</simpara>
<screen>should post a user.json
1_WithList.json</screen>
<simpara>As you can see, the first file got the <literal>name</literal> parameter from the contract. The second
got the name of the contract file (<literal>WithList.groovy</literal>) prefixed with the index (in this
case, the contract had an index of <literal>1</literal> in the list of contracts in the file).</simpara>
<tip>
<simpara>As you can see, it is much better if you name your contracts because doing so makes
your tests far more meaningful.</simpara>
</tip>
</section>
<section xml:id="_generating_spring_rest_docs_snippets_from_the_contracts">
<title>Generating Spring REST Docs snippets from the contracts</title>
<simpara>When you want to include the requests and responses of your API using Spring REST Docs,
you only need to make some minor changes to your setup if you are using MockMvc and RestAssuredMockMvc.
Simply include the following dependencies if you haven&#8217;t already.</simpara>
<formalpara>
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-starter-contract-verifier&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.restdocs&lt;/groupId&gt;
&lt;artifactId&gt;spring-restdocs-mockmvc&lt;/artifactId&gt;
&lt;optional&gt;true&lt;/optional&gt;
&lt;/dependency&gt;</programlisting>
</para>
</formalpara>
<formalpara>
<title>Gradle</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">testCompile 'org.springframework.cloud:spring-cloud-starter-contract-verifier'
testCompile 'org.springframework.restdocs:spring-restdocs-mockmvc'</programlisting>
</para>
</formalpara>
<simpara>Next you need to make some changes to your base class like the following example.</simpara>
<programlisting language="java" linenumbering="unnumbered">package com.example.fraud;
import io.restassured.module.mockmvc.RestAssuredMockMvc;
import org.junit.Before;
import org.junit.Rule;
import org.junit.rules.TestName;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.restdocs.JUnitRestDocumentation;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
@RunWith(SpringRunner.class)
@SpringBootTest(classes = Application.class)
public abstract class FraudBaseWithWebAppSetup {
private static final String OUTPUT = "target/generated-snippets";
@Rule
public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(OUTPUT);
@Rule public TestName testName = new TestName();
@Autowired
private WebApplicationContext context;
@Before
public void setup() {
RestAssuredMockMvc.mockMvc(MockMvcBuilders.webAppContextSetup(this.context)
.apply(documentationConfiguration(this.restDocumentation))
.alwaysDo(document(getClass().getSimpleName() + "_" + testName.getMethodName()))
.build());
}
protected void assertThatRejectionReasonIsNull(Object rejectionReason) {
assert rejectionReason == null;
}
}
// end::base_class[]</programlisting>
<simpara>In case you are using the standalone setup, you can set up RestAssuredMockMvc like this:</simpara>
<programlisting language="java" linenumbering="unnumbered">package com.example.fraud;
import io.restassured.module.mockmvc.RestAssuredMockMvc;
import org.junit.Before;
import org.junit.Rule;
import org.junit.rules.TestName;
import org.springframework.restdocs.JUnitRestDocumentation;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
public abstract class FraudBaseWithStandaloneSetup {
private static final String OUTPUT = "target/generated-snippets";
@Rule
public JUnitRestDocumentation restDocumentation = new JUnitRestDocumentation(OUTPUT);
@Rule public TestName testName = new TestName();
@Before
public void setup() {
RestAssuredMockMvc.standaloneSetup(MockMvcBuilders.standaloneSetup(new FraudDetectionController())
.apply(documentationConfiguration(this.restDocumentation))
.alwaysDo(document(getClass().getSimpleName() + "_" + testName.getMethodName())));
}
}
// end::base_class[]</programlisting>
<tip>
<simpara>You don&#8217;t need to specify the output directory for the generated snippets since version 1.2.0.RELEASE of Spring REST Docs.</simpara>
</tip>
</section>
</chapter>
<chapter xml:id="_customization">
<title>Customization</title>
<important>
<simpara>This section is valid only for Groovy DSL</simpara>
</important>
<simpara>You can customize the Spring Cloud Contract Verifier by extending the DSL, as shown in
the remainder of this section.</simpara>
<section xml:id="_extending_the_dsl">
<title>Extending the DSL</title>
<simpara>You can provide your own functions to the DSL. The key requirement for this feature is to
maintain the static compatibility. Later in this document, you can see examples of:</simpara>
<itemizedlist>
<listitem>
<simpara>Creating a JAR with reusable classes.</simpara>
</listitem>
<listitem>
<simpara>Referencing of these classes in the DSLs.</simpara>
</listitem>
</itemizedlist>
<simpara>You can find the full example
<link xl:href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples">here</link>.</simpara>
<section xml:id="_common_jar">
<title>Common JAR</title>
<simpara>The following examples show three classes that can be reused in the DSLs.</simpara>
<simpara><emphasis role="strong">PatternUtils</emphasis> contains functions used by both the <emphasis role="strong">consumer</emphasis> and the <emphasis role="strong">producer</emphasis>.</simpara>
<programlisting language="java" linenumbering="unnumbered">package com.example;
import java.util.regex.Pattern;
/**
* If you want to use {@link Pattern} directly in your tests
* then you can create a class resembling this one. It can
* contain all the {@link Pattern} you want to use in the DSL.
*
* &lt;pre&gt;
* {@code
* request {
* body(
* [ age: $(c(PatternUtils.oldEnough()))]
* )
* }
* &lt;/pre&gt;
*
* Notice that we're using both {@code $()} for dynamic values
* and {@code c()} for the consumer side.
*
* @author Marcin Grzejszczak
*/
//tag::impl[]
public class PatternUtils {
public static String tooYoung() {
//remove::start[]
return "[0-1][0-9]";
//remove::end[return]
}
public static Pattern oldEnough() {
//remove::start[]
return Pattern.compile("[2-9][0-9]");
//remove::end[return]
}
/**
* Makes little sense but it's just an example ;)
*/
public static Pattern ok() {
//remove::start[]
return Pattern.compile("OK");
//remove::end[return]
}
}
//end::impl[]</programlisting>
<simpara><emphasis role="strong">ConsumerUtils</emphasis> contains functions used by the <emphasis role="strong">consumer</emphasis>.</simpara>
<programlisting language="java" linenumbering="unnumbered">package com.example;
import org.springframework.cloud.contract.spec.internal.ClientDslProperty;
/**
* DSL Properties passed to the DSL from the consumer's perspective.
* That means that on the input side {@code Request} for HTTP
* or {@code Input} for messaging you can have a regular expression.
* On the {@code Response} for HTTP or {@code Output} for messaging
* you have to have a concrete value.
*
* @author Marcin Grzejszczak
*/
//tag::impl[]
public class ConsumerUtils {
/**
* Consumer side property. By using the {@link ClientDslProperty}
* you can omit most of boilerplate code from the perspective
* of dynamic values. Example
*
* &lt;pre&gt;
* {@code
* request {
* body(
* [ age: $(ConsumerUtils.oldEnough())]
* )
* }
* &lt;/pre&gt;
*
* That way it's in the implementation that we decide what value we will pass to the consumer
* and which one to the producer.
*
* @author Marcin Grzejszczak
*/
public static ClientDslProperty oldEnough() {
//remove::start[]
// this example is not the best one and
// theoretically you could just pass the regex instead of `ServerDslProperty` but
// it's just to show some new tricks :)
return new ClientDslProperty(PatternUtils.oldEnough(), 40);
//remove::end[return]
}
}
//end::impl[]</programlisting>
<simpara><emphasis role="strong">ProducerUtils</emphasis> contains functions used by the <emphasis role="strong">producer</emphasis>.</simpara>
<programlisting language="java" linenumbering="unnumbered">package com.example;
import org.springframework.cloud.contract.spec.internal.ServerDslProperty;
/**
* DSL Properties passed to the DSL from the producer's perspective.
* That means that on the input side {@code Request} for HTTP
* or {@code Input} for messaging you have to have a concrete value.
* On the {@code Response} for HTTP or {@code Output} for messaging
* you can have a regular expression.
*
* @author Marcin Grzejszczak
*/
//tag::impl[]
public class ProducerUtils {
/**
* Producer side property. By using the {@link ProducerUtils}
* you can omit most of boilerplate code from the perspective
* of dynamic values. Example
*
* &lt;pre&gt;
* {@code
* response {
* body(
* [ status: $(ProducerUtils.ok())]
* )
* }
* &lt;/pre&gt;
*
* That way it's in the implementation that we decide what value we will pass to the consumer
* and which one to the producer.
*/
public static ServerDslProperty ok() {
// this example is not the best one and
// theoretically you could just pass the regex instead of `ServerDslProperty` but
// it's just to show some new tricks :)
return new ServerDslProperty( PatternUtils.ok(), "OK");
}
}
//end::impl[]</programlisting>
</section>
<section xml:id="_adding_the_dependency_to_the_project">
<title>Adding the Dependency to the Project</title>
<simpara>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.</simpara>
</section>
<section xml:id="_test_the_dependency_in_the_projects_dependencies">
<title>Test the Dependency in the Project&#8217;s Dependencies</title>
<simpara>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:</simpara>
<formalpara role="primary">
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependency&gt;
&lt;groupId&gt;com.example&lt;/groupId&gt;
&lt;artifactId&gt;beer-common&lt;/artifactId&gt;
&lt;version&gt;${project.version}&lt;/version&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;</programlisting>
</para>
</formalpara>
<formalpara role="secondary">
<title>Gradle</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">testCompile("com.example:beer-common:0.0.1-SNAPSHOT")</programlisting>
</para>
</formalpara>
</section>
<section xml:id="_test_a_dependency_in_the_plugins_dependencies">
<title>Test a Dependency in the Plugin&#8217;s Dependencies</title>
<simpara>Now, you must add the dependency for the plugin to reuse at runtime, as shown in the
following example:</simpara>
<formalpara role="primary">
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;configuration&gt;
&lt;packageWithBaseClasses&gt;com.example&lt;/packageWithBaseClasses&gt;
&lt;baseClassMappings&gt;
&lt;baseClassMapping&gt;
&lt;contractPackageRegex&gt;.*intoxication.*&lt;/contractPackageRegex&gt;
&lt;baseClassFQN&gt;com.example.intoxication.BeerIntoxicationBase&lt;/baseClassFQN&gt;
&lt;/baseClassMapping&gt;
&lt;/baseClassMappings&gt;
&lt;/configuration&gt;
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;com.example&lt;/groupId&gt;
&lt;artifactId&gt;beer-common&lt;/artifactId&gt;
&lt;version&gt;${project.version}&lt;/version&gt;
&lt;scope&gt;compile&lt;/scope&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;/plugin&gt;</programlisting>
</para>
</formalpara>
<formalpara role="secondary">
<title>Gradle</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">classpath "com.example:beer-common:0.0.1-SNAPSHOT"</programlisting>
</para>
</formalpara>
</section>
<section xml:id="_referencing_classes_in_dsls">
<title>Referencing classes in DSLs</title>
<simpara>You can now reference your classes in your DSL, as shown in the following example:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">package contracts.beer.rest
import com.example.ConsumerUtils
import com.example.ProducerUtils
import org.springframework.cloud.contract.spec.Contract
Contract.make {
description("""
Represents a successful scenario of getting a beer
```
given:
client is old enough
when:
he applies for a beer
then:
we'll grant him the beer
```
""")
request {
method 'POST'
url '/check'
body(
age: $(ConsumerUtils.oldEnough())
)
headers {
contentType(applicationJson())
}
}
response {
status 200
body("""
{
"status": "${value(ProducerUtils.ok())}"
}
""")
headers {
contentType(applicationJson())
}
}
}</programlisting>
</section>
</section>
</chapter>
<chapter xml:id="_using_the_pluggable_architecture">
<title>Using the Pluggable Architecture</title>
<simpara>You may encounter cases where you have your contracts have been defined in other formats,
such as YAML, RAML or PACT. In those cases, you still want to benefit from the automatic
generation of tests and stubs. You can add your own implementation for generating both
tests and stubs. Also, you can customize the way tests are generated (for example, you
can generate tests for other languages) and the way stubs are generated (for example, you
can generate stubs for other HTTP server implementations).</simpara>
<section xml:id="_custom_contract_converter">
<title>Custom Contract Converter</title>
<simpara>The <literal>ContractConverter</literal> interface lets you register your own implementation of a contract
structure converter. The following code listing shows the <literal>ContractConverter</literal> interface:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">package org.springframework.cloud.contract.spec
/**
* Converter to be used to convert FROM {@link File} TO {@link Contract}
* and from {@link Contract} to {@code T}
*
* @param &lt;T&gt; - type to which we want to convert the contract
*
* @author Marcin Grzejszczak
* @since 1.1.0
*/
interface ContractConverter&lt;T&gt; extends ContractStorer&lt;T&gt; {
/**
* Should this file be accepted by the converter. Can use the file extension
* to check if the conversion is possible.
*
* @param file - file to be considered for conversion
* @return - {@code true} if the given implementation can convert the file
*/
boolean isAccepted(File file)
/**
* Converts the given {@link File} to its {@link Contract} representation
*
* @param file - file to convert
* @return - {@link Contract} representation of the file
*/
Collection&lt;Contract&gt; convertFrom(File file)
/**
* Converts the given {@link Contract} to a {@link T} representation
*
* @param contract - the parsed contract
* @return - {@link T} the type to which we do the conversion
*/
T convertTo(Collection&lt;Contract&gt; contract)
}</programlisting>
<simpara>Your implementation must define the condition on which it should start the
conversion. Also, you must define how to perform that conversion in both directions.</simpara>
<important>
<simpara>Once you create your implementation, you must create a
<literal>/META-INF/spring.factories</literal> file in which you provide the fully qualified name of your
implementation.</simpara>
</important>
<simpara>The following example shows a typical <literal>spring.factories</literal> file:</simpara>
<screen>org.springframework.cloud.contract.spec.ContractConverter=\
org.springframework.cloud.contract.verifier.converter.YamlContractConverter</screen>
<section xml:id="pact-converter">
<title>Pact Converter</title>
<simpara>Spring Cloud Contract includes support for <link xl:href="https://docs.pact.io/">Pact</link> 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.</simpara>
</section>
<section xml:id="_pact_contract">
<title>Pact Contract</title>
<simpara>Consider following example of a Pact contract, which is a file under the
<literal>src/test/resources/contracts</literal> folder.</simpara>
<programlisting language="javascript" linenumbering="unnumbered">{
"provider": {
"name": "Provider"
},
"consumer": {
"name": "Consumer"
},
"interactions": [
{
"description": "",
"request": {
"method": "PUT",
"path": "/fraudcheck",
"headers": {
"Content-Type": "application/vnd.fraud.v1+json"
},
"body": {
"clientId": "1234567890",
"loanAmount": 99999
},
"generators": {
"body": {
"$.clientId": {
"type": "Regex",
"regex": "[0-9]{10}"
}
}
},
"matchingRules": {
"header": {
"Content-Type": {
"matchers": [
{
"match": "regex",
"regex": "application/vnd\\.fraud\\.v1\\+json.*"
}
],
"combine": "AND"
}
},
"body" : {
"$.clientId": {
"matchers": [
{
"match": "regex",
"regex": "[0-9]{10}"
}
],
"combine": "AND"
}
}
}
},
"response": {
"status": 200,
"headers": {
"Content-Type": "application/vnd.fraud.v1+json;charset=UTF-8"
},
"body": {
"fraudCheckStatus": "FRAUD",
"rejectionReason": "Amount too high"
},
"matchingRules": {
"header": {
"Content-Type": {
"matchers": [
{
"match": "regex",
"regex": "application/vnd\\.fraud\\.v1\\+json.*"
}
],
"combine": "AND"
}
},
"body": {
"$.fraudCheckStatus": {
"matchers": [
{
"match": "regex",
"regex": "FRAUD"
}
],
"combine": "AND"
}
}
}
}
}
],
"metadata": {
"pact-specification": {
"version": "3.0.0"
},
"pact-jvm": {
"version": "3.5.13"
}
}
}</programlisting>
<simpara>The remainder of this section about using Pact refers to the preceding file.</simpara>
</section>
<section xml:id="_pact_for_producers">
<title>Pact for Producers</title>
<simpara>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.</simpara>
<formalpara role="primary">
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;plugin&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-maven-plugin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;extensions&gt;true&lt;/extensions&gt;
&lt;configuration&gt;
&lt;packageWithBaseClasses&gt;com.example.fraud&lt;/packageWithBaseClasses&gt;
&lt;/configuration&gt;
&lt;dependencies&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-pact&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;/plugin&gt;</programlisting>
</para>
</formalpara>
<formalpara role="secondary">
<title>Gradle</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">classpath "org.springframework.cloud:spring-cloud-contract-pact:${findProperty('verifierVersion') ?: verifierVersion}"</programlisting>
</para>
</formalpara>
<simpara>When you execute the build of your application, a test will be generated. The generated
test might be as follows:</simpara>
<programlisting language="java" linenumbering="unnumbered">@Test
public void validate_shouldMarkClientAsFraud() throws Exception {
// given:
MockMvcRequestSpecification request = given()
.header("Content-Type", "application/vnd.fraud.v1+json")
.body("{\"clientId\":\"1234567890\",\"loanAmount\":99999}");
// when:
ResponseOptions response = given().spec(request)
.put("/fraudcheck");
// then:
assertThat(response.statusCode()).isEqualTo(200);
assertThat(response.header("Content-Type")).matches("application/vnd\\.fraud\\.v1\\+json.*");
// and:
DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
assertThatJson(parsedJson).field("['rejectionReason']").isEqualTo("Amount too high");
// and:
assertThat(parsedJson.read("$.fraudCheckStatus", String.class)).matches("FRAUD");
}</programlisting>
<simpara>The corresponding generated stub might be as follows:</simpara>
<programlisting language="javascript" linenumbering="unnumbered">{
"id" : "996ae5ae-6834-4db6-8fac-358ca187ab62",
"uuid" : "996ae5ae-6834-4db6-8fac-358ca187ab62",
"request" : {
"url" : "/fraudcheck",
"method" : "PUT",
"headers" : {
"Content-Type" : {
"matches" : "application/vnd\\.fraud\\.v1\\+json.*"
}
},
"bodyPatterns" : [ {
"matchesJsonPath" : "$[?(@.['loanAmount'] == 99999)]"
}, {
"matchesJsonPath" : "$[?(@.clientId =~ /([0-9]{10})/)]"
} ]
},
"response" : {
"status" : 200,
"body" : "{\"fraudCheckStatus\":\"FRAUD\",\"rejectionReason\":\"Amount too high\"}",
"headers" : {
"Content-Type" : "application/vnd.fraud.v1+json;charset=UTF-8"
},
"transformers" : [ "response-template" ]
},
}</programlisting>
</section>
<section xml:id="_pact_for_consumers">
<title>Pact for Consumers</title>
<simpara>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.</simpara>
<formalpara role="primary">
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-pact&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;</programlisting>
</para>
</formalpara>
<formalpara role="secondary">
<title>Gradle</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">testCompile "org.springframework.cloud:spring-cloud-contract-pact"</programlisting>
</para>
</formalpara>
</section>
</section>
<section xml:id="_using_the_custom_test_generator">
<title>Using the Custom Test Generator</title>
<simpara>If you want to generate tests for languages other than Java or you are not happy with the
way the verifier builds Java tests, you can register your own implementation.</simpara>
<simpara>The <literal>SingleTestGenerator</literal> interface lets you register your own implementation. The
following code listing shows the <literal>SingleTestGenerator</literal> interface:</simpara>
<programlisting language="groovy" linenumbering="unnumbered"> *
* @param properties - properties passed to the plugin
* @param listOfFiles - list of parsed contracts with additional metadata
* @param className - the name of the generated test class
* @param classPackage - the name of the package in which the test class should be stored
* @param includedDirectoryRelativePath - relative path to the included directory
* @return contents of a single test class
* @deprecated use {@link SingleTestGenerator#buildClass(ContractVerifierConfigProperties, Collection, String, GeneratedClassData)}
*/
@Deprecated
abstract String buildClass(ContractVerifierConfigProperties properties,
Collection&lt;ContractMetadata&gt; listOfFiles, String className, String classPackage, String includedDirectoryRelativePath)
/**
* Creates contents of a single test class in which all test scenarios from
* the contract metadata should be placed.
*
* @param properties - properties passed to the plugin
* @param listOfFiles - list of parsed contracts with additional metadata
* @param generatedClassData - information about the generated class
* @param includedDirectoryRelativePath - relative path to the included directory
* @return contents of a single test class
*/
String buildClass(ContractVerifierConfigProperties properties,
Collection&lt;ContractMetadata&gt; listOfFiles, String includedDirectoryRelativePath, GeneratedClassData generatedClassData) {
return buildClass(properties, listOfFiles, generatedClassData.className, generatedClassData.classPackage, includedDirectoryRelativePath)
}
/**
* Extension that should be appended to the generated test class. E.g. {@code .java} or {@code .php}
*
* @param properties - properties passed to the plugin
*/
abstract String fileExtension(ContractVerifierConfigProperties properties)
static class GeneratedClassData {
public final String className
public final String classPackage
public final java.nio.file.Path testClassPath
GeneratedClassData(String className, String classPackage,
java.nio.file.Path testClassPath) {
this.className = className
this.classPackage = classPackage
this.testClassPath = testClassPath
}
}
}</programlisting>
<simpara>Again, you must provide a <literal>spring.factories</literal> file, such as the one shown in the following
example:</simpara>
<screen>org.springframework.cloud.contract.verifier.builder.SingleTestGenerator=/
com.example.MyGenerator</screen>
</section>
<section xml:id="_using_the_custom_stub_generator">
<title>Using the Custom Stub Generator</title>
<simpara>If you want to generate stubs for stub servers other than WireMock, you can plug in your
own implementation of the <literal>StubGenerator</literal> interface. The following code listing shows the
<literal>StubGenerator</literal> interface:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">package org.springframework.cloud.contract.verifier.converter
import groovy.transform.CompileStatic
import org.springframework.cloud.contract.spec.Contract
import org.springframework.cloud.contract.verifier.file.ContractMetadata
/**
* Converts contracts into their stub representation.
*
* @since 1.1.0
*/
@CompileStatic
interface StubGenerator {
/**
* Returns {@code true} if the converter can handle the file to convert it into a stub.
*/
boolean canHandleFileName(String fileName)
/**
* Returns the collection of converted contracts into stubs. One contract can
* result in multiple stubs.
*/
Map&lt;Contract, String&gt; convertContents(String rootName, ContractMetadata content)
/**
* Returns the name of the converted stub file. If you have multiple contracts
* in a single file then a prefix will be added to the generated file. If you
* provide the {@link Contract#name} field then that field will override the
* generated file name.
*
* Example: name of file with 2 contracts is {@code foo.groovy}, it will be
* converted by the implementation to {@code foo.json}. The recursive file
* converter will create two files {@code 0_foo.json} and {@code 1_foo.json}
*/
String generateOutputFileNameForInput(String inputFileName)
}</programlisting>
<simpara>Again, you must provide a <literal>spring.factories</literal> file, such as the one shown in the following
example:</simpara>
<screen># Stub converters
org.springframework.cloud.contract.verifier.converter.StubGenerator=\
org.springframework.cloud.contract.verifier.wiremock.DslToWireMockClientConverter</screen>
<simpara>The default implementation is the WireMock stub generation.</simpara>
<tip>
<simpara>You can provide multiple stub generator implementations. For example, from a single
DSL, you can produce both WireMock stubs and Pact files.</simpara>
</tip>
</section>
<section xml:id="_using_the_custom_stub_runner">
<title>Using the Custom Stub Runner</title>
<simpara>If you decide to use a custom stub generation, you also need a custom way of running
stubs with your different stub provider.</simpara>
<simpara>Assume that you use <link xl:href="https://github.com/dreamhead/moco">Moco</link> to build your stubs and that
you have written a stub generator and placed your stubs in a JAR file.</simpara>
<simpara>In order for Stub Runner to know how to run your stubs, you have to define a custom
HTTP Stub server implementation, which might resemble the following example:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">package org.springframework.cloud.contract.stubrunner.provider.moco
import com.github.dreamhead.moco.bootstrap.arg.HttpArgs
import com.github.dreamhead.moco.runner.JsonRunner
import com.github.dreamhead.moco.runner.RunnerSetting
import groovy.util.logging.Commons
import org.springframework.cloud.contract.stubrunner.HttpServerStub
import org.springframework.util.SocketUtils
@Commons
class MocoHttpServerStub implements HttpServerStub {
private boolean started
private JsonRunner runner
private int port
@Override
int port() {
if (!isRunning()) {
return -1
}
return port
}
@Override
boolean isRunning() {
return started
}
@Override
HttpServerStub start() {
return start(SocketUtils.findAvailableTcpPort())
}
@Override
HttpServerStub start(int port) {
this.port = port
return this
}
@Override
HttpServerStub stop() {
if (!isRunning()) {
return this
}
this.runner.stop()
return this
}
@Override
HttpServerStub registerMappings(Collection&lt;File&gt; stubFiles) {
List&lt;RunnerSetting&gt; settings = stubFiles.findAll { it.name.endsWith("json") }
.collect {
log.info("Trying to parse [${it.name}]")
try {
return RunnerSetting.aRunnerSetting().withStream(it.newInputStream()).build()
} catch (Exception e) {
log.warn("Exception occurred while trying to parse file [${it.name}]", e)
return null
}
}.findAll { it }
this.runner = JsonRunner.newJsonRunnerWithSetting(settings,
HttpArgs.httpArgs().withPort(this.port).build())
this.runner.run()
this.started = true
return this
}
@Override
String registeredMappings() {
return ""
}
@Override
boolean isAccepted(File file) {
return file.name.endsWith(".json")
}
}</programlisting>
<simpara>Then, you can register it in your <literal>spring.factories</literal> file, as shown in the following
example:</simpara>
<screen>org.springframework.cloud.contract.stubrunner.HttpServerStub=\
org.springframework.cloud.contract.stubrunner.provider.moco.MocoHttpServerStub</screen>
<simpara>Now you can run stubs with Moco.</simpara>
<important>
<simpara>If you do not provide any implementation, then the default (WireMock)
implementation is used. If you provide more than one, the first one on the list is used.</simpara>
</important>
</section>
<section xml:id="_using_the_custom_stub_downloader">
<title>Using the Custom Stub Downloader</title>
<simpara>You can customize the way your stubs are downloaded by creating an implementation of the
<literal>StubDownloaderBuilder</literal> interface, as shown in the following example:</simpara>
<programlisting language="java" linenumbering="unnumbered">package com.example;
class CustomStubDownloaderBuilder implements StubDownloaderBuilder {
@Override
public StubDownloader build(final StubRunnerOptions stubRunnerOptions) {
return new StubDownloader() {
@Override
public Map.Entry&lt;StubConfiguration, File&gt; downloadAndUnpackStubJar(
StubConfiguration config) {
File unpackedStubs = retrieveStubs();
return new AbstractMap.SimpleEntry&lt;&gt;(
new StubConfiguration(config.getGroupId(), config.getArtifactId(), version,
config.getClassifier()), unpackedStubs);
}
File retrieveStubs() {
// here goes your custom logic to provide a folder where all the stubs reside
}
}</programlisting>
<simpara>Then you can register it in your <literal>spring.factories</literal> file, as shown in the following
example:</simpara>
<screen># Example of a custom Stub Downloader Provider
org.springframework.cloud.contract.stubrunner.StubDownloaderBuilder=\
com.example.CustomStubDownloaderBuilder</screen>
<simpara>Now you can pick a folder with the source of your stubs.</simpara>
<important>
<simpara>If you do not provide any implementation, then the default is used (scan classpath).
If you provide the <literal>stubsMode = StubRunnerProperties.StubsMode.LOCAL</literal> or
<literal>, stubsMode = StubRunnerProperties.StubsMode.REMOTE</literal> then the Aether implementation will be used
If you provide more than one, then the first one on the list is used.</simpara>
</important>
</section>
<section xml:id="scm-stub-downloader">
<title>Using the SCM Stub Downloader</title>
<simpara>Whenever the <literal>repositoryRoot</literal> starts with a SCM protocol
(currently we support only <literal>git://</literal>), the stub downloader will try
to clone the repository and use it as a source of contracts
to generate tests or stubs.</simpara>
<simpara>Either via environment variables, system properties, properties set
inside the plugin or contracts repository configuration you can
tweak the downloader&#8217;s behaviour. Below you can find the list of
properties</simpara>
<table frame="all" rowsep="1" colsep="1">
<title>SCM Stub Downloader properties</title>
<tgroup cols="3">
<colspec colname="col_1" colwidth="33.3333*"/>
<colspec colname="col_2" colwidth="33.3333*"/>
<colspec colname="col_3" colwidth="33.3334*"/>
<tbody>
<row>
<entry align="left" valign="top"><simpara>Type of a property</simpara></entry>
<entry align="left" valign="top"><simpara>Name of the property</simpara></entry>
<entry align="left" valign="top"><simpara>Description</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>* <literal>git.branch</literal> (plugin prop)</simpara><simpara>* <literal>stubrunner.properties.git.branch</literal> (system prop)</simpara><simpara>* <literal>STUBRUNNER_PROPERTIES_GIT_BRANCH</literal> (env prop)</simpara></entry>
<entry align="left" valign="top"><simpara>master</simpara></entry>
<entry align="left" valign="top"><simpara>Which branch to checkout</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>* <literal>git.username</literal> (plugin prop)</simpara><simpara>* <literal>stubrunner.properties.git.username</literal> (system prop)</simpara><simpara>* <literal>STUBRUNNER_PROPERTIES_GIT_USERNAME</literal> (env prop)</simpara></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><simpara>Git clone username</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>* <literal>git.password</literal> (plugin prop)</simpara><simpara>* <literal>stubrunner.properties.git.password</literal> (system prop)</simpara><simpara>* <literal>STUBRUNNER_PROPERTIES_GIT_PASSWORD</literal> (env prop)</simpara></entry>
<entry align="left" valign="top"></entry>
<entry align="left" valign="top"><simpara>Git clone password</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>* <literal>git.no-of-attempts</literal> (plugin prop)</simpara><simpara>* <literal>stubrunner.properties.git.no-of-attempts</literal> (system prop)</simpara><simpara>* <literal>STUBRUNNER_PROPERTIES_GIT_NO_OF_ATTEMPTS</literal> (env prop)</simpara></entry>
<entry align="left" valign="top"><simpara>10</simpara></entry>
<entry align="left" valign="top"><simpara>Number of attempts to push the commits to <literal>origin</literal></simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>* <literal>git.wait-between-attempts</literal> (Plugin prop)</simpara><simpara>* <literal>stubrunner.properties.git.wait-between-attempts</literal> (system prop)</simpara><simpara>* <literal>STUBRUNNER_PROPERTIES_GIT_WAIT_BETWEEN_ATTEMPTS</literal> (env prop)</simpara></entry>
<entry align="left" valign="top"><simpara>1000</simpara></entry>
<entry align="left" valign="top"><simpara>Number of millis to wait between attempts to push the commits to <literal>origin</literal></simpara></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="pact-stub-downloader">
<title>Using the Pact Stub Downloader</title>
<simpara>Whenever the <literal>repositoryRoot</literal> starts with a Pact protocol
(starts with <literal>pact://</literal>), the stub downloader will try
to fetch the Pact contract definitions from the Pact Broker.
Whatever is set after <literal>pact://</literal> will be parsed as the Pact Broker URL.</simpara>
<simpara>Either via environment variables, system properties, properties set
inside the plugin or contracts repository configuration you can
tweak the downloader&#8217;s behaviour. Below you can find the list of
properties</simpara>
<table frame="all" rowsep="1" colsep="1">
<title>SCM Stub Downloader properties</title>
<tgroup cols="3">
<colspec colname="col_1" colwidth="33.3333*"/>
<colspec colname="col_2" colwidth="33.3333*"/>
<colspec colname="col_3" colwidth="33.3334*"/>
<tbody>
<row>
<entry align="left" valign="top"><simpara>Name of a property</simpara></entry>
<entry align="left" valign="top"><simpara>Default</simpara></entry>
<entry align="left" valign="top"><simpara>Description</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>* <literal>pactbroker.host</literal> (plugin prop)</simpara><simpara>* <literal>stubrunner.properties.pactbroker.host</literal> (system prop)</simpara><simpara>* <literal>STUBRUNNER_PROPERTIES_PACTBROKER_HOST</literal> (env prop)</simpara></entry>
<entry align="left" valign="top"><simpara>Host from URL passed to <literal>repositoryRoot</literal></simpara></entry>
<entry align="left" valign="top"><simpara>What is the URL of Pact Broker</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>* <literal>pactbroker.port</literal> (plugin prop)</simpara><simpara>* <literal>stubrunner.properties.pactbroker.port</literal> (system prop)</simpara><simpara>* <literal>STUBRUNNER_PROPERTIES_PACTBROKER_PORT</literal> (env prop)</simpara></entry>
<entry align="left" valign="top"><simpara>Port from URL passed to <literal>repositoryRoot</literal></simpara></entry>
<entry align="left" valign="top"><simpara>What is the port of Pact Broker</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>* <literal>pactbroker.protocol</literal> (plugin prop)</simpara><simpara>* <literal>stubrunner.properties.pactbroker.protocol</literal> (system prop)</simpara><simpara>* <literal>STUBRUNNER_PROPERTIES_PACTBROKER_PROTOCOL</literal> (env prop)</simpara></entry>
<entry align="left" valign="top"><simpara>Protocol from URL passed to <literal>repositoryRoot</literal></simpara></entry>
<entry align="left" valign="top"><simpara>What is the protocol of Pact Broker</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>* <literal>pactbroker.tags</literal> (plugin prop)</simpara><simpara>* <literal>stubrunner.properties.pactbroker.tags</literal> (system prop)</simpara><simpara>* <literal>STUBRUNNER_PROPERTIES_PACTBROKER_TAGS</literal> (env prop)</simpara></entry>
<entry align="left" valign="top"><simpara>Version of the stub, or <literal>latest</literal> if version is <literal>+</literal></simpara></entry>
<entry align="left" valign="top"><simpara>What tags should be used to fetch the stub</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>* <literal>pactbroker.auth.scheme</literal> (plugin prop)</simpara><simpara>* <literal>stubrunner.properties.pactbroker.auth.scheme</literal> (system prop)</simpara><simpara>* <literal>STUBRUNNER_PROPERTIES_PACTBROKER_AUTH_SCHEME</literal> (env prop)</simpara></entry>
<entry align="left" valign="top"><simpara><literal>Basic</literal></simpara></entry>
<entry align="left" valign="top"><simpara>What kind of authentication should be used to connect to the Pact Broker</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>* <literal>pactbroker.auth.username</literal> (plugin prop)</simpara><simpara>* <literal>stubrunner.properties.pactbroker.auth.username</literal> (system prop)</simpara><simpara>* <literal>STUBRUNNER_PROPERTIES_PACTBROKER_AUTH_USERNAME</literal> (env prop)</simpara></entry>
<entry align="left" valign="top"><simpara>The username passed to <literal>contractsRepositoryUsername</literal> (maven) or <literal>contractRepository.username</literal> (gradle)</simpara></entry>
<entry align="left" valign="top"><simpara>Username used to connect to the Pact Broker</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>* <literal>pactbroker.auth.password</literal> (plugin prop)</simpara><simpara>* <literal>stubrunner.properties.pactbroker.auth.password</literal> (system prop)</simpara><simpara>* <literal>STUBRUNNER_PROPERTIES_PACTBROKER_AUTH_PASSWORD</literal> (env prop)</simpara></entry>
<entry align="left" valign="top"><simpara>The password passed to <literal>contractsRepositoryPassword</literal> (maven) or <literal>contractRepository.password</literal> (gradle)</simpara></entry>
<entry align="left" valign="top"><simpara>Password used to connect to the Pact Broker</simpara></entry>
</row>
<row>
<entry align="left" valign="top"><simpara>* <literal>pactbroker.provider-name-with-group-id</literal> (plugin prop)</simpara><simpara>* <literal>stubrunner.properties.pactbroker.provider-name-with-group-id</literal> (system prop)</simpara><simpara>* <literal>STUBRUNNER_PROPERTIES_PACTBROKER_PROVIDER_NAME_WITH_GROUP_ID</literal> (env prop)</simpara></entry>
<entry align="left" valign="top"><simpara>false</simpara></entry>
<entry align="left" valign="top"><simpara>When <literal>true</literal>, the provider name will be a combination of <literal>groupId:artifactId</literal>. If <literal>false</literal>, just <literal>artifactId</literal> is used</simpara></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</chapter>
<chapter xml:id="_spring_cloud_contract_wiremock">
<title>Spring Cloud Contract WireMock</title>
<simpara>The Spring Cloud Contract WireMock modules let you use <link xl:href="http://wiremock.org">WireMock</link> in a
Spring Boot application. Check out the
<link xl:href="https://github.com/spring-cloud/spring-cloud-contract/tree/master/samples">samples</link>
for more details.</simpara>
<simpara>If you have a Spring Boot application that uses Tomcat as an embedded server (which is
the default with <literal>spring-boot-starter-web</literal>), you can add
<literal>spring-cloud-starter-contract-stub-runner</literal> to your classpath and add <literal>@AutoConfigureWireMock</literal> in
order to be able to use Wiremock in your tests. Wiremock runs as a stub server and you
can register stub behavior using a Java API or via static JSON declarations as part of
your test. The following code shows an example:</simpara>
<programlisting language="java" linenumbering="unnumbered">@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@AutoConfigureWireMock(port = 0)
public class WiremockForDocsTests {
// A service that calls out over HTTP
@Autowired
private Service service;
// Using the WireMock APIs in the normal way:
@Test
public void contextLoads() throws Exception {
// Stubbing WireMock
stubFor(get(urlEqualTo("/resource")).willReturn(aResponse()
.withHeader("Content-Type", "text/plain").withBody("Hello World!")));
// We're asserting if WireMock responded properly
assertThat(this.service.go()).isEqualTo("Hello World!");
}
}
// end::wiremock_test2[]</programlisting>
<simpara>To start the stub server on a different port use (for example),
<literal>@AutoConfigureWireMock(port=9999)</literal>. For a random port, use a value of <literal>0</literal>. The stub
server port can be bound in the test application context with the "wiremock.server.port"
property. Using <literal>@AutoConfigureWireMock</literal> adds a bean of type <literal>WiremockConfiguration</literal> to
your test application context, where it will be cached in between methods and classes
having the same context, the same as for Spring integration tests. Also you can inject a bean of type <literal>WireMockServer</literal> into your test.</simpara>
<section xml:id="_registering_stubs_automatically">
<title>Registering Stubs Automatically</title>
<simpara>If you use <literal>@AutoConfigureWireMock</literal>, it registers WireMock JSON stubs from the file
system or classpath (by default, from <literal>file:src/test/resources/mappings</literal>). You can
customize the locations using the <literal>stubs</literal> attribute in the annotation, which can be an
Ant-style resource pattern or a directory. In the case of a directory, <literal><emphasis role="strong">*/</emphasis>.json</literal> is
appended. The following code shows an example:</simpara>
<screen>@RunWith(SpringRunner.class)
@SpringBootTest
@AutoConfigureWireMock(stubs="classpath:/stubs")
public class WiremockImportApplicationTests {
@Autowired
private Service service;
@Test
public void contextLoads() throws Exception {
assertThat(this.service.go()).isEqualTo("Hello World!");
}
}</screen>
<note>
<simpara>Actually, WireMock always loads mappings from <literal>src/test/resources/mappings</literal> <emphasis role="strong">as
well as</emphasis> the custom locations in the stubs attribute. To change this behavior, you can
also specify a files root as described in the next section of this document.</simpara>
</note>
</section>
<section xml:id="_using_files_to_specify_the_stub_bodies">
<title>Using Files to Specify the Stub Bodies</title>
<simpara>WireMock can read response bodies from files on the classpath or the file system. In that
case, you can see in the JSON DSL that the response has a <literal>bodyFileName</literal> instead of a
(literal) <literal>body</literal>. The files are resolved relative to a root directory (by default,
<literal>src/test/resources/__files</literal>). To customize this location you can set the <literal>files</literal>
attribute in the <literal>@AutoConfigureWireMock</literal> annotation to the location of the parent
directory (in other words, <literal>__files</literal> is a subdirectory). You can use Spring resource
notation to refer to <literal>file:&#8230;&#8203;</literal> or <literal>classpath:&#8230;&#8203;</literal> locations. Generic URLs are not
supported. A list of values can be given, in which case WireMock resolves the first file
that exists when it needs to find a response body.</simpara>
<note>
<simpara>When you configure the <literal>files</literal> root, it also affects the
automatic loading of stubs, because they come from the root location
in a subdirectory called "mappings". The value of <literal>files</literal> has no
effect on the stubs loaded explicitly from the <literal>stubs</literal> attribute.</simpara>
</note>
</section>
<section xml:id="_alternative_using_junit_rules">
<title>Alternative: Using JUnit Rules</title>
<simpara>For a more conventional WireMock experience, you can use JUnit <literal>@Rules</literal> to start and stop
the server. To do so, use the <literal>WireMockSpring</literal> convenience class to obtain an <literal>Options</literal>
instance, as shown in the following example:</simpara>
<programlisting language="java" linenumbering="unnumbered">@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
public class WiremockForDocsClassRuleTests {
// Start WireMock on some dynamic port
// for some reason `dynamicPort()` is not working properly
@ClassRule
public static WireMockClassRule wiremock = new WireMockClassRule(
WireMockSpring.options().dynamicPort());
// A service that calls out over HTTP to localhost:${wiremock.port}
@Autowired
private Service service;
// Using the WireMock APIs in the normal way:
@Test
public void contextLoads() throws Exception {
// Stubbing WireMock
wiremock.stubFor(get(urlEqualTo("/resource")).willReturn(aResponse()
.withHeader("Content-Type", "text/plain").withBody("Hello World!")));
// We're asserting if WireMock responded properly
assertThat(this.service.go()).isEqualTo("Hello World!");
}
}
// end::wiremock_test2[]</programlisting>
<simpara>The <literal>@ClassRule</literal> means that the server shuts down after all the methods in this class
have been run.</simpara>
</section>
<section xml:id="_relaxed_ssl_validation_for_rest_template">
<title>Relaxed SSL Validation for Rest Template</title>
<simpara>WireMock lets you stub a "secure" server with an "https" URL protocol. If your
application wants to contact that stub server in an integration test, it will find that
the SSL certificates are not valid (the usual problem with self-installed certificates).
The best option is often to re-configure the client to use "http". If that&#8217;s not an
option, you can ask Spring to configure an HTTP client that ignores SSL validation errors
(do so only for tests, of course).</simpara>
<simpara>To make this work with minimum fuss, you need to be using the Spring Boot
<literal>RestTemplateBuilder</literal> in your app, as shown in the following example:</simpara>
<programlisting language="java" linenumbering="unnumbered">@Bean
public RestTemplate restTemplate(RestTemplateBuilder builder) {
return builder.build();
}</programlisting>
<simpara>You need <literal>RestTemplateBuilder</literal> because the builder is passed through callbacks to
initialize it, so the SSL validation can be set up in the client at that point. This
happens automatically in your test if you are using the <literal>@AutoConfigureWireMock</literal>
annotation or the stub runner. If you use the JUnit <literal>@Rule</literal> approach, you need to add the
<literal>@AutoConfigureHttpClient</literal> annotation as well, as shown in the following example:</simpara>
<programlisting language="java" linenumbering="unnumbered">@RunWith(SpringRunner.class)
@SpringBootTest("app.baseUrl=https://localhost:6443")
@AutoConfigureHttpClient
public class WiremockHttpsServerApplicationTests {
@ClassRule
public static WireMockClassRule wiremock = new WireMockClassRule(
WireMockSpring.options().httpsPort(6443));
...
}</programlisting>
<simpara>If you are using <literal>spring-boot-starter-test</literal>, you have the Apache HTTP client on the
classpath and it is selected by the <literal>RestTemplateBuilder</literal> and configured to ignore SSL
errors. If you use the default <literal>java.net</literal> client, you do not need the annotation (but it
won&#8217;t do any harm). There is no support currently for other clients, but it may be added
in future releases.</simpara>
<simpara>To disable the custom <literal>RestTemplateBuilder</literal>, set the <literal>wiremock.rest-template-ssl-enabled</literal>
property to <literal>false</literal>.</simpara>
</section>
<section xml:id="_wiremock_and_spring_mvc_mocks">
<title>WireMock and Spring MVC Mocks</title>
<simpara>Spring Cloud Contract provides a convenience class that can load JSON WireMock stubs into
a Spring <literal>MockRestServiceServer</literal>. The following code shows an example:</simpara>
<programlisting language="java" linenumbering="unnumbered">@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = WebEnvironment.NONE)
public class WiremockForDocsMockServerApplicationTests {
@Autowired
private RestTemplate restTemplate;
@Autowired
private Service service;
@Test
public void contextLoads() throws Exception {
// will read stubs classpath
MockRestServiceServer server = WireMockRestServiceServer.with(this.restTemplate)
.baseUrl("http://example.org").stubs("classpath:/stubs/resource.json")
.build();
// We're asserting if WireMock responded properly
assertThat(this.service.go()).isEqualTo("Hello World");
server.verify();
}
}</programlisting>
<simpara>The <literal>baseUrl</literal> value is prepended to all mock calls, and the <literal>stubs()</literal> method takes a stub
path resource pattern as an argument. In the preceding example, the stub defined at
<literal>/stubs/resource.json</literal> is loaded into the mock server. If the <literal>RestTemplate</literal> is asked to
visit <literal><link xl:href="http://example.org/">http://example.org/</link></literal>, it gets the responses as being declared at that URL. More
than one stub pattern can be specified, and each one can be a directory (for a recursive
list of all ".json"), a fixed filename (as in the example above), or an Ant-style
pattern. The JSON format is the normal WireMock format, which you can read about in the
<link xl:href="http://wiremock.org/docs/stubbing/">WireMock website</link>.</simpara>
<simpara>Currently, the Spring Cloud Contract Verifier supports Tomcat, Jetty, and Undertow as
Spring Boot embedded servers, and Wiremock itself has "native" support for a particular
version of Jetty (currently 9.2). To use the native Jetty, you need to add the native
Wiremock dependencies and exclude the Spring Boot container (if there is one).</simpara>
</section>
<section xml:id="_customization_of_wiremock_configuration">
<title>Customization of WireMock configuration</title>
<simpara>You can register a bean of <literal>org.springframework.cloud.contract.wiremock.WireMockConfigurationCustomizer</literal> type
in order to customize the WireMock configuration (e.g. add custom transformers).
Example:</simpara>
<programlisting language="java" linenumbering="unnumbered"> @Bean
WireMockConfigurationCustomizer optionsCustomizer() {
return new WireMockConfigurationCustomizer() {
@Override
public void customize(WireMockConfiguration options) {
// perform your customization here
}
};
}</programlisting>
</section>
<section xml:id="_generating_stubs_using_rest_docs">
<title>Generating Stubs using REST Docs</title>
<simpara><link xl:href="https://projects.spring.io/spring-restdocs">Spring REST Docs</link> can be used to generate
documentation (for example in Asciidoctor format) for an HTTP API with Spring MockMvc
or <literal>WebTestClient</literal> or Rest Assured. At the same time that you generate documentation for your API, you can also
generate WireMock stubs by using Spring Cloud Contract WireMock. To do so, write your
normal REST Docs test cases and use <literal>@AutoConfigureRestDocs</literal> to have stubs be
automatically generated in the REST Docs output directory. The following code shows an
example using <literal>MockMvc</literal>:</simpara>
<programlisting language="java" linenumbering="unnumbered">@RunWith(SpringRunner.class)
@SpringBootTest
@AutoConfigureRestDocs(outputDir = "target/snippets")
@AutoConfigureMockMvc
public class ApplicationTests {
@Autowired
private MockMvc mockMvc;
@Test
public void contextLoads() throws Exception {
mockMvc.perform(get("/resource"))
.andExpect(content().string("Hello World"))
.andDo(document("resource"));
}
}</programlisting>
<simpara>This test generates a WireMock stub at "target/snippets/stubs/resource.json". It matches
all GET requests to the "/resource" path. The same example with <literal>WebTestClient</literal> (used
for testing Spring WebFlux applications) would look like this:</simpara>
<programlisting language="java" linenumbering="unnumbered">@RunWith(SpringRunner.class)
@SpringBootTest
@AutoConfigureRestDocs(outputDir = "target/snippets")
@AutoConfigureWebTestClient
public class ApplicationTests {
@Autowired
private WebTestClient client;
@Test
public void contextLoads() throws Exception {
client.get().uri("/resource").exchange()
.expectBody(String.class).isEqualTo("Hello World")
.consumeWith(document("resource"));
}
}</programlisting>
<simpara>Without any additional configuration, these tests create a stub with a request matcher
for the HTTP method and all headers except "host" and "content-length". To match the
request more precisely (for example, to match the body of a POST or PUT), we need to
explicitly create a request matcher. Doing so has two effects:</simpara>
<itemizedlist>
<listitem>
<simpara>Creating a stub that matches only in the way you specify.</simpara>
</listitem>
<listitem>
<simpara>Asserting that the request in the test case also matches the same conditions.</simpara>
</listitem>
</itemizedlist>
<simpara>The main entry point for this feature is <literal>WireMockRestDocs.verify()</literal>, which can be used
as a substitute for the <literal>document()</literal> convenience method, as shown in the following
example:</simpara>
<programlisting language="java" linenumbering="unnumbered">import static org.springframework.cloud.contract.wiremock.restdocs.WireMockRestDocs.verify;</programlisting>
<screen>@RunWith(SpringRunner.class)
@SpringBootTest
@AutoConfigureRestDocs(outputDir = "target/snippets")
@AutoConfigureMockMvc
public class ApplicationTests {
@Autowired
private MockMvc mockMvc;
@Test
public void contextLoads() throws Exception {
mockMvc.perform(post("/resource")
.content("{\"id\":\"123456\",\"message\":\"Hello World\"}"))
.andExpect(status().isOk())
.andDo(verify().jsonPath("$.id")
.stub("resource"));
}
}</screen>
<simpara>This contract specifies that any valid POST with an "id" field receives the response
defined in this test. You can chain together calls to <literal>.jsonPath()</literal> to add additional
matchers. If JSON Path is unfamiliar, The <link xl:href="https://github.com/jayway/JsonPath">JayWay
documentation</link> can help you get up to speed. The <literal>WebTestClient</literal> version of this test
has a similar <literal>verify()</literal> static helper that you insert in the same place.</simpara>
<simpara>Instead of the <literal>jsonPath</literal> and <literal>contentType</literal> convenience methods, you can also use the
WireMock APIs to verify that the request matches the created stub, as shown in the
following example:</simpara>
<programlisting language="java" linenumbering="unnumbered">@Test
public void contextLoads() throws Exception {
mockMvc.perform(post("/resource")
.content("{\"id\":\"123456\",\"message\":\"Hello World\"}"))
.andExpect(status().isOk())
.andDo(verify()
.wiremock(WireMock.post(
urlPathEquals("/resource"))
.withRequestBody(matchingJsonPath("$.id"))
.stub("post-resource"));
}</programlisting>
<simpara>The WireMock API is rich. You can match headers, query parameters, and request body by
regex as well as by JSON path. These features can be used to create stubs with a wider
range of parameters. The above example generates a stub resembling the following example:</simpara>
<formalpara>
<title>post-resource.json</title>
<para>
<programlisting language="json" linenumbering="unnumbered">{
"request" : {
"url" : "/resource",
"method" : "POST",
"bodyPatterns" : [ {
"matchesJsonPath" : "$.id"
}]
},
"response" : {
"status" : 200,
"body" : "Hello World",
"headers" : {
"X-Application-Context" : "application:-1",
"Content-Type" : "text/plain"
}
}
}</programlisting>
</para>
</formalpara>
<note>
<simpara>You can use either the <literal>wiremock()</literal> method or the <literal>jsonPath()</literal> and <literal>contentType()</literal>
methods to create request matchers, but you can&#8217;t use both approaches.</simpara>
</note>
<simpara>On the consumer side, you can make the <literal>resource.json</literal> generated earlier in this section
available on the classpath (by
&lt;&lt;publishing-stubs-as-jars], for example). After that, you can create a stub using WireMock in a
number of different ways, including by using
<literal>@AutoConfigureWireMock(stubs="classpath:resource.json")</literal>, as described earlier in this
document.</simpara>
</section>
<section xml:id="_generating_contracts_by_using_rest_docs">
<title>Generating Contracts by Using REST Docs</title>
<simpara>You can also generate Spring Cloud Contract DSL files and documentation with Spring REST
Docs. If you do so in combination with Spring Cloud WireMock, you get both the contracts
and the stubs.</simpara>
<simpara>Why would you want to use this feature? Some people in the community asked questions
about a situation in which they would like to move to DSL-based contract definition,
but they already have a lot of Spring MVC tests. Using this feature lets you generate
the contract files that you can later modify and move to folders (defined in your
configuration) so that the plugin finds them.</simpara>
<tip>
<simpara>You might wonder why this functionality is in the WireMock module. The functionality
is there because it makes sense to generate both the contracts and the stubs.</simpara>
</tip>
<simpara>Consider the following test:</simpara>
<programlisting language="java" linenumbering="unnumbered"> this.mockMvc
.perform(post("/foo").accept(MediaType.APPLICATION_PDF)
.accept(MediaType.APPLICATION_JSON)
.contentType(MediaType.APPLICATION_JSON)
.content("{\"foo\": 23, \"bar\" : \"baz\" }"))
.andExpect(status().isOk()).andExpect(content().string("bar"))
// first WireMock
.andDo(WireMockRestDocs.verify().jsonPath("$[?(@.foo &gt;= 20)]")
.jsonPath("$[?(@.bar in ['baz','bazz','bazzz'])]")
.contentType(MediaType.valueOf("application/json"))
.stub("shouldGrantABeerIfOldEnough"))
// then Contract DSL documentation
.andDo(document("index", SpringCloudContractRestDocs.dslContract()));</programlisting>
<simpara>The preceding test creates the stub presented in the previous section, generating both
the contract and a documentation file.</simpara>
<simpara>The contract is called <literal>index.groovy</literal> and might look like the following example:</simpara>
<programlisting language="groovy" linenumbering="unnumbered">import org.springframework.cloud.contract.spec.Contract
Contract.make {
request {
method 'POST'
url '/foo'
body('''
{"foo": 23 }
''')
headers {
header('''Accept''', '''application/json''')
header('''Content-Type''', '''application/json''')
}
}
response {
status OK()
body('''
bar
''')
headers {
header('''Content-Type''', '''application/json;charset=UTF-8''')
header('''Content-Length''', '''3''')
}
testMatchers {
jsonPath('$[?(@.foo &gt;= 20)]', byType())
}
}
}</programlisting>
<simpara>The generated document (formatted in Asciidoc in this case) contains a formatted
contract. The location of this file would be <literal>index/dsl-contract.adoc</literal>.</simpara>
</section>
</chapter>
<chapter xml:id="_migrations">
<title>Migrations</title>
<tip>
<simpara>For up to date migration guides please visit
the project&#8217;s <link xl:href="https://github.com/spring-cloud/spring-cloud-contract/wiki/">wiki page</link>.</simpara>
</tip>
<simpara>This section covers migrating from one version of Spring Cloud Contract Verifier to the
next version. It covers the following versions upgrade paths:</simpara>
<section xml:id="cloud-verifier-1.0-1.1">
<title>1.0.x &#8594; 1.1.x</title>
<simpara>This section covers upgrading from version 1.0 to version 1.1.</simpara>
<section xml:id="_new_structure_of_generated_stubs">
<title>New structure of generated stubs</title>
<simpara>In <literal>1.1.x</literal> we have introduced a change to the structure of generated stubs. If you have
been using the <literal>@AutoConfigureWireMock</literal> notation to use the stubs from the classpath,
it no longer works. The following example shows how the <literal>@AutoConfigureWireMock</literal> notation
used to work:</simpara>
<programlisting language="java" linenumbering="unnumbered">@AutoConfigureWireMock(stubs = "classpath:/customer-stubs/mappings", port = 8084)</programlisting>
<simpara>You must either change the location of the stubs to:
<literal>classpath:&#8230;&#8203;/META-INF/groupId/artifactId/version/mappings</literal> or use the new
classpath-based <literal>@AutoConfigureStubRunner</literal>, as shown in the following example:</simpara>
<programlisting language="java" linenumbering="unnumbered">@AutoConfigureWireMock(stubs = "classpath:customer-stubs/META-INF/travel.components/customer-contract/1.0.2-SNAPSHOT/mappings/", port = 8084)</programlisting>
<simpara>If you do not want to use <literal>@AutoConfigureStubRunner</literal> and you want to remain with the old
structure, set your plugin tasks accordingly. The following example would work for the
structure presented in the previous snippet.</simpara>
<formalpara role="primary">
<title>Maven</title>
<para>
<programlisting language="xml" linenumbering="unnumbered">&lt;!-- start of pom.xml --&gt;
&lt;properties&gt;
&lt;!-- we don't want the verifier to do a jar for us --&gt;
&lt;spring.cloud.contract.verifier.skip&gt;true&lt;/spring.cloud.contract.verifier.skip&gt;
&lt;/properties&gt;
&lt;!-- ... --&gt;
&lt;!-- You need to set up the assembly plugin --&gt;
&lt;build&gt;
&lt;plugins&gt;
&lt;plugin&gt;
&lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
&lt;artifactId&gt;maven-assembly-plugin&lt;/artifactId&gt;
&lt;executions&gt;
&lt;execution&gt;
&lt;id&gt;stub&lt;/id&gt;
&lt;phase&gt;prepare-package&lt;/phase&gt;
&lt;goals&gt;
&lt;goal&gt;single&lt;/goal&gt;
&lt;/goals&gt;
&lt;inherited&gt;false&lt;/inherited&gt;
&lt;configuration&gt;
&lt;attach&gt;true&lt;/attach&gt;
&lt;descriptor&gt;${basedir}/src/assembly/stub.xml&lt;/descriptor&gt;
&lt;/configuration&gt;
&lt;/execution&gt;
&lt;/executions&gt;
&lt;/plugin&gt;
&lt;/plugins&gt;
&lt;/build&gt;
&lt;!-- end of pom.xml --&gt;
&lt;!-- start of stub.xml--&gt;
&lt;assembly
xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd"&gt;
&lt;id&gt;stubs&lt;/id&gt;
&lt;formats&gt;
&lt;format&gt;jar&lt;/format&gt;
&lt;/formats&gt;
&lt;includeBaseDirectory&gt;false&lt;/includeBaseDirectory&gt;
&lt;fileSets&gt;
&lt;fileSet&gt;
&lt;directory&gt;${project.build.directory}/snippets/stubs&lt;/directory&gt;
&lt;outputDirectory&gt;customer-stubs/mappings&lt;/outputDirectory&gt;
&lt;includes&gt;
&lt;include&gt;**/*&lt;/include&gt;
&lt;/includes&gt;
&lt;/fileSet&gt;
&lt;fileSet&gt;
&lt;directory&gt;${basedir}/src/test/resources/contracts&lt;/directory&gt;
&lt;outputDirectory&gt;customer-stubs/contracts&lt;/outputDirectory&gt;
&lt;includes&gt;
&lt;include&gt;**/*.groovy&lt;/include&gt;
&lt;/includes&gt;
&lt;/fileSet&gt;
&lt;/fileSets&gt;
&lt;/assembly&gt;
&lt;!-- end of stub.xml--&gt;</programlisting>
</para>
</formalpara>
<formalpara role="secondary">
<title>Gradle</title>
<para>
<programlisting language="groovy" linenumbering="unnumbered">task copyStubs(type: Copy, dependsOn: 'generateWireMockClientStubs') {
// Preserve directory structure from 1.0.X of spring-cloud-contract
from "${project.buildDir}/resources/main/customer-stubs/META-INF/${project.group}/${project.name}/${project.version}"
into "${project.buildDir}/resources/main/customer-stubs"
}</programlisting>
</para>
</formalpara>
</section>
</section>
<section xml:id="cloud-verifier-1.1-1.2">
<title>1.1.x &#8594; 1.2.x</title>
<simpara>This section covers upgrading from version 1.1 to version 1.2.</simpara>
<section xml:id="_custom_httpserverstub">
<title>Custom <literal>HttpServerStub</literal></title>
<simpara><literal>HttpServerStub</literal> includes a method that was not in version 1.1. The method is
<literal>String registeredMappings()</literal> If you have classes that implement <literal>HttpServerStub</literal>, you
now have to implement the <literal>registeredMappings()</literal> method. It should return a <literal>String</literal>
representing all mappings available in a single <literal>HttpServerStub</literal>.</simpara>
<simpara>See <link xl:href="https://github.com/spring-cloud/spring-cloud-contract/issues/355">issue 355</link> for more
detail.</simpara>
</section>
<section xml:id="_new_packages_for_generated_tests">
<title>New packages for generated tests</title>
<simpara>The flow for setting the generated tests package name will look like this:</simpara>
<itemizedlist>
<listitem>
<simpara>Set <literal>basePackageForTests</literal></simpara>
</listitem>
<listitem>
<simpara>If <literal>basePackageForTests</literal> was not set, pick the package from <literal>baseClassForTests</literal></simpara>
</listitem>
<listitem>
<simpara>If <literal>baseClassForTests</literal> was not set, pick <literal>packageWithBaseClasses</literal></simpara>
</listitem>
<listitem>
<simpara>If nothing got set, pick the default value:
<literal>org.springframework.cloud.contract.verifier.tests</literal></simpara>
</listitem>
</itemizedlist>
<simpara>See <link xl:href="https://github.com/spring-cloud/spring-cloud-contract/issues/260">issue 260</link> for more
detail.</simpara>
</section>
<section xml:id="_new_methods_in_templateprocessor">
<title>New Methods in TemplateProcessor</title>
<simpara>In order to add support for <literal>fromRequest.path</literal>, the following methods had to be added to the
<literal>TemplateProcessor</literal> interface:</simpara>
<itemizedlist>
<listitem>
<simpara><literal>path()</literal></simpara>
</listitem>
<listitem>
<simpara><literal>path(int index)</literal></simpara>
</listitem>
</itemizedlist>
<simpara>See <link xl:href="https://github.com/spring-cloud/spring-cloud-contract/issues/388">issue 388</link> for more
detail.</simpara>
</section>
<section xml:id="_restassured_3_0">
<title>RestAssured 3.0</title>
<simpara>Rest Assured, used in the generated test classes, got bumped to <literal>3.0</literal>. If
you manually set versions of Spring Cloud Contract and the release train
you might see the following exception:</simpara>
<programlisting language="bash" linenumbering="unnumbered">Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.1:testCompile (default-testCompile) on project some-project: Compilation failure: Compilation failure:
[ERROR] /some/path/SomeClass.java:[4,39] package com.jayway.restassured.response does not exist</programlisting>
<simpara>This exception will occur due to the fact that the tests got generated with
an old version of plugin and at test execution time you have an incompatible
version of the release train (and vice versa).</simpara>
<simpara>Done via <link xl:href="https://github.com/spring-cloud/spring-cloud-contract/issues/267">issue 267</link></simpara>
</section>
</section>
<section xml:id="cloud-verifier-1.2-2.0">
<title>1.2.x &#8594; 2.0.x</title>
</section>
</chapter>
<chapter xml:id="_links">
<title>Links</title>
<simpara>The following links may be helpful when working with Spring Cloud Contract:</simpara>
<itemizedlist>
<listitem>
<simpara><link xl:href="https://github.com/spring-cloud/spring-cloud-contract/">Spring Cloud Contract Github
Repository</link></simpara>
</listitem>
<listitem>
<simpara><link xl:href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/">Spring Cloud
Contract Samples</link></simpara>
</listitem>
<listitem>
<simpara><link xl:href="https://gitter.im/spring-cloud/spring-cloud-contract">Spring Cloud Contract Gitter</link></simpara>
</listitem>
<listitem>
<simpara><link xl:href="https://www.youtube.com/watch?v=sAAklvxmPmk">Spring Cloud Contract WJUG Presentation by
Marcin Grzejszczak</link></simpara>
</listitem>
</itemizedlist>
</chapter>
</book>
Reference in New Issue View Git Blame Copy Permalink