SpringCloud/spring-cloud-static
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
Files
40e5da70f5bbff96ed27356bebb3e0c80f8fda1f
spring-cloud-static/spring-cloud-contract/2.2.0.RC1/reference/html/project-features.html
buildmaster 40e5da70f5 Sync docs from v2.2.0.RC1 to gh-pages
2019-10-24 21:38:37 +00:00

10778 lines
391 KiB
HTML
Raw 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.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.8">
<title>Spring Cloud Contract Features</title>
<link rel="stylesheet" href="css/spring.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<style>
.hidden {
display: none;
}
.switch {
border-width: 1px 1px 0 1px;
border-style: solid;
border-color: #7a2518;
display: inline-block;
}
.switch--item {
padding: 10px;
background-color: #ffffff;
color: #7a2518;
display: inline-block;
cursor: pointer;
}
.switch--item:not(:first-child) {
border-width: 0 0 0 1px;
border-style: solid;
border-color: #7a2518;
}
.switch--item.selected {
background-color: #7a2519;
color: #ffffff;
}
</style>
<script src="https://cdnjs.cloudflare.com/ajax/libs/zepto/1.2.0/zepto.min.js"></script>
<script type="text/javascript">
function addBlockSwitches() {
$('.primary').each(function() {
primary = $(this);
createSwitchItem(primary, createBlockSwitch(primary)).item.addClass("selected");
primary.children('.title').remove();
});
$('.secondary').each(function(idx, node) {
secondary = $(node);
primary = findPrimary(secondary);
switchItem = createSwitchItem(secondary, primary.children('.switch'));
switchItem.content.addClass('hidden');
findPrimary(secondary).append(switchItem.content);
secondary.remove();
});
}
function createBlockSwitch(primary) {
blockSwitch = $('<div class="switch"></div>');
primary.prepend(blockSwitch);
return blockSwitch;
}
function findPrimary(secondary) {
candidate = secondary.prev();
while (!candidate.is('.primary')) {
candidate = candidate.prev();
}
return candidate;
}
function createSwitchItem(block, blockSwitch) {
blockName = block.children('.title').text();
content = block.children('.content').first().append(block.next('.colist'));
item = $('<div class="switch--item">' + blockName + '</div>');
item.on('click', '', content, function(e) {
$(this).addClass('selected');
$(this).siblings().removeClass('selected');
e.data.siblings('.content').addClass('hidden');
e.data.removeClass('hidden');
});
blockSwitch.append(item);
return {'item': item, 'content': content};
}
$(addBlockSwitches);
</script>
</head>
<body id="features" class="book toc2 toc-left">
<div id="header">
<h1>Spring Cloud Contract Features</h1>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#contract-dsl">1. Contract DSL</a>
<ul class="sectlevel2">
<li><a href="#contract-groovy">1.1. Contract DSL in Groovy</a></li>
<li><a href="#contract-java">1.2. Contract DSL in Java</a></li>
<li><a href="#contract-kotlin">1.3. Contract DSL in Kotlin</a></li>
<li><a href="#contract-yml">1.4. Contract DSL in YML</a></li>
<li><a href="#contract-limitations">1.5. Limitations</a></li>
<li><a href="#contract-common-top-elements">1.6. Common Top-Level Elements</a>
<ul class="sectlevel3">
<li><a href="#contract-dsl-description">1.6.1. Description</a></li>
<li><a href="#contract-dsl-name">1.6.2. Name</a></li>
<li><a href="#contract-dsl-ignoring-contracts">1.6.3. Ignoring Contracts</a></li>
<li><a href="#contract-dsl-in-progress">1.6.4. Contracts in Progress</a></li>
<li><a href="#contract-dsl-passing-values-from-files">1.6.5. Passing Values from Files</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#features-http">2. Contracts for HTTP</a>
<ul class="sectlevel2">
<li><a href="#contract-dsl-http-top-level-elements">2.1. HTTP Top-Level Elements</a></li>
<li><a href="#contract-dsl-request">2.2. HTTP Request</a></li>
<li><a href="#contract-dsl-response">2.3. HTTP Response</a></li>
<li><a href="#contract-dsl-dynamic-properties">2.4. Dynamic properties</a>
<ul class="sectlevel3">
<li><a href="#contract-dsl-dynamic-properties-in-body">2.4.1. Dynamic Properties inside the Body</a></li>
<li><a href="#contract-dsl-regex">2.4.2. Regular Expressions</a>
<ul class="sectlevel4">
<li><a href="#contract-dsl-regex-limitations">Limitations</a></li>
</ul>
</li>
<li><a href="#contract-dsl-optional-params">2.4.3. Passing Optional Parameters</a></li>
<li><a href="#contract-dsl-custom-methods">2.4.4. Executing Custom Methods on the Server Side</a></li>
<li><a href="#contract-dsl-referencing-request-from-response">2.4.5. Referencing the Request from the Response</a></li>
<li><a href="#contract-dsl-matchers">2.4.6. Dynamic Properties in the Matchers Sections</a>
<ul class="sectlevel4">
<li><a href="#coded-dsl">Coded DSL</a></li>
<li><a href="#yaml">YAML</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#contract-dsl-async">2.5. Asynchronous Support</a></li>
<li><a href="#contract-dsl-xml">2.6. XML Support for HTTP</a></li>
<li><a href="#contract-dsl-multiple">2.7. Multiple Contracts in One File</a></li>
<li><a href="#contract-stateful-contracts">2.8. Stateful Contracts</a></li>
</ul>
</li>
<li><a href="#feature-integrations">3. Integrations</a>
<ul class="sectlevel2">
<li><a href="#features-jax-rs">3.1. JAX-RS</a></li>
<li><a href="#feature-webflux">3.2. WebFlux with WebTestClient</a></li>
<li><a href="#feature-webflux-explicit">3.3. WebFlux with Explicit Mode</a></li>
<li><a href="#features-context-paths">3.4. Working with Context Paths</a></li>
<li><a href="#features-rest-docs">3.5. Working with REST Docs</a>
<ul class="sectlevel3">
<li><a href="#features-rest-docs-contracts">3.5.1. Generating Contracts with REST Docs</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#features-messaging">4. Messaging</a>
<ul class="sectlevel2">
<li><a href="#contract-dsl-messaging-top-level">4.1. Messaging DSL Top-Level Elements</a>
<ul class="sectlevel3">
<li><a href="#contract-dsl-output-triggered-method">4.1.1. Output Triggered by a Method</a></li>
<li><a href="#contract-dsl-output-triggered-message">4.1.2. Output Triggered by a Message</a></li>
<li><a href="#contract-dsl-consumer-producer">4.1.3. Consumer/Producer</a></li>
<li><a href="#contract-dsl-messaging-common">4.1.4. Common</a></li>
</ul>
</li>
<li><a href="#features-messaging-integrations">4.2. Integrations</a>
<ul class="sectlevel3">
<li><a href="#features-messaging-manual">4.2.1. Manual Integration Testing</a></li>
</ul>
</li>
<li><a href="#features-messaging-test-generation">4.3. Producer Side Messaging Test Generation</a>
<ul class="sectlevel3">
<li><a href="#features-messaging-scenario1">4.3.1. Scenario 1: No Input Message</a></li>
<li><a href="#features-messaging-scenario2">4.3.2. Scenario 2: Output Triggered by Input</a></li>
<li><a href="#features-messaging-scenario3">4.3.3. Scenario 3: No Output Message</a></li>
</ul>
</li>
<li><a href="#features-messaging-consumer">4.4. Consumer Stub Generation</a>
<ul class="sectlevel3">
<li><a href="#features-messaging-stub-triggering">4.4.1. Stub triggering</a></li>
<li><a href="#features-messaging-trigger-label">4.4.2. Trigger by Label</a></li>
<li><a href="#features-messaging-trigger-group-artifact-ids">4.4.3. Trigger by Group and Artifact Ids</a></li>
<li><a href="#features-messaging-trigger-artifact-ids">4.4.4. Trigger by Artifact IDs</a></li>
<li><a href="#features-messaging-trigger-all-messages">4.4.5. Trigger All Messages</a></li>
</ul>
</li>
<li><a href="#features-messaging-stub-runner-camel">4.5. Consumer Side Messaging With Apache Camel</a>
<ul class="sectlevel3">
<li><a href="#features-messaging-stub-runner-camel-adding">4.5.1. Adding Apache Camel to the Project</a></li>
<li><a href="#features-messaging-stub-runner-camel-disabling">4.5.2. Disabling the Functionality</a></li>
<li><a href="#features-messaging-stub-runner-camel-example">4.5.3. Examples</a>
<ul class="sectlevel4">
<li><a href="#features-messaging-stub-runner-camel-scenario1">Scenario 1 (No Input Message)</a></li>
<li><a href="#features-messaging-stub-runner-camel-scenario2">Scenario 2 (Output Triggered by Input)</a></li>
<li><a href="#features-messaging-stub-runner-camel-scenario3">Scenario 3 (Input with No Output)</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#features-messaging-stub-runner-integration">4.6. Consumer Side Messaging with Spring Integration</a>
<ul class="sectlevel3">
<li><a href="#features-messaging-stub-runner-integration-adding">4.6.1. Adding the Runner to the Project</a></li>
<li><a href="#features-messaging-stub-runner-integration-disabling">4.6.2. Disabling the Functionality</a></li>
<li><a href="#features-messaging-stub-runner-integration-example">4.6.3. Examples</a>
<ul class="sectlevel4">
<li><a href="#features-messaging-stub-runner-integration-scenario1">Scenario 1 (No Input Message)</a></li>
<li><a href="#features-messaging-stub-runner-integration-scenario2">Scenario 2 (Output Triggered by Input)</a></li>
<li><a href="#features-messaging-stub-runner-integration-scenario3">Scenario 3 (Input with No Output)</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#features-messaging-stub-runner-stream">4.7. Consumer Side Messaging With Spring Cloud Stream</a>
<ul class="sectlevel3">
<li><a href="#features-messaging-stub-runner-stream-adding">4.7.1. Adding the Runner to the Project</a></li>
<li><a href="#features-messaging-stub-runner-stream-disabling">4.7.2. Disabling the Functionality</a></li>
<li><a href="#features-messaging-stub-runner-stream-example">4.7.3. Examples</a>
<ul class="sectlevel4">
<li><a href="#features-messaging-stub-runner-stream-scenario1">Scenario 1 (No Input Message)</a></li>
<li><a href="#features-messaging-stub-runner-stream-scenario2">Scenario 2 (Output Triggered by Input)</a></li>
<li><a href="#features-messaging-stub-runner-stream-scenario3">Scenario 3 (Input with No Output)</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#features-messaging-stub-runner-amqp">4.8. Consumer Side Messaging With Spring AMQP</a>
<ul class="sectlevel3">
<li><a href="#features-messaging-stub-runner-amqp-adding">4.8.1. Adding the Runner to the Project</a></li>
<li><a href="#features-messaging-stub-runner-amqp-example">4.8.2. Examples</a>
<ul class="sectlevel4">
<li><a href="#features-messaging-stub-runner-amqp-triggering">Triggering the Message</a></li>
<li><a href="#features-messaging-stub-runner-amqp-configuration">Spring AMQP Test Configuration</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#features-messaging-stub-runner-jms">4.9. Consumer Side Messaging With Spring JMS</a>
<ul class="sectlevel3">
<li><a href="#features-messaging-stub-runner-jms-adding">4.9.1. Adding the Runner to the Project</a></li>
<li><a href="#features-messaging-stub-runner-jms-example">4.9.2. Examples</a>
<ul class="sectlevel4">
<li><a href="#features-messaging-stub-runner-jms-scenario1">Scenario 1 (No Input Message)</a></li>
<li><a href="#features-messaging-stub-runner-jms-scenario2">Scenario 2 (Output Triggered by Input)</a></li>
<li><a href="#features-messaging-stub-runner-jms-scenario3">Scenario 3 (Input with No Output)</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#features-messaging-stub-runner-kafka">4.10. Consumer Side Messaging With Spring Kafka</a>
<ul class="sectlevel3">
<li><a href="#features-messaging-stub-runner-kafka-adding">4.10.1. Adding the Runner to the Project</a></li>
<li><a href="#features-messaging-stub-runner-kafka-example">4.10.2. Examples</a>
<ul class="sectlevel4">
<li><a href="#features-messaging-stub-runner-kafka-scenario1">Scenario 1 (No Input Message)</a></li>
<li><a href="#features-messaging-stub-runner-kafka-scenario2">Scenario 2 (Output Triggered by Input)</a></li>
<li><a href="#features-messaging-stub-runner-kafka-scenario3">Scenario 3 (Input with No Output)</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a href="#features-stub-runner">5. Spring Cloud Contract Stub Runner</a>
<ul class="sectlevel2">
<li><a href="#features-stub-runner-snapshot-versions">5.1. Snapshot Versions</a></li>
<li><a href="#features-stub-runner-publishing-stubs-as-jars">5.2. Publishing Stubs as JARs</a></li>
<li><a href="#features-stub-runner-core">5.3. Stub Runner Core</a>
<ul class="sectlevel3">
<li><a href="#features-stub-runner-retrieving">5.3.1. Retrieving stubs</a>
<ul class="sectlevel4">
<li><a href="#features-stub-runner-downloading-stub">Downloading Stubs</a></li>
<li><a href="#features-stub-runner-classpath-scanning">Classpath scanning</a></li>
<li><a href="#features-stub-runner-configuring-http-server-stubs">Configuring HTTP Server Stubs</a></li>
</ul>
</li>
<li><a href="#features-stub-runner-running-stubs">5.3.2. Running stubs</a>
<ul class="sectlevel4">
<li><a href="#features-stub-runner-http-stubs">HTTP Stubs</a></li>
<li><a href="#features-stub-runner-viewing">Viewing Registered Mappings</a></li>
<li><a href="#features-stub-runner-messaging">Messaging Stubs</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#features-stub-runner-junit">5.4. Stub Runner JUnit Rule and Stub Runner JUnit5 Extension</a>
<ul class="sectlevel3">
<li><a href="#features-stub-runner-rule-maven-settings">5.4.1. Maven Settings</a></li>
<li><a href="#features-stub-runner-rule-fixed-ports">5.4.2. Providing Fixed Ports</a></li>
<li><a href="#features-stub-runner-rule-fluent-api">5.4.3. Fluent API</a></li>
<li><a href="#features-stub-runner-rule-spring">5.4.4. Stub Runner with Spring</a></li>
</ul>
</li>
<li><a href="#features-stub-runner-cloud">5.5. Stub Runner Spring Cloud</a>
<ul class="sectlevel3">
<li><a href="#features-stub-runner-cloud-stubbing-discovery">5.5.1. Stubbing Service Discovery</a>
<ul class="sectlevel4">
<li><a href="#features-stub-runner-cloud-stubbing-profiles">Test Profiles and Service Discovery</a></li>
</ul>
</li>
<li><a href="#features-stub-runner-additional-config">5.5.2. Additional Configuration</a></li>
</ul>
</li>
<li><a href="#features-stub-runner-boot">5.6. Using the Stub Runner Boot Application</a>
<ul class="sectlevel3">
<li><a href="#features-stub-runner-boot-server">5.6.1. Stub Runner Server</a></li>
<li><a href="#features-stub-runner-boot-how-fat-jar">5.6.2. Stub Runner Server Fat Jar</a></li>
<li><a href="#features-stub-runner-boot-how-cli">5.6.3. Spring Cloud CLI</a></li>
<li><a href="#features-stub-runner-boot-endpoints">5.6.4. Endpoints</a>
<ul class="sectlevel4">
<li><a href="#features-stub-runner-boot-endpoints-http">HTTP</a></li>
<li><a href="#features-stub-runner-boot-endpoints-messaging">Messaging</a></li>
</ul>
</li>
<li><a href="#features-stub-runner-boot-endpoints-example">5.6.5. Example</a></li>
<li><a href="#features-stub-runner-boot-service-discovery">5.6.6. Stub Runner Boot with Service Discovery</a></li>
</ul>
</li>
<li><a href="#features-stub-runner-stubs-per-consumer">5.7. Consumer-Driven Contracts: Stubs Per Consumer</a></li>
<li><a href="#features-stub-runner-stubs-protocol">5.8. Fetching Stubs or Contract Definitions From A Location</a></li>
<li><a href="#features-stub-runner-generate-stubs-at-runtime">5.9. Generating Stubs at Runtime</a></li>
<li><a href="#features-stub-runner-fail-on-no-stubs">5.10. Fail On No Stubs</a></li>
<li><a href="#features-stub-runner-common">5.11. Common Properties</a>
<ul class="sectlevel3">
<li><a href="#features-stub-runner-common-properties-junit-spring">5.11.1. Common Properties for JUnit and Spring</a></li>
<li><a href="#features-stub-runner-stub-runner-stub-ids">5.11.2. Stub Runner Stubs IDs</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#features-wiremock">6. Spring Cloud Contract WireMock</a>
<ul class="sectlevel2">
<li><a href="#features-wiremock-registering-stubs">6.1. Registering Stubs Automatically</a></li>
<li><a href="#features-wiremock-using-files">6.2. Using Files to Specify the Stub Bodies</a></li>
<li><a href="#features-wiremock-junit-rule">6.3. Alternative: Using JUnit Rules</a></li>
<li><a href="#features-wiremock-relaxed-ssl">6.4. Relaxed SSL Validation for Rest Template</a></li>
<li><a href="#features-wiremock-spring-mvc-mocks">6.5. WireMock and Spring MVC Mocks</a></li>
</ul>
</li>
<li><a href="#features-build-tools">7. Build Tools Integration</a></li>
<li><a href="#features-whats-next">8. What to Read Next</a></li>
</ul>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>This section dives into the details of Spring Cloud Contract. Here you can learn about the key
features that you may want to use and customize. If you have not already done so, you
might want to read the "<a href="getting-started.html#getting-started">getting-started.html</a>" and
"<a href="using.html#using">using.html</a>" sections, so that you have a good grounding of the
basics.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="contract-dsl"><a class="anchor" href="#contract-dsl"></a><a class="link" href="#contract-dsl">1. Contract DSL</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Spring Cloud Contract supports the DSLs written in the following languages:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Groovy</p>
</li>
<li>
<p>YAML</p>
</li>
<li>
<p>Java</p>
</li>
<li>
<p>Kotlin</p>
</li>
</ul>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Spring Cloud Contract supports defining multiple contracts in a single file.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The following example shows a contract definition:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">org.springframework.cloud.contract.spec.Contract.make {
request {
method 'PUT'
url '/api/12'
headers {
header 'Content-Type': 'application/vnd.org.springframework.cloud.contract.verifier.twitter-places-analyzer.v1+json'
}
body '''\
[{
"created_at": "Sat Jul 26 09:38:57 +0000 2014",
"id": 492967299297845248,
"id_str": "492967299297845248",
"text": "Gonna see you at Warsaw",
"place":
{
"attributes":{},
"bounding_box":
{
"coordinates":
[[
[-77.119759,38.791645],
[-76.909393,38.791645],
[-76.909393,38.995548],
[-77.119759,38.995548]
]],
"type":"Polygon"
},
"country":"United States",
"country_code":"US",
"full_name":"Washington, DC",
"id":"01fbe706f872cb32",
"name":"Washington",
"place_type":"city",
"url": "https://api.twitter.com/1/geo/id/01fbe706f872cb32.json"
}
}]
'''
}
response {
status OK()
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">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)</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">import java.util.Collection;
import java.util.Collections;
import java.util.function.Supplier;
import org.springframework.cloud.contract.spec.Contract;
import org.springframework.cloud.contract.verifier.util.ContractVerifierUtil;
class contract_rest implements Supplier&lt;Collection&lt;Contract&gt;&gt; {
@Override
public Collection&lt;Contract&gt; get() {
return Collections.singletonList(Contract.make(c -&gt; {
c.description("Some description");
c.name("some name");
c.priority(8);
c.ignored();
c.request(r -&gt; {
r.url("/foo", u -&gt; {
u.queryParameters(q -&gt; {
q.parameter("a", "b");
q.parameter("b", "c");
});
});
r.method(r.PUT());
r.headers(h -&gt; {
h.header("foo", r.value(r.client(r.regex("bar")), r.server("bar")));
h.header("fooReq", "baz");
});
r.body(ContractVerifierUtil.map().entry("foo", "bar"));
r.bodyMatchers(m -&gt; {
m.jsonPath("$.foo", m.byRegex("bar"));
});
});
c.response(r -&gt; {
r.fixedDelayMilliseconds(1000);
r.status(r.OK());
r.headers(h -&gt; {
h.header("foo2", r.value(r.server(r.regex("bar")), r.client("bar")));
h.header("foo3", r.value(r.server(r.execute("andMeToo($it)")),
r.client("foo33")));
h.header("fooRes", "baz");
});
r.body(ContractVerifierUtil.map().entry("foo2", "bar")
.entry("foo3", "baz").entry("nullValue", null));
r.bodyMatchers(m -&gt; {
m.jsonPath("$.foo2", m.byRegex("bar"));
m.jsonPath("$.foo3", m.byCommand("executeMe($it)"));
m.jsonPath("$.nullValue", m.byNull());
});
});
}));
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract
import org.springframework.cloud.contract.spec.withQueryParameters
contract {
name = "some name"
description = "Some description"
priority = 8
ignored = true
request {
url = url("/foo") withQueryParameters {
parameter("a", "b")
parameter("b", "c")
}
method = PUT
headers {
header("foo", value(client(regex("bar")), server("bar")))
header("fooReq", "baz")
}
body = body(mapOf("foo" to "bar"))
bodyMatchers {
jsonPath("$.foo", byRegex("bar"))
}
}
response {
delay = fixedMilliseconds(1000)
status = OK
headers {
header("foo2", value(server(regex("bar")), client("bar")))
header("foo3", value(server(execute("andMeToo(\$it)")), client("foo33")))
header("fooRes", "baz")
}
body = body(mapOf(
"foo" to "bar",
"foo3" to "baz",
"nullValue" to null
))
bodyMatchers {
jsonPath("$.foo2", byRegex("bar"))
jsonPath("$.foo3", byCommand("executeMe(\$it)"))
jsonPath("$.nullValue", byNull)
}
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
<div class="paragraph">
<p>You can compile contracts to stubs mapping by using the following standalone Maven command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>mvn org.springframework.cloud:spring-cloud-contract-maven-plugin:convert</pre>
</div>
</div>
</td>
</tr>
</table>
</div>
<div class="sect2">
<h3 id="contract-groovy"><a class="anchor" href="#contract-groovy"></a><a class="link" href="#contract-groovy">1.1. Contract DSL in Groovy</a></h3>
<div class="paragraph">
<p>If you are not familiar with Groovy, do not worry - you can use Java syntax in the
Groovy DSL files as well.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Remember that, inside the Groovy contract file, you have to provide the fully
qualified name to the <code>Contract</code> class and <code>make</code> static imports, such as
<code>org.springframework.cloud.spec.Contract.make { &#8230;&#8203; }</code>. You can also provide an import to
the <code>Contract</code> class (<code>import org.springframework.cloud.spec.Contract</code>) and then call
<code>Contract.make { &#8230;&#8203; }</code>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="contract-java"><a class="anchor" href="#contract-java"></a><a class="link" href="#contract-java">1.2. Contract DSL in Java</a></h3>
<div class="paragraph">
<p>To write a contract definition in Java, you need to create a class, that implements either the <code>Supplier&lt;Contract&gt;</code> interface for a single contract or <code>Supplier&lt;Collection&lt;Contract&gt;&gt;</code> for multiple contracts.</p>
</div>
<div class="paragraph">
<p>You can also write the contract definitions under <code>src/test/java</code> (e.g. <code>src/test/java/contracts</code>) so that you don&#8217;t have to modify the classpath of your project. In this case you&#8217;ll have to provide a new location of contract definitions to your Spring Cloud Contract plugin.</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">Maven</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml">&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;contractsDirectory&gt;src/test/java/contracts&lt;/contractsDirectory&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Gradle</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">contracts {
contractsDslDir = new File(project.rootDir, "src/test/java/contracts")
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="contract-kotlin"><a class="anchor" href="#contract-kotlin"></a><a class="link" href="#contract-kotlin">1.3. Contract DSL in Kotlin</a></h3>
<div class="paragraph">
<p>To get started with writing contracts in Kotlin you would need to start with a (newly created) Kotlin Script file (.kts).
Just like the with the Java DSL you can put your contracts in any directory of your choice.
The Maven and Gradle plugins will look at the <code>src/test/resources/contracts</code> directory by default.</p>
</div>
<div class="paragraph">
<p>You need to explicitly pass the the <code>spring-cloud-contract-spec-kotlin</code> dependency to your project plugin setup.</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">Maven</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml">&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;!-- some config --&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-spec-kotlin&lt;/artifactId&gt;
&lt;version&gt;${spring-cloud-contract.version}&lt;/version&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;/plugin&gt;
&lt;dependencies&gt;
&lt;!-- Remember to add this for the DSL support in the IDE and on the consumer side --&gt;
&lt;dependency&gt;
&lt;groupId&gt;org.springframework.cloud&lt;/groupId&gt;
&lt;artifactId&gt;spring-cloud-contract-spec-kotlin&lt;/artifactId&gt;
&lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;
&lt;/dependencies&gt;</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Gradle</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">buildscript {
repositories {
// ...
}
dependencies {
classpath "org.springframework.cloud:spring-cloud-contract-gradle-plugin:${scContractVersion}"
// remember to add this:
classpath "org.springframework.cloud:spring-cloud-contract-spec-kotlin:${scContractVersion}"
}
}
dependencies {
// ...
// Remember to add this for the DSL support in the IDE and on the consumer side
testImplementation "org.springframework.cloud:spring-cloud-contract-spec-kotlin"
}</code></pre>
</div>
</div>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Remember that, inside the Kotlin Script file, you have to provide the fully qualified name to the <code>ContractDSL</code> class.
Generally you would use its contract function like this: <code>org.springframework.cloud.contract.spec.ContractDsl.contract { &#8230;&#8203; }</code>.
You can also provide an import to the <code>contract</code> function (<code>import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract</code>) and then call <code>contract { &#8230;&#8203; }</code>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="contract-yml"><a class="anchor" href="#contract-yml"></a><a class="link" href="#contract-yml">1.4. Contract DSL in YML</a></h3>
<div class="paragraph">
<p>In order to see a schema of a YAML contract, you can check out the <a href="yml-schema.html">YML Schema</a> page.</p>
</div>
</div>
<div class="sect2">
<h3 id="contract-limitations"><a class="anchor" href="#contract-limitations"></a><a class="link" href="#contract-limitations">1.5. Limitations</a></h3>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
The support for verifying the size of JSON arrays is experimental. If you want
to turn it on, set the value of the following system property to <code>true</code>:
<code>spring.cloud.contract.verifier.assert.size</code>. By default, this feature is set to <code>false</code>.
You can also set the <code>assertJsonSize</code> property in the plugin configuration.
</td>
</tr>
</table>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
Because JSON structure can have any form, it can be impossible to parse it
properly when using the Groovy DSL and the <code>value(consumer(&#8230;&#8203;), producer(&#8230;&#8203;))</code> notation in <code>GString</code>. That
is why you should use the Groovy Map notation.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="contract-common-top-elements"><a class="anchor" href="#contract-common-top-elements"></a><a class="link" href="#contract-common-top-elements">1.6. Common Top-Level Elements</a></h3>
<div class="paragraph">
<p>The following sections describe the most common top-level elements:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#contract-dsl-description">Description</a></p>
</li>
<li>
<p><a href="#contract-dsl-name">Name</a></p>
</li>
<li>
<p><a href="#contract-dsl-ignoring-contracts">Ignoring Contracts</a></p>
</li>
<li>
<p><a href="#contract-dsl-in-progress">Contracts in Progress</a></p>
</li>
<li>
<p><a href="#contract-dsl-passing-values-from-files">Passing Values from Files</a></p>
</li>
</ul>
</div>
<div class="sect3">
<h4 id="contract-dsl-description"><a class="anchor" href="#contract-dsl-description"></a><a class="link" href="#contract-dsl-description">1.6.1. Description</a></h4>
<div class="paragraph">
<p>You can add a <code>description</code> to your contract. The description is arbitrary text. The
following code shows an example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy"> org.springframework.cloud.contract.spec.Contract.make {
description('''
given:
An input
when:
Sth happens
then:
Output
''')
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">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)</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Contract.make(c -&gt; {
c.description("Some description");
}));</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">contract {
description = """
given:
An input
when:
Sth happens
then:
Output
"""
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="contract-dsl-name"><a class="anchor" href="#contract-dsl-name"></a><a class="link" href="#contract-dsl-name">1.6.2. Name</a></h4>
<div class="paragraph">
<p>You can provide a name for your contract. Assume that you provided the following name:
<code>should register a user</code>. If you do so, the name of the autogenerated test is
<code>validate_should_register_a_user</code>. Also, the name of the stub in a WireMock stub is
<code>should_register_a_user.json</code>.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
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.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The following example shows how to add a name to a contract:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">org.springframework.cloud.contract.spec.Contract.make {
name("some_special_name")
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">name: some name</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Contract.make(c -&gt; {
c.name("some name");
}));</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">contract {
name = "some_special_name"
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="contract-dsl-ignoring-contracts"><a class="anchor" href="#contract-dsl-ignoring-contracts"></a><a class="link" href="#contract-dsl-ignoring-contracts">1.6.3. Ignoring Contracts</a></h4>
<div class="paragraph">
<p>If you want to ignore a contract, you can either set a value for ignored contracts in the
plugin configuration or set the <code>ignored</code> property on the contract itself. The following
example shows how to do so:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">org.springframework.cloud.contract.spec.Contract.make {
ignored()
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">ignored: true</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Contract.make(c -&gt; {
c.ignored();
}));</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">contract {
ignored = true
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="contract-dsl-in-progress"><a class="anchor" href="#contract-dsl-in-progress"></a><a class="link" href="#contract-dsl-in-progress">1.6.4. Contracts in Progress</a></h4>
<div class="paragraph">
<p>A contract in progress will not generate tests on the producer side, but will allow generation of stubs.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Use this feature with caution as it may lead to false positives. You generate stubs for your consumers to use without actually having the implementation in place!
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>If you want to set a contract in progress the following
example shows how to do so:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">org.springframework.cloud.contract.spec.Contract.make {
inProgress()
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">inProgress: true</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">Contract.make(c -&gt; {
c.inProgress();
}));</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">contract {
inProgress = true
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>You can set the value of the <code>failOnInProgress</code> Spring Cloud Contract plugin property to ensure that your build will break when at least one contract in progress remains in your sources.</p>
</div>
</div>
<div class="sect3">
<h4 id="contract-dsl-passing-values-from-files"><a class="anchor" href="#contract-dsl-passing-values-from-files"></a><a class="link" href="#contract-dsl-passing-values-from-files">1.6.5. Passing Values from Files</a></h4>
<div class="paragraph">
<p>Starting with version <code>1.2.0</code>, you can pass values from files. Assume that you have the
following resources in your project:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">└── src
    └── test
       └── resources
          └── contracts
    ├── readFromFile.groovy
    ├── request.json
    └── response.json</code></pre>
</div>
</div>
<div class="paragraph">
<p>Further assume that your contract is as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">/*
* Copyright 2013-2019 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
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())
}
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">request:
method: GET
url: /foo
bodyFromFile: request.json
response:
status: 200
bodyFromFile: response.json</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">import java.util.Collection;
import java.util.Collections;
import java.util.function.Supplier;
import org.springframework.cloud.contract.spec.Contract;
class contract_rest_from_file implements Supplier&lt;Collection&lt;Contract&gt;&gt; {
@Override
public Collection&lt;Contract&gt; get() {
return Collections.singletonList(Contract.make(c -&gt; {
c.request(r -&gt; {
r.url("/foo");
r.method(r.GET());
r.body(r.file("request.json"));
});
c.response(r -&gt; {
r.status(r.OK());
r.body(r.file("response.json"));
});
}));
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract
contract {
request {
url = url("/1")
method = PUT
headers {
contentType = APPLICATION_JSON
}
body = bodyFromFile("request.json")
}
response {
status = OK
body = bodyFromFile("response.json")
headers {
contentType = APPLICATION_JSON
}
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Further assume that the JSON files is as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">request.json</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{
"status": "REQUEST"
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">response.json</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">{
"status": "RESPONSE"
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>When test or stub generation takes place, the contents of the <code>request.json</code> and <code>response.json</code> files are 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.</p>
</div>
<div class="paragraph">
<p>If you need to pass the contents of a file in binary form,
you can use the <code>fileAsBytes</code> method in the coded DSL or a <code>bodyFromFileAsBytes</code> field in YAML.</p>
</div>
<div class="paragraph">
<p>The following example shows how to pass the contents of binary files:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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())
}
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">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</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">import java.util.Collection;
import java.util.Collections;
import java.util.function.Supplier;
import org.springframework.cloud.contract.spec.Contract;
class contract_rest_from_pdf implements Supplier&lt;Collection&lt;Contract&gt;&gt; {
@Override
public Collection&lt;Contract&gt; get() {
return Collections.singletonList(Contract.make(c -&gt; {
c.request(r -&gt; {
r.url("/1");
r.method(r.PUT());
r.body(r.fileAsBytes("request.pdf"));
r.headers(h -&gt; {
h.contentType(h.applicationOctetStream());
});
});
c.response(r -&gt; {
r.status(r.OK());
r.body(r.fileAsBytes("response.pdf"));
r.headers(h -&gt; {
h.contentType(h.applicationOctetStream());
});
});
}));
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract
contract {
request {
url = url("/1")
method = PUT
headers {
contentType = APPLICATION_OCTET_STREAM
}
body = bodyFromFileAsBytes("contracts/request.pdf")
}
response {
status = OK
body = bodyFromFileAsBytes("contracts/response.pdf")
headers {
contentType = APPLICATION_OCTET_STREAM
}
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
You should use this approach whenever you want to work with binary payloads,
both for HTTP and messaging.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="features-http"><a class="anchor" href="#features-http"></a><a class="link" href="#features-http">2. Contracts for HTTP</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Spring Cloud Contract lets you verify applications that use REST or HTTP as a
means of communication. Spring Cloud Contract verifies that, for a request that matches the
criteria from the <code>request</code> part of the contract, the server provides a response that is in
keeping with the <code>response</code> part of the contract. Subsequently, the contracts are used to
generate WireMock stubs that, for any request matching the provided criteria, provide a
suitable response.</p>
</div>
<div class="sect2">
<h3 id="contract-dsl-http-top-level-elements"><a class="anchor" href="#contract-dsl-http-top-level-elements"></a><a class="link" href="#contract-dsl-http-top-level-elements">2.1. HTTP Top-Level Elements</a></h3>
<div class="paragraph">
<p>You can call the following methods in the top-level closure of a contract definition:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>request</code>: Mandatory</p>
</li>
<li>
<p><code>response</code> : Mandatory</p>
</li>
<li>
<p><code>priority</code>: Optional</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The following example shows how to define an HTTP request contract:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">priority: 8
request:
...
response:
...</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">org.springframework.cloud.contract.spec.Contract.make(c -&gt; {
// Definition of HTTP request part of the contract
// (this can be a valid request or invalid depending
// on type of contract being specified).
c.request(r -&gt; {
r.method(r.GET());
r.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).
c.response(r -&gt; {
r.status(200);
// ...
});
// Contract priority, which can be used for overriding
// contracts (1 is highest). Priority is optional.
c.priority(1);
});</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">contract {
// 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 = 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 = OK
// ...
}
// Contract priority, which can be used for overriding
// contracts (1 is highest). Priority is optional.
priority = 1
}</code></pre>
</div>
</div>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
If you want to make your contract have a higher priority,
you need to pass a lower number to the <code>priority</code> tag or method. For example, a <code>priority</code> with
a value of <code>5</code> has higher priority than a <code>priority</code> with a value of <code>10</code>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="contract-dsl-request"><a class="anchor" href="#contract-dsl-request"></a><a class="link" href="#contract-dsl-request">2.2. HTTP Request</a></h3>
<div class="paragraph">
<p>The HTTP protocol requires only the method and the URL to be specified in a request. The
same information is mandatory in request definition of the contract.</p>
</div>
<div class="paragraph">
<p>The following example shows a contract for a request:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">method: PUT
url: /foo</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">org.springframework.cloud.contract.spec.Contract.make(c -&gt; {
c.request(r -&gt; {
// HTTP request method (GET/POST/PUT/DELETE).
r.method("GET");
// Path component of request URL is specified as follows.
r.urlPath("/users");
});
c.response(r -&gt; {
// ...
r.status(200);
});
});</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">contract {
request {
// HTTP request method (GET/POST/PUT/DELETE).
method = method("GET")
// Path component of request URL is specified as follows.
urlPath = path("/users")
}
response {
// ...
status = code(200)
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>You can specify an absolute rather than a relative <code>url</code>, but using <code>urlPath</code> is
the recommended way, as doing so makes the tests be host-independent.</p>
</div>
<div class="paragraph">
<p>The following example uses <code>url</code>:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">request:
method: PUT
urlPath: /foo</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">org.springframework.cloud.contract.spec.Contract.make(c -&gt; {
c.request(r -&gt; {
r.method("GET");
// Specifying `url` and `urlPath` in one contract is illegal.
r.url("http://localhost:8888/users");
});
c.response(r -&gt; {
// ...
r.status(200);
});
});</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">contract {
request {
method = GET
// Specifying `url` and `urlPath` in one contract is illegal.
url("http://localhost:8888/users")
}
response {
// ...
status = OK
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p><code>request</code> may contain query parameters, as the following example (which uses <code>urlPath</code>) shows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">request:
...
queryParameters:
a: b
b: c</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">org.springframework.cloud.contract.spec.Contract.make(c -&gt; {
c.request(r -&gt; {
// ...
r.method(r.GET());
r.urlPath("/users", u -&gt; {
// 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.
u.queryParameters(q -&gt; {
// If a simple literal is used as value
// default matcher function is used (equalTo)
q.parameter("limit", 100);
// `equalTo` function simply compares passed value
// using identity operator (==).
q.parameter("filter", r.equalTo("email"));
// `containing` function matches strings
// that contains passed substring.
q.parameter("gender",
r.value(r.consumer(r.containing("[mf]")),
r.producer("mf")));
// `matching` function tests parameter
// against passed regular expression.
q.parameter("offset",
r.value(r.consumer(r.matching("[0-9]+")),
r.producer(123)));
// `notMatching` functions tests if parameter
// does not match passed regular expression.
q.parameter("loginStartsWith",
r.value(r.consumer(r.notMatching(".{0,2}")),
r.producer(3)));
});
});
// ...
});
c.response(r -&gt; {
// ...
r.status(200);
});
});</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">contract {
request {
// ...
method = GET
// 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.
urlPath = path("/users") withQueryParameters {
// 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 = code(200)
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p><code>request</code> can contain additional request headers, as the following example shows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">request:
...
headers:
foo: bar
fooReq: baz</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">org.springframework.cloud.contract.spec.Contract.make(c -&gt; {
c.request(r -&gt; {
// ...
r.method(r.GET());
r.url("/foo");
// Each header is added in form `'Header-Name' : 'Header-Value'`.
// there are also some helper methods
r.headers(h -&gt; {
h.header("key", "value");
h.contentType(h.applicationJson());
});
// ...
});
c.response(r -&gt; {
// ...
r.status(200);
});
});</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">contract {
request {
// ...
method = GET
url = url("/foo")
// Each header is added in form `'Header-Name' : 'Header-Value'`.
// there are also some helper variables
headers {
header("key", "value")
contentType = APPLICATION_JSON
}
// ...
}
response {
// ...
status = OK
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p><code>request</code> may contain additional request cookies, as the following example shows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">request:
...
cookies:
foo: bar
fooReq: baz</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">org.springframework.cloud.contract.spec.Contract.make(c -&gt; {
c.request(r -&gt; {
// ...
r.method(r.GET());
r.url("/foo");
// Each Cookies is added in form `'Cookie-Key' : 'Cookie-Value'`.
// there are also some helper methods
r.cookies(ck -&gt; {
ck.cookie("key", "value");
ck.cookie("another_key", "another_value");
});
// ...
});
c.response(r -&gt; {
// ...
r.status(200);
});
});</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">contract {
request {
// ...
method = GET
url = 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 = code(200)
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p><code>request</code> may contain a request body, as the following example shows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">request:
...
body:
foo: bar</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">org.springframework.cloud.contract.spec.Contract.make(c -&gt; {
c.request(r -&gt; {
// ...
r.method(r.GET());
r.url("/foo");
// Currently only JSON format of request body is supported.
// Format will be determined from a header or body's content.
r.body("{ \"login\" : \"john\", \"name\": \"John The Contract\" }");
});
c.response(r -&gt; {
// ...
r.status(200);
});
});</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">contract {
request {
// ...
method = GET
url = url("/foo")
// Currently only JSON format of request body is supported.
// Format will be determined from a header or body's content.
body = body("{ \"login\" : \"john\", \"name\": \"John The Contract\" }")
}
response {
// ...
status = OK
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p><code>request</code> can contain multipart elements. To include multipart elements, use the
<code>multipart</code> method/section, as the following examples show:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">org.springframework.cloud.contract.spec.Contract contractDsl = org.springframework.cloud.contract.spec.Contract.make {
request {
method 'PUT'
url '/multipart'
headers {
contentType('multipart/form-data;boundary=AaB03x')
}
multipart(
// key (parameter name), value (parameter value) pair
formParameter: $(c(regex('".+"')), p('"formParameterValue"')),
someBooleanParameter: $(c(regex(anyBoolean())), p('true')),
// a named parameter (e.g. with `file` name) that represents file with
// `name` and `content`. You can also call `named("fileName", "fileContent")`
file: named(
// name of the file
name: $(c(regex(nonEmpty())), p('filename.csv')),
// content of the file
content: $(c(regex(nonEmpty())), p('file content')),
// content type for the part
contentType: $(c(regex(nonEmpty())), p('application/json')))
)
}
response {
status OK()
}
}
org.springframework.cloud.contract.spec.Contract contractDsl = org.springframework.cloud.contract.spec.Contract.make {
request {
method "PUT"
url "/multipart"
headers {
contentType('multipart/form-data;boundary=AaB03x')
}
multipart(
file: named(
name: value(stub(regex('.+')), test('file')),
content: value(stub(regex('.+')), test([100, 117, 100, 97] as byte[]))
)
)
}
response {
status 200
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">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</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">import java.util.Collection;
import java.util.Collections;
import java.util.HashMap;
import java.util.Map;
import java.util.function.Supplier;
import org.springframework.cloud.contract.spec.Contract;
import org.springframework.cloud.contract.spec.internal.DslProperty;
import org.springframework.cloud.contract.spec.internal.Request;
import org.springframework.cloud.contract.verifier.util.ContractVerifierUtil;
class contract_multipart implements Supplier&lt;Collection&lt;Contract&gt;&gt; {
private static Map&lt;String, DslProperty&gt; namedProps(Request r) {
Map&lt;String, DslProperty&gt; map = new HashMap&lt;&gt;();
// name of the file
map.put("name", r.$(r.c(r.regex(r.nonEmpty())), r.p("filename.csv")));
// content of the file
map.put("content", r.$(r.c(r.regex(r.nonEmpty())), r.p("file content")));
// content type for the part
map.put("contentType", r.$(r.c(r.regex(r.nonEmpty())), r.p("application/json")));
return map;
}
@Override
public Collection&lt;Contract&gt; get() {
return Collections.singletonList(Contract.make(c -&gt; {
c.request(r -&gt; {
r.method("PUT");
r.url("/multipart");
r.headers(h -&gt; {
h.contentType("multipart/form-data;boundary=AaB03x");
});
r.multipart(ContractVerifierUtil.map()
// key (parameter name), value (parameter value) pair
.entry("formParameter",
r.$(r.c(r.regex("\".+\"")),
r.p("\"formParameterValue\"")))
.entry("someBooleanParameter",
r.$(r.c(r.regex(r.anyBoolean())), r.p("true")))
// a named parameter (e.g. with `file` name) that represents file
// with
// `name` and `content`. You can also call `named("fileName",
// "fileContent")`
.entry("file", r.named(namedProps(r))));
});
c.response(r -&gt; {
r.status(r.OK());
});
}));
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract
contract {
request {
method = PUT
url = url("/multipart")
multipart {
field("formParameter", value(consumer(regex("\".+\"")), producer("\"formParameterValue\"")))
field("someBooleanParameter", value(consumer(anyBoolean), producer("true")))
field("file",
named(
// name of the file
value(consumer(regex(nonEmpty)), producer("filename.csv")),
// content of the file
value(consumer(regex(nonEmpty)), producer("file content")),
// content type for the part
value(consumer(regex(nonEmpty)), producer("application/json"))
)
)
}
headers {
contentType = "multipart/form-data;boundary=AaB03x"
}
}
response {
status = OK
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>In the preceding example, we define parameters in either of two ways:</p>
</div>
<div class="ulist">
<div class="title">Coded DSL</div>
<ul>
<li>
<p>Directly, by using the map notation, where the value can be a dynamic property (such as
<code>formParameter: $(consumer(&#8230;&#8203;), producer(&#8230;&#8203;))</code>).</p>
</li>
<li>
<p>By using the <code>named(&#8230;&#8203;)</code> method that lets you set a named parameter. A named parameter
can set a <code>name</code> and <code>content</code>. You can call it either by using a method with two arguments,
such as <code>named("fileName", "fileContent")</code>, or by using a map notation, such as
<code>named(name: "fileName", content: "fileContent")</code>.</p>
</li>
</ul>
</div>
<div class="ulist">
<div class="title">YAML</div>
<ul>
<li>
<p>The multipart parameters are set in the <code>multipart.params</code> section.</p>
</li>
<li>
<p>The named parameters (the <code>fileName</code> and <code>fileContent</code> for a given parameter name)
can be set in the <code>multipart.named</code> section. That section contains
the <code>paramName</code> (the name of the parameter), <code>fileName</code> (the name of the file),
<code>fileContent</code> (the content of the file) fields.</p>
</li>
<li>
<p>The dynamic bits can be set via the <code>matchers.multipart</code> section.</p>
<div class="ulist">
<ul>
<li>
<p>For parameters, use the <code>params</code> section, which can accept
<code>regex</code> or a <code>predefined</code> regular expression.</p>
</li>
<li>
<p>for named params, use the <code>named</code> section where first you
define the parameter name with <code>paramName</code>. Then you can pass the
parametrization of either <code>fileName</code> or <code>fileContent</code> in a
<code>regex</code> or in a <code>predefined</code> regular expression.</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
<div class="paragraph">
<p>From the contract in the preceding example, the generated test and stubs look as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">Test</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">// 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);</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Stub</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json"> '''
{
"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" ]
}
}
'''</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="contract-dsl-response"><a class="anchor" href="#contract-dsl-response"></a><a class="link" href="#contract-dsl-response">2.3. HTTP Response</a></h3>
<div class="paragraph">
<p>The response must contain an HTTP status code and may contain other information. The
following code shows an example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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()
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">response:
...
status: 200</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">org.springframework.cloud.contract.spec.Contract.make(c -&gt; {
c.request(r -&gt; {
// ...
r.method(r.GET());
r.url("/foo");
});
c.response(r -&gt; {
// Status code sent by the server
// in response to request specified above.
r.status(r.OK());
});
});</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">contract {
request {
// ...
method = GET
url =url("/foo")
}
response {
// Status code sent by the server
// in response to request specified above.
status = OK
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Besides status, the response may contain headers, cookies, and a body, which are
specified the same way as in the request (see <a href="#contract-dsl-request">HTTP Request</a>).</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
In the Groovy DSL, you can reference the <code>org.springframework.cloud.contract.spec.internal.HttpStatus</code>
methods to provide a meaningful status instead of a digit. For example, you can call
<code>OK()</code> for a status <code>200</code> or <code>BAD_REQUEST()</code> for <code>400</code>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="contract-dsl-dynamic-properties"><a class="anchor" href="#contract-dsl-dynamic-properties"></a><a class="link" href="#contract-dsl-dynamic-properties">2.4. Dynamic properties</a></h3>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>For the 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
<code>bodyMatchers</code>.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Before 2.0.0, these were set by using <code>testMatchers</code> and <code>stubMatchers</code>.
See the <a href="https://github.com/spring-cloud/spring-cloud-contract/wiki/Spring-Cloud-Contract-2.0-Migration-Guide">migration guide</a> for more information.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>For YAML, you can use only the <code>matchers</code> section.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Entries inside the <code>matchers</code> must reference existing elements of the payload. For more information check this <a href="https://github.com/spring-cloud/spring-cloud-contract/issues/722">issue</a>.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="contract-dsl-dynamic-properties-in-body"><a class="anchor" href="#contract-dsl-dynamic-properties-in-body"></a><a class="link" href="#contract-dsl-dynamic-properties-in-body">2.4.1. Dynamic Properties inside the Body</a></h4>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
This section is valid only for the Coded DSL (Groovy, Java etc.). Check out the
<a href="#contract-dsl-matchers">Dynamic Properties in the Matchers Sections</a> section for YAML examples of a similar feature.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>You can set the properties inside the body either with the <code>value</code> method or, if you use
the Groovy map notation, with <code>$()</code>. The following example shows how to set dynamic
properties with the value method:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">value</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">value(consumer(...), producer(...))
value(c(...), p(...))
value(stub(...), test(...))
value(client(...), server(...))</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">$</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">$(consumer(...), producer(...))
$(c(...), p(...))
$(stub(...), test(...))
$(client(...), server(...))</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Both approaches work equally well. The <code>stub</code> and <code>client</code> methods are aliases over the <code>consumer</code>
method. Subsequent sections take a closer look at what you can do with those values.</p>
</div>
</div>
<div class="sect3">
<h4 id="contract-dsl-regex"><a class="anchor" href="#contract-dsl-regex"></a><a class="link" href="#contract-dsl-regex">2.4.2. Regular Expressions</a></h4>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
This section is valid only for Groovy DSL. Check out the
<a href="#contract-dsl-matchers">Dynamic Properties in the Matchers Sections</a> section for YAML examples of a similar feature.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>You can use regular expressions to write your requests in the 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 tests and your server-side tests.</p>
</div>
<div class="paragraph">
<p>Make sure that regex matches a whole region of a sequence, as, internally, a call to
<a href="https://docs.oracle.com/javase/8/docs/api/java/util/regex/Matcher.html#matches"><code>Pattern.matches()</code></a>
is called. For instance, <code>abc</code> does not match <code>aabc</code>, but <code>.abc</code> does.
There are several additional <a href="#contract-dsl-regex-limitations">known limitations</a> as well.</p>
</div>
<div class="paragraph">
<p>The following example shows how to use regular expressions to write a request:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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'
}
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">org.springframework.cloud.contract.spec.Contract.make(c -&gt; {
c.request(r -&gt; {
r.method("GET");
r.url(r.$(r.consumer(r.regex("\\/[0-9]{2}")), r.producer("/12")));
});
c.response(r -&gt; {
r.status(r.OK());
r.body(ContractVerifierUtil.map().entry("id", r.$(r.anyNumber()))
.entry("surname", r.$(r.consumer("Kowalsky"),
r.producer(r.regex("[a-zA-Z]+")))));
r.headers(h -&gt; {
h.header("Content-Type", "text/plain");
});
});
});</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">contract {
request {
method = method("GET")
url = url(v(consumer(regex("\\/[0-9]{2}")), producer("/12")))
}
response {
status = OK
body(mapOf(
"id" to v(anyNumber),
"surname" to v(consumer("Kowalsky"), producer(regex("[a-zA-Z]+")))
))
headers {
header("Content-Type", "text/plain")
}
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>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 for Groovy:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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")
}
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the preceding example, the opposite side of the communication has the respective data
generated for request and response.</p>
</div>
<div class="paragraph">
<p>Spring Cloud Contract comes with a series of predefined regular expressions that you can
use in your contracts, as the following example shows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">public static RegexProperty onlyAlphaUnicode() {
return new RegexProperty(ONLY_ALPHA_UNICODE).asString();
}
public static RegexProperty alphaNumeric() {
return new RegexProperty(ALPHA_NUMERIC).asString();
}
public static RegexProperty number() {
return new RegexProperty(NUMBER).asDouble();
}
public static RegexProperty positiveInt() {
return new RegexProperty(POSITIVE_INT).asInteger();
}
public static RegexProperty anyBoolean() {
return new RegexProperty(TRUE_OR_FALSE).asBooleanType();
}
public static RegexProperty anInteger() {
return new RegexProperty(INTEGER).asInteger();
}
public static RegexProperty aDouble() {
return new RegexProperty(DOUBLE).asDouble();
}
public static RegexProperty ipAddress() {
return new RegexProperty(IP_ADDRESS).asString();
}
public static RegexProperty hostname() {
return new RegexProperty(HOSTNAME_PATTERN).asString();
}
public static RegexProperty email() {
return new RegexProperty(EMAIL).asString();
}
public static RegexProperty url() {
return new RegexProperty(URL).asString();
}
public static RegexProperty httpsUrl() {
return new RegexProperty(HTTPS_URL).asString();
}
public static RegexProperty uuid() {
return new RegexProperty(UUID).asString();
}
public static RegexProperty isoDate() {
return new RegexProperty(ANY_DATE).asString();
}
public static RegexProperty isoDateTime() {
return new RegexProperty(ANY_DATE_TIME).asString();
}
public static RegexProperty isoTime() {
return new RegexProperty(ANY_TIME).asString();
}
public static RegexProperty iso8601WithOffset() {
return new RegexProperty(ISO8601_WITH_OFFSET).asString();
}
public static RegexProperty nonEmpty() {
return new RegexProperty(NON_EMPTY).asString();
}
public static RegexProperty nonBlank() {
return new RegexProperty(NON_BLANK).asString();
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In your contract, you can use it as follows (example for the Groovy DSL):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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'))}]"
)
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>To make matters even simpler, you can use a set of predefined objects that automatically
assume that you want a regular expression to be passed.
All of those methods start with the <code>any</code> prefix, as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">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);</code></pre>
</div>
</div>
<div class="paragraph">
<p>The following example shows how you can reference those methods:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Contract contractDsl = Contract.make {
name "foo"
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'))
])
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">contract {
name = "foo"
label = "trigger_event"
input {
triggeredBy = "toString()"
}
outputMessage {
sentTo = sentTo("topic.rateablequote")
body(mapOf(
"alpha" to v(anyAlphaUnicode),
"number" to v(anyNumber),
"anInteger" to v(anyInteger),
"positiveInt" to v(anyPositiveInt),
"aDouble" to v(anyDouble),
"aBoolean" to v(aBoolean),
"ip" to v(anyIpAddress),
"hostname" to v(anyAlphaUnicode),
"email" to v(anyEmail),
"url" to v(anyUrl),
"httpsUrl" to v(anyHttpsUrl),
"uuid" to v(anyUuid),
"date" to v(anyDate),
"dateTime" to v(anyDateTime),
"time" to v(anyTime),
"iso8601WithOffset" to v(anyIso8601WithOffset),
"nonBlankString" to v(anyNonBlankString),
"nonEmptyString" to v(anyNonEmptyString),
"anyOf" to v(anyOf('foo', 'bar'))
))
headers {
header("Content-Type", "text/plain")
}
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="contract-dsl-regex-limitations"><a class="anchor" href="#contract-dsl-regex-limitations"></a><a class="link" href="#contract-dsl-regex-limitations">Limitations</a></h5>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
Due to certain limitations of the <code>Xeger</code> library that generates a string out of
a regex, do not use the <code>$</code> and <code>^</code> signs in your regex if you rely on automatic
generation. See <a href="https://github.com/spring-cloud/spring-cloud-contract/issues/899">Issue 899</a>.
</td>
</tr>
</table>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
Do not use a <code>LocalDate</code> instance as a value for <code>$</code> (for example, <code>$(consumer(LocalDate.now()))</code>).
It causes a <code>java.lang.StackOverflowError</code>. Use <code>$(consumer(LocalDate.now().toString()))</code> instead.
See <a href="https://github.com/spring-cloud/spring-cloud-contract/issues/900">Issue 900</a>.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect3">
<h4 id="contract-dsl-optional-params"><a class="anchor" href="#contract-dsl-optional-params"></a><a class="link" href="#contract-dsl-optional-params">2.4.3. Passing Optional Parameters</a></h4>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
This section is valid only for Groovy DSL. Check out the
<a href="#contract-dsl-matchers">Dynamic Properties in the Matchers Sections</a> section for YAML examples of a similar feature.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>You can provide optional parameters in your contract. However, you can provide
optional parameters only for the following:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The STUB side of the Request</p>
</li>
<li>
<p>The TEST side of the Response</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The following example shows how to provide optional parameters:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">org.springframework.cloud.contract.spec.Contract.make {
priority 1
name "optionals"
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('https://partners.com'))
)
}
response {
status 404
headers {
header 'Content-Type': 'application/json'
}
body(
code: value(consumer("123123"), producer(optional("123123")))
)
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">org.springframework.cloud.contract.spec.Contract.make(c -&gt; {
c.priority(1);
c.name("optionals");
c.request(r -&gt; {
r.method("POST");
r.url("/users/password");
r.headers(h -&gt; {
h.contentType(h.applicationJson());
});
r.body(ContractVerifierUtil.map()
.entry("email",
r.$(r.consumer(r.optional(r.regex(r.email()))),
r.producer("abc@abc.com")))
.entry("callback_url", r.$(r.consumer(r.regex(r.hostname())),
r.producer("https://partners.com"))));
});
c.response(r -&gt; {
r.status(404);
r.headers(h -&gt; {
h.header("Content-Type", "application/json");
});
r.body(ContractVerifierUtil.map().entry("code", r.value(
r.consumer("123123"), r.producer(r.optional("123123")))));
});
});</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">contract { c -&gt;
priority = 1
name = "optionals"
request {
method = POST
url = url("/users/password")
headers {
contentType = APPLICATION_JSON
}
body = body(mapOf(
"email" to v(consumer(optional(regex(email))), producer("abc@abc.com")),
"callback_url" to v(consumer(regex(hostname)), producer("https://partners.com"))
))
}
response {
status = NOT_FOUND
headers {
header("Content-Type", "application/json")
}
body(mapOf(
"code" to value(consumer("123123"), producer(optional("123123")))
))
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>By wrapping a part of the body with the <code>optional()</code> method, you create a regular
expression that must be present 0 or more times.</p>
</div>
<div class="paragraph">
<p>If you use Spock, the following test would be generated from the previous example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy"> """\
package com.example
import com.jayway.jsonpath.DocumentContext
import com.jayway.jsonpath.JsonPath
import spock.lang.Specification
import io.restassured.module.mockmvc.specification.MockMvcRequestSpecification
import io.restassured.response.ResponseOptions
import static org.springframework.cloud.contract.verifier.assertion.SpringCloudContractAssertions.assertThat
import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.*
import static com.toomuchcoding.jsonassert.JsonAssertion.assertThatJson
import static io.restassured.module.mockmvc.RestAssuredMockMvc.*
@SuppressWarnings("rawtypes")
class FooSpec extends Specification {
\tdef validate_optionals() throws Exception {
\t\tgiven:
\t\t\tMockMvcRequestSpecification request = given()
\t\t\t\t\t.header("Content-Type", "application/json")
\t\t\t\t\t.body('''{"email":"abc@abc.com","callback_url":"https://partners.com"}''')
\t\twhen:
\t\t\tResponseOptions response = given().spec(request)
\t\t\t\t\t.post("/users/password")
\t\tthen:
\t\t\tresponse.statusCode() == 404
\t\t\tresponse.header("Content-Type") == 'application/json'
\t\tand:
\t\t\tDocumentContext parsedJson = JsonPath.parse(response.body.asString())
\t\t\tassertThatJson(parsedJson).field("['code']").matches("(123123)?")
\t}
}
"""</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The following stub would also be generated:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy"> '''
{
"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
}
'''</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="contract-dsl-custom-methods"><a class="anchor" href="#contract-dsl-custom-methods"></a><a class="link" href="#contract-dsl-custom-methods">2.4.4. Executing Custom Methods on the Server Side</a></h4>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
This section is valid only for Groovy DSL. Check out the
<a href="#contract-dsl-matchers">Dynamic Properties in the Matchers Sections</a> section for YAML examples of a similar feature.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>You can define a method call that runs on the server side during the test. Such a
method can be added to the class defined as <code>baseClassForTests</code> in the configuration. The
following code shows an example of the contract portion of the test case:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">method GET()</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">r.method(r.GET());</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">method = GET</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The following code shows the base class portion of the test case:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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
}
}</code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
You cannot use both a <code>String</code> and <code>execute</code> to perform concatenation. For
example, calling <code>header('Authorization', 'Bearer ' + execute('authToken()'))</code> leads to
improper results. Instead, call <code>header('Authorization', execute('authToken()'))</code> and
ensure that the <code>authToken()</code> method returns everything you need.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The type of the object read from the JSON can be one of the following, depending on the
JSON path:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>String</code>: If you point to a <code>String</code> value in the JSON.</p>
</li>
<li>
<p><code>JSONArray</code>: If you point to a <code>List</code> in the JSON.</p>
</li>
<li>
<p><code>Map</code>: If you point to a <code>Map</code> in the JSON.</p>
</li>
<li>
<p><code>Number</code>: If you point to <code>Integer</code>, <code>Double</code>, and other numeric type in the JSON.</p>
</li>
<li>
<p><code>Boolean</code>: If you point to a <code>Boolean</code> in the JSON.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In the request part of the contract, you can specify that the <code>body</code> should be taken from
a method.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
You must provide both the consumer and the producer side. The <code>execute</code> part
is applied for the whole body, not for parts of it.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The following example shows how to read an object from JSON:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Contract contractDsl = Contract.make {
request {
method 'GET'
url '/something'
body(
$(c('foo'), p(execute('hashCode()')))
)
}
response {
status OK()
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The preceding example results in calling the <code>hashCode()</code> method in the request body.
It should resemble the following code:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">// given:
MockMvcRequestSpecification request = given()
.body(hashCode());
// when:
ResponseOptions response = given().spec(request)
.get("/something");
// then:
assertThat(response.statusCode()).isEqualTo(200);</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="contract-dsl-referencing-request-from-response"><a class="anchor" href="#contract-dsl-referencing-request-from-response"></a><a class="link" href="#contract-dsl-referencing-request-from-response">2.4.5. Referencing the Request from the Response</a></h4>
<div class="paragraph">
<p>The best situation is to provide fixed values, but sometimes you need to reference a
request in your response.</p>
</div>
<div class="paragraph">
<p>If you write contracts in the Groovy DSL, you can use the <code>fromRequest()</code> method, which lets
you reference a bunch of elements from the HTTP request. You can use the following
options:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>fromRequest().url()</code>: Returns the request URL and query parameters.</p>
</li>
<li>
<p><code>fromRequest().query(String key)</code>: Returns the first query parameter with a given name.</p>
</li>
<li>
<p><code>fromRequest().query(String key, int index)</code>: Returns the nth query parameter with a
given name.</p>
</li>
<li>
<p><code>fromRequest().path()</code>: Returns the full path.</p>
</li>
<li>
<p><code>fromRequest().path(int index)</code>: Returns the nth path element.</p>
</li>
<li>
<p><code>fromRequest().header(String key)</code>: Returns the first header with a given name.</p>
</li>
<li>
<p><code>fromRequest().header(String key, int index)</code>: Returns the nth header with a given name.</p>
</li>
<li>
<p><code>fromRequest().body()</code>: Returns the full request body.</p>
</li>
<li>
<p><code>fromRequest().body(String jsonPath)</code>: Returns the element from the request that
matches the JSON Path.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>If you use the YAML contract definition or the Java one, you have to use the
<a href="https://handlebarsjs.com/">Handlebars</a> <code>{{{ }}}</code> notation with custom Spring Cloud Contract
functions to achieve this. In that case, you can use the following options:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>{{{ request.url }}}</code>: Returns the request URL and query parameters.</p>
</li>
<li>
<p><code>{{{ request.query.key.[index] }}}</code>: Returns the nth query parameter with a given name.
For example, for a key of <code>thing</code>, the first entry is <code>{{{ request.query.thing.[0] }}}</code></p>
</li>
<li>
<p><code>{{{ request.path }}}</code>: Returns the full path.</p>
</li>
<li>
<p><code>{{{ request.path.[index] }}}</code>: Returns the nth path element. For example,
the first entry is <code>`</code>{{{ request.path.[0] }}}</p>
</li>
<li>
<p><code>{{{ request.headers.key }}}</code>: Returns the first header with a given name.</p>
</li>
<li>
<p><code>{{{ request.headers.key.[index] }}}</code>: Returns the nth header with a given name.</p>
</li>
<li>
<p><code>{{{ request.body }}}</code>: Returns the full request body.</p>
</li>
<li>
<p><code>{{{ jsonpath this 'your.json.path' }}}</code>: Returns the element from the request that
matches the JSON Path. For example, for a JSON path of <code>$.here</code>, use <code>{{{ jsonpath this '$.here' }}}</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Consider the following contract:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Contract contractDsl = Contract.make {
request {
method 'GET'
url('/api/v1/xxxx') {
queryParameters {
parameter('foo', 'bar')
parameter('foo', 'bar2')
}
}
headers {
header(authorization(), 'secret')
header(authorization(), 'secret2')
}
body(foo: 'bar', baz: 5)
}
response {
status OK()
headers {
header(authorization(), "foo ${fromRequest().header(authorization())} bar")
}
body(
url: fromRequest().url(),
path: fromRequest().path(),
pathIndex: fromRequest().path(1),
param: fromRequest().query('foo'),
paramIndex: fromRequest().query('foo', 1),
authorization: fromRequest().header('Authorization'),
authorization2: fromRequest().header('Authorization', 1),
fullBody: fromRequest().body(),
responseFoo: fromRequest().body('$.foo'),
responseBaz: fromRequest().body('$.baz'),
responseBaz2: "Bla bla ${fromRequest().body('$.foo')} bla bla",
rawUrl: fromRequest().rawUrl(),
rawPath: fromRequest().rawPath(),
rawPathIndex: fromRequest().rawPath(1),
rawParam: fromRequest().rawQuery('foo'),
rawParamIndex: fromRequest().rawQuery('foo', 1),
rawAuthorization: fromRequest().rawHeader('Authorization'),
rawAuthorization2: fromRequest().rawHeader('Authorization', 1),
rawResponseFoo: fromRequest().rawBody('$.foo'),
rawResponseBaz: fromRequest().rawBody('$.baz'),
rawResponseBaz2: "Bla bla ${fromRequest().rawBody('$.foo')} bla bla"
)
}
}
Contract contractDsl = Contract.make {
request {
method 'GET'
url('/api/v1/xxxx') {
queryParameters {
parameter('foo', 'bar')
parameter('foo', 'bar2')
}
}
headers {
header(authorization(), 'secret')
header(authorization(), 'secret2')
}
body(foo: "bar", baz: 5)
}
response {
status OK()
headers {
contentType(applicationJson())
}
body('''
{
"responseFoo": "{{{ jsonPath request.body '$.foo' }}}",
"responseBaz": {{{ jsonPath request.body '$.baz' }}},
"responseBaz2": "Bla bla {{{ jsonPath request.body '$.foo' }}} bla bla"
}
'''.toString())
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">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"</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">package contracts.beer.rest;
import java.util.function.Supplier;
import org.springframework.cloud.contract.spec.Contract;
import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.map;
class shouldReturnStatsForAUser implements Supplier&lt;Contract&gt; {
@Override
public Contract get() {
return Contract.make(c -&gt; {
c.request(r -&gt; {
r.method("POST");
r.url("/stats");
r.body(map().entry("name", r.anyAlphaUnicode()));
r.headers(h -&gt; {
h.contentType(h.applicationJson());
});
});
c.response(r -&gt; {
r.status(r.OK());
r.body(map()
.entry("text",
"Dear {{{jsonPath request.body '$.name'}}} thanks for your interested in drinking beer")
.entry("quantity", r.$(r.c(5), r.p(r.anyNumber()))));
r.headers(h -&gt; {
h.contentType(h.applicationJson());
});
});
});
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">package contracts.beer.rest
import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract
contract {
request {
method = method("POST")
url = url("/stats")
body(mapOf(
"name" to anyAlphaUnicode
))
headers {
contentType = APPLICATION_JSON
}
}
response {
status = OK
body(mapOf(
"text" to "Don't worry ${fromRequest().body("$.name")} thanks for your interested in drinking beer",
"quantity" to v(c(5), p(anyNumber))
))
headers {
contentType = fromRequest().header(CONTENT_TYPE)
}
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Running a JUnit test generation leads to a test that resembles the following example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">// 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");</code></pre>
</div>
</div>
<div class="paragraph">
<p>As you can see, elements from the request have been properly referenced in the response.</p>
</div>
<div class="paragraph">
<p>The generated WireMock stub should resemble the following example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{
"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" ]
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Sending a request such as the one presented in the <code>request</code> part of the contract results
in sending the following response body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{
"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"
}</code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
This feature works only with WireMock versions greater than or equal
to 2.5.1. The Spring Cloud Contract Verifier uses WireMock&#8217;s
<code>response-template</code> response transformer. It uses Handlebars to convert the Mustache <code>{{{ }}}</code> templates into
proper values. Additionally, it registers two helper functions:
</td>
</tr>
</table>
</div>
<div class="ulist">
<ul>
<li>
<p><code>escapejsonbody</code>: Escapes the request body in a format that can be embedded in a JSON.</p>
</li>
<li>
<p><code>jsonpath</code>: For a given parameter, find an object in the request body.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="contract-dsl-matchers"><a class="anchor" href="#contract-dsl-matchers"></a><a class="link" href="#contract-dsl-matchers">2.4.6. Dynamic Properties in the Matchers Sections</a></h4>
<div class="paragraph">
<p>If you work with <a href="https://docs.pact.io/">Pact</a>, 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.</p>
</div>
<div class="paragraph">
<p>You can use the <code>bodyMatchers</code> section for two reasons:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Define the dynamic values that should end up in a stub.
You can set it in the <code>request</code> or <code>inputMessage</code> part of your contract.</p>
</li>
<li>
<p>Verify the result of your test.
This section is present in the <code>response</code> or <code>outputMessage</code> side of the
contract.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Currently, Spring Cloud Contract Verifier supports only JSON path-based matchers with the
following matching possibilities:</p>
</div>
<div class="sect4">
<h5 id="coded-dsl"><a class="anchor" href="#coded-dsl"></a><a class="link" href="#coded-dsl">Coded DSL</a></h5>
<div class="ulist">
<ul>
<li>
<p>For the stubs (in tests on the consumer&#8217;s side):</p>
<div class="ulist">
<ul>
<li>
<p><code>byEquality()</code>: The value taken from the consumer&#8217;s request in the provided JSON path must be
equal to the value provided in the contract.</p>
</li>
<li>
<p><code>byRegex(&#8230;&#8203;)</code>: The value taken from the consumer&#8217;s request in the provided JSON path must
match the regex. You can also pass the type of the expected matched value (for example, <code>asString()</code>, <code>asLong()</code>, and so on).</p>
</li>
<li>
<p><code>byDate()</code>: The value taken from the consumer&#8217;s request in the provided JSON path must
match the regex for an ISO Date value.</p>
</li>
<li>
<p><code>byTimestamp()</code>: The value taken from the consumer&#8217;s request in the provided JSON path must
match the regex for an ISO DateTime value.</p>
</li>
<li>
<p><code>byTime()</code>: The value taken from the consumer&#8217;s request in the provided JSON path must
match the regex for an ISO Time value.</p>
</li>
</ul>
</div>
</li>
<li>
<p>For the verification (in generated tests on the Producer&#8217;s side):</p>
<div class="ulist">
<ul>
<li>
<p><code>byEquality()</code>: The value taken from the producer&#8217;s response in the provided JSON path must be
equal to the provided value in the contract.</p>
</li>
<li>
<p><code>byRegex(&#8230;&#8203;)</code>: The value taken from the producer&#8217;s response in the provided JSON path must
match the regex.</p>
</li>
<li>
<p><code>byDate()</code>: The value taken from the producer&#8217;s response in the provided JSON path must match
the regex for an ISO Date value.</p>
</li>
<li>
<p><code>byTimestamp()</code>: The value taken from the producer&#8217;s response in the provided JSON path must
match the regex for an ISO DateTime value.</p>
</li>
<li>
<p><code>byTime()</code>: The value taken from the producer&#8217;s response in the provided JSON path must match
the regex for an ISO Time value.</p>
</li>
<li>
<p><code>byType()</code>: The value taken from the producer&#8217;s response in the provided JSON path needs to be
of the same type as the type defined in the body of the response in the contract.
<code>byType</code> can take a closure, in which you can set <code>minOccurrence</code> and <code>maxOccurrence</code>. 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 <code>byCommand(&#8230;&#8203;)</code> <code>testMatcher</code>.</p>
</li>
<li>
<p><code>byCommand(&#8230;&#8203;)</code>: The value taken from the producer&#8217;s response in the provided JSON path is
passed as an input to the custom method that you provide. For example,
<code>byCommand('thing($it)')</code> results in calling a <code>thing</code> 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:</p>
<div class="ulist">
<ul>
<li>
<p><code>String</code>: If you point to a <code>String</code> value.</p>
</li>
<li>
<p><code>JSONArray</code>: If you point to a <code>List</code>.</p>
</li>
<li>
<p><code>Map</code>: If you point to a <code>Map</code>.</p>
</li>
<li>
<p><code>Number</code>: If you point to <code>Integer</code>, <code>Double</code>, or another kind of number.</p>
</li>
<li>
<p><code>Boolean</code>: If you point to a <code>Boolean</code>.</p>
</li>
</ul>
</div>
</li>
<li>
<p><code>byNull()</code>: The value taken from the response in the provided JSON path must be null.</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="yaml"><a class="anchor" href="#yaml"></a><a class="link" href="#yaml">YAML</a></h5>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
See the Groovy section for detailed explanation of
what the types mean.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>For YAML, the structure of a matcher resembles the following example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">- path: $.thing1
type: by_regex
value: thing2
regexType: as_string</code></pre>
</div>
</div>
<div class="paragraph">
<p>Alternatively, if you want to use one of the predefined regular expressions
<code>[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]</code>, you can use something similar to the following example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">- path: $.thing1
type: by_regex
predefined: only_alpha_unicode</code></pre>
</div>
</div>
<div class="paragraph">
<p>The following list shows the allowed list of <code>type</code> values:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>For <code>stubMatchers</code>:</p>
<div class="ulist">
<ul>
<li>
<p><code>by_equality</code></p>
</li>
<li>
<p><code>by_regex</code></p>
</li>
<li>
<p><code>by_date</code></p>
</li>
<li>
<p><code>by_timestamp</code></p>
</li>
<li>
<p><code>by_time</code></p>
</li>
<li>
<p><code>by_type</code></p>
<div class="ulist">
<ul>
<li>
<p>Two additional fields (<code>minOccurrence</code> and <code>maxOccurrence</code>) are accepted.</p>
</li>
</ul>
</div>
</li>
</ul>
</div>
</li>
<li>
<p>For <code>testMatchers</code>:</p>
<div class="ulist">
<ul>
<li>
<p><code>by_equality</code></p>
</li>
<li>
<p><code>by_regex</code></p>
</li>
<li>
<p><code>by_date</code></p>
</li>
<li>
<p><code>by_timestamp</code></p>
</li>
<li>
<p><code>by_time</code></p>
</li>
<li>
<p><code>by_type</code></p>
<div class="ulist">
<ul>
<li>
<p>Two additional fields (<code>minOccurrence</code> and <code>maxOccurrence</code>) are accepted.</p>
</li>
</ul>
</div>
</li>
<li>
<p><code>by_command</code></p>
</li>
<li>
<p><code>by_null</code></p>
</li>
</ul>
</div>
</li>
</ul>
</div>
<div class="paragraph">
<p>You can also define which type the regular expression corresponds to in the <code>regexType</code>
field. The following list shows the allowed regular expression types:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>as_integer</code></p>
</li>
<li>
<p><code>as_double</code></p>
</li>
<li>
<p><code>as_float</code></p>
</li>
<li>
<p><code>as_long</code></p>
</li>
<li>
<p><code>as_short</code></p>
</li>
<li>
<p><code>as_boolean</code></p>
</li>
<li>
<p><code>as_string</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Consider the following example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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}").asInteger())
jsonPath('$.duck', byEquality())
jsonPath('$.alpha', byRegex(onlyAlphaUnicode()).asString())
jsonPath('$.alpha', byEquality())
jsonPath('$.number', byRegex(number()).asInteger())
jsonPath('$.aBoolean', byRegex(anyBoolean()).asBooleanType())
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}").asInteger())
// asserts the jsonpath value against the provided value
jsonPath('$.duck', byEquality())
// asserts the jsonpath value against some default regex
jsonPath('$.alpha', byRegex(onlyAlphaUnicode()).asString())
jsonPath('$.alpha', byEquality())
jsonPath('$.number', byRegex(number()).asInteger())
jsonPath('$.positiveInteger', byRegex(anInteger()).asInteger())
jsonPath('$.negativeInteger', byRegex(anInteger()).asInteger())
jsonPath('$.positiveDecimalNumber', byRegex(aDouble()).asDouble())
jsonPath('$.negativeDecimalNumber', byRegex(aDouble()).asDouble())
jsonPath('$.aBoolean', byRegex(anyBoolean()).asBooleanType())
// 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}'))))
}
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">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</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>In the preceding example, you can see the dynamic portions of the contract in the
<code>matchers</code> sections. For the request part, you can see that, for all fields but
<code>valueWithoutAMatcher</code>, the values of the regular expressions that the stub should
contain are explicitly set. For the <code>valueWithoutAMatcher</code>, the verification takes place
in the same way as without the use of matchers. In that case, the test performs an
equality check.</p>
</div>
<div class="paragraph">
<p>For the response side in the <code>bodyMatchers</code> section, we define the dynamic parts in a
similar manner. The only difference is that the <code>byType</code> 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):</p>
</div>
<div class="ulist">
<ul>
<li>
<p>For <code>$.valueWithTypeMatch</code>, the engine checks whether the type is the same.</p>
</li>
<li>
<p>For <code>$.valueWithMin</code>, the engine checks the type and asserts whether the size is greater
than or equal to the minimum occurrence.</p>
</li>
<li>
<p>For <code>$.valueWithMax</code>, the engine checks the type and asserts whether the size is
smaller than or equal to the maximum occurrence.</p>
</li>
<li>
<p>For <code>$.valueWithMinMax</code>, the engine checks the type and asserts whether the size is
between the minimum and maximum occurrence.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The resulting test resembles the following example (note that an <code>and</code> section
separates the autogenerated assertions and the assertion from matchers):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">// 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");</code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Notice that, for the <code>byCommand</code> method, the example calls the
<code>assertThatValueIsANumber</code>. This method must be defined in the test base class or be
statically imported to your tests. Notice that the <code>byCommand</code> call was converted to
<code>assertThatValueIsANumber(parsedJson.read("$.duck"));</code>. That means that the engine took
the method name and passed the proper JSON path as a parameter to it.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The resulting WireMock stub is in the following example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json"> '''
{
"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" ]
}
}
'''</code></pre>
</div>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
If you use a <code>matcher</code>, the part of the request and response that the
<code>matcher</code> addresses with the JSON Path gets removed from the assertion. In the case of
verifying a collection, you must create matchers for <strong>all</strong> the elements of the
collection.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Consider the following example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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('.+'))
}
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The preceding code leads to creating the following test (the code block shows only the assertion section):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">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(".+")</code></pre>
</div>
</div>
<div class="paragraph">
<p>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 <code>$.events</code>
collection and assert it with the <code>byCommand(&#8230;&#8203;)</code> method.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="contract-dsl-async"><a class="anchor" href="#contract-dsl-async"></a><a class="link" href="#contract-dsl-async">2.5. Asynchronous Support</a></h3>
<div class="paragraph">
<p>If you use asynchronous communication on the server side (your controllers are
returning <code>Callable</code>, <code>DeferredResult</code>, and so on), then, inside your contract, you must
provide an <code>async()</code> method in the <code>response</code> section. The following code shows an example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">org.springframework.cloud.contract.spec.Contract.make {
request {
method GET()
url '/get'
}
response {
status OK()
body 'Passed'
async()
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">response:
async: true</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">class contract implements Supplier&lt;Collection&lt;Contract&gt;&gt; {
@Override
public Collection&lt;Contract&gt; get() {
return Collections.singletonList(Contract.make(c -&gt; {
c.request(r -&gt; {
// ...
});
c.response(r -&gt; {
r.async();
// ...
});
}));
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract
contract {
request {
// ...
}
response {
async = true
// ...
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>You can also use the <code>fixedDelayMilliseconds</code> method or property to add delay to your stubs.
The following example shows how to do so:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">org.springframework.cloud.contract.spec.Contract.make {
request {
method GET()
url '/get'
}
response {
status 200
body 'Passed'
fixedDelayMilliseconds 1000
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">response:
fixedDelayMilliseconds: 1000</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">class contract implements Supplier&lt;Collection&lt;Contract&gt;&gt; {
@Override
public Collection&lt;Contract&gt; get() {
return Collections.singletonList(Contract.make(c -&gt; {
c.request(r -&gt; {
// ...
});
c.response(r -&gt; {
r.fixedDelayMilliseconds(1000);
// ...
});
}));
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract
contract {
request {
// ...
}
response {
delay = fixedMilliseconds(1000)
// ...
}
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="contract-dsl-xml"><a class="anchor" href="#contract-dsl-xml"></a><a class="link" href="#contract-dsl-xml">2.6. XML Support for HTTP</a></h3>
<div class="paragraph">
<p>For HTTP contracts, we also support using XML in the request and response body.
The XML body has to be passed within the <code>body</code> element
as a <code>String</code> or <code>GString</code>. Also, body matchers can be provided for
both the request and the response. In place of the <code>jsonPath(&#8230;&#8203;)</code> method, the <code>org.springframework.cloud.contract.spec.internal.BodyMatchers.xPath</code>
method should be used, with the desired <code>xPath</code> provided as the first argument
and the appropriate <code>MatchingType</code> as second. All the body matchers apart from <code>byType()</code> are supported.</p>
</div>
<div class="paragraph">
<p>The following example shows a Groovy DSL contract with XML in the response body:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy"> Contract.make {
request {
method GET()
urlPath '/get'
headers {
contentType(applicationXml())
}
}
response {
status(OK())
headers {
contentType(applicationXml())
}
body """
&lt;test&gt;
&lt;duck type='xtype'&gt;123&lt;/duck&gt;
&lt;alpha&gt;abc&lt;/alpha&gt;
&lt;list&gt;
&lt;elem&gt;abc&lt;/elem&gt;
&lt;elem&gt;def&lt;/elem&gt;
&lt;elem&gt;ghi&lt;/elem&gt;
&lt;/list&gt;
&lt;number&gt;123&lt;/number&gt;
&lt;aBoolean&gt;true&lt;/aBoolean&gt;
&lt;date&gt;2017-01-01&lt;/date&gt;
&lt;dateTime&gt;2017-01-01T01:23:45&lt;/dateTime&gt;
&lt;time&gt;01:02:34&lt;/time&gt;
&lt;valueWithoutAMatcher&gt;foo&lt;/valueWithoutAMatcher&gt;
&lt;key&gt;&lt;complex&gt;foo&lt;/complex&gt;&lt;/key&gt;
&lt;/test&gt;"""
bodyMatchers {
xPath('/test/duck/text()', byRegex("[0-9]{3}"))
xPath('/test/duck/text()', byCommand('equals($it)'))
xPath('/test/duck/xxx', byNull())
xPath('/test/duck/text()', byEquality())
xPath('/test/alpha/text()', byRegex(onlyAlphaUnicode()))
xPath('/test/alpha/text()', byEquality())
xPath('/test/number/text()', byRegex(number()))
xPath('/test/date/text()', byDate())
xPath('/test/dateTime/text()', byTimestamp())
xPath('/test/time/text()', byTime())
xPath('/test/*/complex/text()', byEquality())
xPath('/test/duck/@type', byEquality())
}
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">include::/tmp/releaser-1571951697369-0/spring-cloud-contract/spring-cloud-contract-verifier/src/test/resources/yml/contract_rest_xml.yml</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">import java.util.function.Supplier;
import org.springframework.cloud.contract.spec.Contract;
class contract_xml implements Supplier&lt;Contract&gt; {
@Override
public Contract get() {
return Contract.make(c -&gt; {
c.request(r -&gt; {
r.method(r.GET());
r.urlPath("/get");
r.headers(h -&gt; {
h.contentType(h.applicationXml());
});
});
c.response(r -&gt; {
r.status(r.OK());
r.headers(h -&gt; {
h.contentType(h.applicationXml());
});
r.body("&lt;test&gt;\n" + "&lt;duck type='xtype'&gt;123&lt;/duck&gt;\n"
+ "&lt;alpha&gt;abc&lt;/alpha&gt;\n" + "&lt;list&gt;\n" + "&lt;elem&gt;abc&lt;/elem&gt;\n"
+ "&lt;elem&gt;def&lt;/elem&gt;\n" + "&lt;elem&gt;ghi&lt;/elem&gt;\n" + "&lt;/list&gt;\n"
+ "&lt;number&gt;123&lt;/number&gt;\n" + "&lt;aBoolean&gt;true&lt;/aBoolean&gt;\n"
+ "&lt;date&gt;2017-01-01&lt;/date&gt;\n"
+ "&lt;dateTime&gt;2017-01-01T01:23:45&lt;/dateTime&gt;\n"
+ "&lt;time&gt;01:02:34&lt;/time&gt;\n"
+ "&lt;valueWithoutAMatcher&gt;foo&lt;/valueWithoutAMatcher&gt;\n"
+ "&lt;key&gt;&lt;complex&gt;foo&lt;/complex&gt;&lt;/key&gt;\n" + "&lt;/test&gt;");
r.bodyMatchers(m -&gt; {
m.xPath("/test/duck/text()", m.byRegex("[0-9]{3}"));
m.xPath("/test/duck/text()", m.byCommand("equals($it)"));
m.xPath("/test/duck/xxx", m.byNull());
m.xPath("/test/duck/text()", m.byEquality());
m.xPath("/test/alpha/text()", m.byRegex(r.onlyAlphaUnicode()));
m.xPath("/test/alpha/text()", m.byEquality());
m.xPath("/test/number/text()", m.byRegex(r.number()));
m.xPath("/test/date/text()", m.byDate());
m.xPath("/test/dateTime/text()", m.byTimestamp());
m.xPath("/test/time/text()", m.byTime());
m.xPath("/test/*/complex/text()", m.byEquality());
m.xPath("/test/duck/@type", m.byEquality());
});
});
});
};
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract
contract {
request {
method = GET
urlPath = path("/get")
headers {
contentType = APPLICATION_XML
}
}
response {
status = OK
headers {
contentType =APPLICATION_XML
}
body = body("&lt;test&gt;\n" + "&lt;duck type='xtype'&gt;123&lt;/duck&gt;\n"
+ "&lt;alpha&gt;abc&lt;/alpha&gt;\n" + "&lt;list&gt;\n" + "&lt;elem&gt;abc&lt;/elem&gt;\n"
+ "&lt;elem&gt;def&lt;/elem&gt;\n" + "&lt;elem&gt;ghi&lt;/elem&gt;\n" + "&lt;/list&gt;\n"
+ "&lt;number&gt;123&lt;/number&gt;\n" + "&lt;aBoolean&gt;true&lt;/aBoolean&gt;\n"
+ "&lt;date&gt;2017-01-01&lt;/date&gt;\n"
+ "&lt;dateTime&gt;2017-01-01T01:23:45&lt;/dateTime&gt;\n"
+ "&lt;time&gt;01:02:34&lt;/time&gt;\n"
+ "&lt;valueWithoutAMatcher&gt;foo&lt;/valueWithoutAMatcher&gt;\n"
+ "&lt;key&gt;&lt;complex&gt;foo&lt;/complex&gt;&lt;/key&gt;\n" + "&lt;/test&gt;")
bodyMatchers {
xPath("/test/duck/text()", byRegex("[0-9]{3}"))
xPath("/test/duck/text()", byCommand("equals(\$it)"))
xPath("/test/duck/xxx", byNull)
xPath("/test/duck/text()", byEquality)
xPath("/test/alpha/text()", byRegex(onlyAlphaUnicode))
xPath("/test/alpha/text()", byEquality)
xPath("/test/number/text()", byRegex(number))
xPath("/test/date/text()", byDate)
xPath("/test/dateTime/text()", byTimestamp)
xPath("/test/time/text()", byTime)
xPath("/test/*/complex/text()", byEquality)
xPath("/test/duck/@type", byEquality)
}
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The following example shows an automatically generated test for XML in the response body:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Test
public void validate_xmlMatches() throws Exception {
// given:
MockMvcRequestSpecification request = given()
.header("Content-Type", "application/xml");
// when:
ResponseOptions response = given().spec(request).get("/get");
// then:
assertThat(response.statusCode()).isEqualTo(200);
// and:
DocumentBuilder documentBuilder = DocumentBuilderFactory.newInstance()
.newDocumentBuilder();
Document parsedXml = documentBuilder.parse(new InputSource(
new StringReader(response.getBody().asString())));
// and:
assertThat(valueFromXPath(parsedXml, "/test/list/elem/text()")).isEqualTo("abc");
assertThat(valueFromXPath(parsedXml,"/test/list/elem[2]/text()")).isEqualTo("def");
assertThat(valueFromXPath(parsedXml, "/test/duck/text()")).matches("[0-9]{3}");
assertThat(nodeFromXPath(parsedXml, "/test/duck/xxx")).isNull();
assertThat(valueFromXPath(parsedXml, "/test/alpha/text()")).matches("[\\p{L}]*");
assertThat(valueFromXPath(parsedXml, "/test/*/complex/text()")).isEqualTo("foo");
assertThat(valueFromXPath(parsedXml, "/test/duck/@type")).isEqualTo("xtype");
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="contract-dsl-multiple"><a class="anchor" href="#contract-dsl-multiple"></a><a class="link" href="#contract-dsl-multiple">2.7. Multiple Contracts in One File</a></h3>
<div class="paragraph">
<p>You can define multiple contracts in one file. Such a contract might resemble the
following example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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()
}
}
]</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">---
name: should post a user
request:
method: POST
url: /users/1
response:
status: 200
---
request:
method: POST
url: /users/2
response:
status: 200
---
request:
method: POST
url: /users/3
response:
status: 200</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">java</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">class contract implements Supplier&lt;Collection&lt;Contract&gt;&gt; {
@Override
public Collection&lt;Contract&gt; get() {
return Arrays.asList(
Contract.make(c -&gt; {
c.name("should post a user");
// ...
}), Contract.make(c -&gt; {
// ...
}), Contract.make(c -&gt; {
// ...
})
);
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">kotlin</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-kotlin hljs" data-lang="kotlin">import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract
arrayOf(
contract {
name("should post a user")
// ...
},
contract {
// ...
},
contract {
// ...
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>In the preceding example, one contract has the <code>name</code> field and the other does not. This
leads to generation of two tests that look more or less like the following:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">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);
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Notice that, for the contract that has the <code>name</code> field, the generated test method is named
<code>validate_should_post_a_user</code>. The one that does not have the <code>name</code> field is called
<code>validate_withList_1</code>. It corresponds to the name of the file <code>WithList.groovy</code> and the
index of the contract in the list.</p>
</div>
<div class="paragraph">
<p>The generated stubs are shown in the following example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>should post a user.json
1_WithList.json</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The first file got the <code>name</code> parameter from the contract. The second
got the name of the contract file (<code>WithList.groovy</code>) prefixed with the index (in this
case, the contract had an index of <code>1</code> in the list of contracts in the file).</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
It is much better to name your contracts, because doing so makes
your tests far more meaningful.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="contract-stateful-contracts"><a class="anchor" href="#contract-stateful-contracts"></a><a class="link" href="#contract-stateful-contracts">2.8. Stateful Contracts</a></h3>
<div class="paragraph">
<p>Stateful contracts (known also as scenarios) are contract definitions that should be read
in order. This might be useful in the following situations:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>You want to execute the contract in a precisely defined order, since you use Spring
Cloud Contract to test your stateful application</p>
</li>
</ul>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
We really discourage you from doing that, since contract tests should be stateless.
</td>
</tr>
</table>
</div>
<div class="ulist">
<ul>
<li>
<p>You want the same endpoint to return different results for the same request.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>To create stateful contracts (or scenarios), you need to
use the proper naming convention while creating your contracts. The convention
requires including an order number followed by an underscore. This works regardless
of whether you work with YAML or Groovy. The following listing shows an example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code>my_contracts_dir\
scenario1\
1_login.groovy
2_showCart.groovy
3_logout.groovy</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Such a tree causes Spring Cloud Contract Verifier to generate WireMock&#8217;s scenario with a
name of <code>scenario1</code> and the three following steps:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>login, marked as <code>Started</code> pointing to&#8230;&#8203;</p>
</li>
<li>
<p>showCart, marked as <code>Step1</code> pointing to&#8230;&#8203;</p>
</li>
<li>
<p>logout, marked as <code>Step2</code> (which closes the scenario).</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>You can find more details about WireMock scenarios at
<a href="https://wiremock.org/docs/stateful-behaviour/">https://wiremock.org/docs/stateful-behaviour/</a>.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="feature-integrations"><a class="anchor" href="#feature-integrations"></a><a class="link" href="#feature-integrations">3. Integrations</a></h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="features-jax-rs"><a class="anchor" href="#features-jax-rs"></a><a class="link" href="#features-jax-rs">3.1. JAX-RS</a></h3>
<div class="paragraph">
<p>The Spring Cloud Contract supports the JAX-RS 2 Client API. The base class needs
to define <code>protected WebTarget webTarget</code> 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 be set. Otherwise, the default of <code>application/octet-stream</code> gets used.</p>
</div>
<div class="paragraph">
<p>In order to use JAX-RS mode, use the following settings:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">testMode = 'JAXRSCLIENT'</code></pre>
</div>
</div>
<div class="paragraph">
<p>The following example shows a generated test API:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy"> """\
package com.example;
import com.jayway.jsonpath.DocumentContext;
import com.jayway.jsonpath.JsonPath;
import org.junit.Test;
import org.junit.Rule;
import javax.ws.rs.client.Entity;
import javax.ws.rs.core.Response;
import static org.springframework.cloud.contract.verifier.assertion.SpringCloudContractAssertions.assertThat;
import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.*;
import static com.toomuchcoding.jsonassert.JsonAssertion.assertThatJson;
import static javax.ws.rs.client.Entity.*;
@SuppressWarnings("rawtypes")
public class FooTest {
\tWebTarget webTarget;
\t@Test
\tpublic void validate_() throws Exception {
\t\t// when:
\t\t\tResponse response = webTarget
\t\t\t\t\t\t\t.path("/users")
\t\t\t\t\t\t\t.queryParam("limit", "10")
\t\t\t\t\t\t\t.queryParam("offset", "20")
\t\t\t\t\t\t\t.queryParam("filter", "email")
\t\t\t\t\t\t\t.queryParam("sort", "name")
\t\t\t\t\t\t\t.queryParam("search", "55")
\t\t\t\t\t\t\t.queryParam("age", "99")
\t\t\t\t\t\t\t.queryParam("name", "Denis.Stepanov")
\t\t\t\t\t\t\t.queryParam("email", "bob@email.com")
\t\t\t\t\t\t\t.request()
\t\t\t\t\t\t\t.build("GET")
\t\t\t\t\t\t\t.invoke();
\t\t\tString responseAsString = response.readEntity(String.class);
\t\t// then:
\t\t\tassertThat(response.getStatus()).isEqualTo(200);
\t\t// and:
\t\t\tDocumentContext parsedJson = JsonPath.parse(responseAsString);
\t\t\tassertThatJson(parsedJson).field("['property1']").isEqualTo("a");
\t}
}
"""</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="feature-webflux"><a class="anchor" href="#feature-webflux"></a><a class="link" href="#feature-webflux">3.2. WebFlux with WebTestClient</a></h3>
<div class="paragraph">
<p>You can work with WebFlux by using WebTestClient. The following listing shows how to
configure WebTestClient as the test mode:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">Maven</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml">&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;WEBTESTCLIENT&lt;/testMode&gt;
&lt;/configuration&gt;
&lt;/plugin&gt;</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Gradle</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">contracts {
testMode = 'WEBTESTCLIENT'
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The following example shows how to set up a WebTestClient base class and RestAssured
for WebFlux:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">import io.restassured.module.webtestclient.RestAssuredWebTestClient;
import org.junit.Before;
public abstract class BeerRestBase {
@Before
public void setup() {
RestAssuredWebTestClient.standaloneSetup(
new ProducerController(personToCheck -&gt; personToCheck.age &gt;= 20));
}
}
}</code></pre>
</div>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
The <code>WebTestClient</code> mode is faster than the <code>EXPLICIT</code> mode.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="feature-webflux-explicit"><a class="anchor" href="#feature-webflux-explicit"></a><a class="link" href="#feature-webflux-explicit">3.3. WebFlux with Explicit Mode</a></h3>
<div class="paragraph">
<p>You can also use WebFlux with the explicit mode in your generated tests
to work with WebFlux. The following example shows how to configure using explicit mode:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">Maven</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml">&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;</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Gradle</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">contracts {
testMode = 'EXPLICIT'
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The following example shows how to set up a base class and RestAssured for Web Flux:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">@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());
}
}
}</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-context-paths"><a class="anchor" href="#features-context-paths"></a><a class="link" href="#features-context-paths">3.4. Working with Context Paths</a></h3>
<div class="paragraph">
<p>Spring Cloud Contract supports context paths.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
<div class="paragraph">
<p>The only change needed to fully support context paths is the switch on the
producer side. Also, the autogenerated tests must use explicit mode. The consumer
side remains untouched. In order for the generated test to pass, you must use explicit
mode. The following example shows how to set the test mode to <code>EXPLICIT</code>:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">Maven</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml">&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;</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Gradle</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">contracts {
testMode = 'EXPLICIT'
}</code></pre>
</div>
</div>
</div>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>That way, you generate a test that does not use MockMvc. It means that you generate
real requests and you need to set up your generated test&#8217;s base class to work on a real
socket.</p>
</div>
<div class="paragraph">
<p>Consider the following contract:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">org.springframework.cloud.contract.spec.Contract.make {
request {
method 'GET'
url '/my-context-path/url'
}
response {
status OK()
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The following example shows how to set up a base class and RestAssured:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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;
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>If you do it this way:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>All of your requests in the autogenerated tests are sent to the real endpoint with your
context path included (for example, <code>/my-context-path/url</code>).</p>
</li>
<li>
<p>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 <code>/my-context-path/url</code>).</p>
</li>
</ul>
</div>
</div>
<div class="sect2">
<h3 id="features-rest-docs"><a class="anchor" href="#features-rest-docs"></a><a class="link" href="#features-rest-docs">3.5. Working with REST Docs</a></h3>
<div class="paragraph">
<p>You can use <a href="https://projects.spring.io/spring-restdocs">Spring REST Docs</a> to generate
documentation (for example, in Asciidoc format) for an HTTP API with Spring MockMvc,
<code>WebTestClient</code>, or RestAssured. 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 <code>@AutoConfigureRestDocs</code> to have stubs be
automatically generated in the REST Docs output directory.</p>
</div>
<div class="imageblock">
<div class="content">
<img src="./images/rest-docs.png" alt="rest docs" width="1237" height="835">
</div>
</div>
<div class="paragraph">
<p>The following example uses <code>MockMvc</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@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"));
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>This test generates a WireMock stub at <code>target/snippets/stubs/resource.json</code>. It matches
all <code>GET</code> requests to the <code>/resource</code> path. The same example with <code>WebTestClient</code> (used
for testing Spring WebFlux applications) would be as follows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@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"));
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Without any additional configuration, these tests create a stub with a request matcher
for the HTTP method and all headers except <code>host</code> and <code>content-length</code>. 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:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Creating a stub that matches only in the way you specify.</p>
</li>
<li>
<p>Asserting that the request in the test case also matches the same conditions.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The main entry point for this feature is <code>WireMockRestDocs.verify()</code>, which can be used
as a substitute for the <code>document()</code> convenience method, as the following
example shows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">import static org.springframework.cloud.contract.wiremock.restdocs.WireMockRestDocs.verify;
@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"));
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The preceding contract specifies that any valid POST with an <code>id</code> field receives the response
defined in this test. You can chain together calls to <code>.jsonPath()</code> to add additional
matchers. If JSON Path is unfamiliar, the <a href="https://github.com/jayway/JsonPath">JayWay
documentation</a> can help you get up to speed. The <code>WebTestClient</code> version of this test
has a similar <code>verify()</code> static helper that you insert in the same place.</p>
</div>
<div class="paragraph">
<p>Instead of the <code>jsonPath</code> and <code>contentType</code> convenience methods, you can also use the
WireMock APIs to verify that the request matches the created stub, as the
following example shows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@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"));
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The WireMock API is rich. You can match headers, query parameters, and the request body by
regex as well as by JSON path. You can use these features to create stubs with a wider
range of parameters. The preceding example generates a stub resembling the following example:</p>
</div>
<div class="listingblock">
<div class="title">post-resource.json</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">{
"request" : {
"url" : "/resource",
"method" : "POST",
"bodyPatterns" : [ {
"matchesJsonPath" : "$.id"
}]
},
"response" : {
"status" : 200,
"body" : "Hello World",
"headers" : {
"X-Application-Context" : "application:-1",
"Content-Type" : "text/plain"
}
}
}</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
You can use either the <code>wiremock()</code> method or the <code>jsonPath()</code> and <code>contentType()</code>
methods to create request matchers, but you cannot use both approaches.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>On the consumer side, you can make the <code>resource.json</code> generated earlier in this section
available on the classpath (by
<a href="#features-stub-runner-publishing-stubs-as-jars">Publishing Stubs as JARs</a>, for example). After that, you can create a stub that uses WireMock in a
number of different ways, including by using
<code>@AutoConfigureWireMock(stubs="classpath:resource.json")</code>, as described earlier in this
document.</p>
</div>
<div class="sect3">
<h4 id="features-rest-docs-contracts"><a class="anchor" href="#features-rest-docs-contracts"></a><a class="link" href="#features-rest-docs-contracts">3.5.1. Generating Contracts with REST Docs</a></h4>
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
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.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Consider the following test:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java"> 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()));</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The preceding test creates the stub presented in the previous section, generating both
the contract and a documentation file.</p>
</div>
<div class="paragraph">
<p>The contract is called <code>index.groovy</code> and might resemble the following example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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''')
}
bodyMatchers {
jsonPath('$[?(@.foo &gt;= 20)]', byType())
}
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The generated document (formatted in Asciidoc in this case) contains a formatted
contract. The location of this file would be <code>index/dsl-contract.adoc</code>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="features-messaging"><a class="anchor" href="#features-messaging"></a><a class="link" href="#features-messaging">4. Messaging</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>Spring Cloud Contract 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.</p>
</div>
<div class="sect2">
<h3 id="contract-dsl-messaging-top-level"><a class="anchor" href="#contract-dsl-messaging-top-level"></a><a class="link" href="#contract-dsl-messaging-top-level">4.1. Messaging DSL Top-Level Elements</a></h3>
<div class="paragraph">
<p>The DSL for messaging looks a little bit different than the one that focuses on HTTP. The
following sections explain the differences:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#contract-dsl-output-triggered-method">Output Triggered by a Method</a></p>
</li>
<li>
<p><a href="#contract-dsl-output-triggered-message">Output Triggered by a Message</a></p>
</li>
<li>
<p><a href="#contract-dsl-consumer-producer">Consumer/Producer</a></p>
</li>
<li>
<p><a href="#contract-dsl-messaging-common">Common</a></p>
</li>
</ul>
</div>
<div class="sect3">
<h4 id="contract-dsl-output-triggered-method"><a class="anchor" href="#contract-dsl-output-triggered-method"></a><a class="link" href="#contract-dsl-output-triggered-method">4.1.1. Output Triggered by a Method</a></h4>
<div class="paragraph">
<p>The output message can be triggered by calling a method (such as a <code>Scheduler</code> when a contract was
started and a message was sent), as shown in the following example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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')
}
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy"># 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</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>In the previous example case, the output message is sent to <code>output</code> if a method called
<code>bookReturnedTriggered</code> is executed. On the message publisher&#8217;s side, we generate a
test that calls that method to trigger the message. On the consumer side, you can use
the <code>some_label</code> to trigger the message.</p>
</div>
</div>
<div class="sect3">
<h4 id="contract-dsl-output-triggered-message"><a class="anchor" href="#contract-dsl-output-triggered-message"></a><a class="link" href="#contract-dsl-output-triggered-message">4.1.2. Output Triggered by a Message</a></h4>
<div class="paragraph">
<p>The output message can be triggered by receiving a message, as shown in the following
example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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')
}
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy"># 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</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>In the preceding example, the output message is sent to <code>output</code> if a proper message is
received on the <code>input</code> destination. On the message publisher&#8217;s side, the engine
generates a test that sends the input message to the defined destination. On the
consumer side, you can either send a message to the input destination or use a label
(<code>some_label</code> in the example) to trigger the message.</p>
</div>
</div>
<div class="sect3">
<h4 id="contract-dsl-consumer-producer"><a class="anchor" href="#contract-dsl-consumer-producer"></a><a class="link" href="#contract-dsl-consumer-producer">4.1.3. Consumer/Producer</a></h4>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
This section is valid only for Groovy DSL.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>In HTTP, you have a notion of <code>client</code>/<code>stub and `server</code>/<code>test</code> notation. You can also
use those paradigms in messaging. In addition, Spring Cloud Contract Verifier also
provides the <code>consumer</code> and <code>producer</code> methods, as presented in the following example
(note that you can use either <code>$</code> or <code>value</code> methods to provide <code>consumer</code> and <code>producer</code>
parts):</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy"> Contract.make {
name "foo"
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'
])
}
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="contract-dsl-messaging-common"><a class="anchor" href="#contract-dsl-messaging-common"></a><a class="link" href="#contract-dsl-messaging-common">4.1.4. Common</a></h4>
<div class="paragraph">
<p>In the <code>input</code> or <code>outputMessage</code> section, you can call <code>assertThat</code> with the name
of a <code>method</code> (for example, <code>assertThatMessageIsOnTheQueue()</code>) that you have defined in the
base class or in a static import. Spring Cloud Contract runs that method
in the generated test.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-messaging-integrations"><a class="anchor" href="#features-messaging-integrations"></a><a class="link" href="#features-messaging-integrations">4.2. Integrations</a></h3>
<div class="paragraph">
<p>You can use one of the following four integration configurations:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Apache Camel</p>
</li>
<li>
<p>Spring Integration</p>
</li>
<li>
<p>Spring Cloud Stream</p>
</li>
<li>
<p>Spring AMQP</p>
</li>
<li>
<p>Spring JMS (requires embedded broker)</p>
</li>
<li>
<p>Spring Kafka (requires embedded broker)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Since we use Spring Boot, if you have added one of these libraries to the classpath, all
the messaging configuration is automatically set up.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
Remember to put <code>@AutoConfigureMessageVerifier</code> on the base class of your
generated tests. Otherwise, the messaging part of Spring Cloud Contract does not
work.
</td>
</tr>
</table>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
<div class="paragraph">
<p>If you want to use Spring Cloud Stream, remember to add a dependency on
<code>org.springframework.cloud:spring-cloud-stream-test-support</code>, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">Maven</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml">&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;</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Gradle</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">testCompile "org.springframework.cloud:spring-cloud-stream-test-support"</code></pre>
</div>
</div>
</div>
</div>
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="features-messaging-manual"><a class="anchor" href="#features-messaging-manual"></a><a class="link" href="#features-messaging-manual">4.2.1. Manual Integration Testing</a></h4>
<div class="paragraph">
<p>The main interface used by the tests is
<code>org.springframework.cloud.contract.verifier.messaging.MessageVerifier</code>.
It defines how to send and receive messages. You can create your own implementation to
achieve the same goal.</p>
</div>
<div class="paragraph">
<p>In a test, you can inject a <code>ContractVerifierMessageExchange</code> to send and receive
messages that follow the contract. Then add <code>@AutoConfigureMessageVerifier</code> to your test.
The following example shows how to do so:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@RunWith(SpringTestRunner.class)
@SpringBootTest
@AutoConfigureMessageVerifier
public static class MessagingContractTests {
@Autowired
private MessageVerifier verifier;
...
}</code></pre>
</div>
</div>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
If your tests require stubs as well, then <code>@AutoConfigureStubRunner</code> includes the
messaging configuration, so you only need the one annotation.
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-messaging-test-generation"><a class="anchor" href="#features-messaging-test-generation"></a><a class="link" href="#features-messaging-test-generation">4.3. Producer Side Messaging Test Generation</a></h3>
<div class="paragraph">
<p>Having the <code>input</code> or <code>outputMessage</code> 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, TestNG, or Spock tests.</p>
</div>
<div class="paragraph">
<p>There are three main scenarios that we should take into consideration:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>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, a scheduler).</p>
</li>
<li>
<p>Scenario 2: The input message triggers an output message.</p>
</li>
<li>
<p>Scenario 3: The input message is consumed, and there is no output message.</p>
</li>
</ul>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
The destination passed to <code>messageFrom</code> or <code>sentTo</code> can have different
meanings for different messaging implementations. For Stream and Integration, it is
first resolved as a <code>destination</code> of a channel. Then, if there is no such <code>destination</code>
it is resolved as a channel name. For Camel, that&#8217;s a certain component (for example,
<code>jms</code>).
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="features-messaging-scenario1"><a class="anchor" href="#features-messaging-scenario1"></a><a class="link" href="#features-messaging-scenario1">4.3.1. Scenario 1: No Input Message</a></h4>
<div class="paragraph">
<p>Consider the following contract:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">def contractDsl = Contract.make {
name "foo"
label 'some_label'
input {
triggeredBy('bookReturnedTriggered()')
}
outputMessage {
sentTo('activemq:output')
body('''{ "bookName" : "foo" }''')
headers {
header('BOOK-NAME', 'foo')
messagingContentType(applicationJson())
}
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">label: some_label
input:
triggeredBy: bookReturnedTriggered
outputMessage:
sentTo: activemq:output
body:
bookName: foo
headers:
BOOK-NAME: foo
contentType: application/json</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>For the preceding example, the following test would be created:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">JUnit</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java"> '''\
package com.example;
import com.jayway.jsonpath.DocumentContext;
import com.jayway.jsonpath.JsonPath;
import org.junit.Test;
import org.junit.Rule;
import javax.inject.Inject;
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierObjectMapper;
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierMessage;
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierMessaging;
import static org.springframework.cloud.contract.verifier.assertion.SpringCloudContractAssertions.assertThat;
import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.*;
import static com.toomuchcoding.jsonassert.JsonAssertion.assertThatJson;
import static org.springframework.cloud.contract.verifier.messaging.util.ContractVerifierMessagingUtil.headers;
import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.fileToBytes;
@SuppressWarnings("rawtypes")
public class FooTest {
\t@Inject ContractVerifierMessaging contractVerifierMessaging;
\t@Inject ContractVerifierObjectMapper contractVerifierObjectMapper;
\t@Test
\tpublic void validate_foo() throws Exception {
\t\t// when:
\t\t\tbookReturnedTriggered();
\t\t// then:
\t\t\tContractVerifierMessage response = contractVerifierMessaging.receive("activemq:output");
\t\t\tassertThat(response).isNotNull();
\t\t// and:
\t\t\tassertThat(response.getHeader("BOOK-NAME")).isNotNull();
\t\t\tassertThat(response.getHeader("BOOK-NAME").toString()).isEqualTo("foo");
\t\t\tassertThat(response.getHeader("contentType")).isNotNull();
\t\t\tassertThat(response.getHeader("contentType").toString()).isEqualTo("application/json");
\t\t// and:
\t\t\tDocumentContext parsedJson = JsonPath.parse(contractVerifierObjectMapper.writeValueAsString(response.getPayload()));
\t\t\tassertThatJson(parsedJson).field("['bookName']").isEqualTo("foo");
\t}
}
'''</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Spock</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy"> '''\
package com.example
import com.jayway.jsonpath.DocumentContext
import com.jayway.jsonpath.JsonPath
import spock.lang.Specification
import javax.inject.Inject
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierObjectMapper
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierMessage
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierMessaging
import static org.springframework.cloud.contract.verifier.assertion.SpringCloudContractAssertions.assertThat
import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.*
import static com.toomuchcoding.jsonassert.JsonAssertion.assertThatJson
import static org.springframework.cloud.contract.verifier.messaging.util.ContractVerifierMessagingUtil.headers
import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.fileToBytes
@SuppressWarnings("rawtypes")
class FooSpec extends Specification {
\t@Inject ContractVerifierMessaging contractVerifierMessaging
\t@Inject ContractVerifierObjectMapper contractVerifierObjectMapper
\tdef validate_foo() throws Exception {
\t\twhen:
\t\t\tbookReturnedTriggered()
\t\tthen:
\t\t\tContractVerifierMessage response = contractVerifierMessaging.receive("activemq:output")
\t\t\tresponse != null
\t\tand:
\t\t\tresponse.getHeader("BOOK-NAME") != null
\t\t\tresponse.getHeader("BOOK-NAME").toString() == 'foo'
\t\t\tresponse.getHeader("contentType") != null
\t\t\tresponse.getHeader("contentType").toString() == 'application/json'
\t\tand:
\t\t\tDocumentContext parsedJson = JsonPath.parse(contractVerifierObjectMapper.writeValueAsString(response.getPayload()))
\t\t\tassertThatJson(parsedJson).field("['bookName']").isEqualTo("foo")
\t}
}
'''</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="features-messaging-scenario2"><a class="anchor" href="#features-messaging-scenario2"></a><a class="link" href="#features-messaging-scenario2">4.3.2. Scenario 2: Output Triggered by Input</a></h4>
<div class="paragraph">
<p>Consider the following contract:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">def contractDsl = Contract.make {
name "foo"
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')
}
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">label: some_label
input:
messageFrom: jms:input
messageBody:
bookName: 'foo'
messageHeaders:
sample: header
outputMessage:
sentTo: jms:output
body:
bookName: foo
headers:
BOOK-NAME: foo</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>For the preceding contract, the following test would be created:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">JUnit</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java"> '''\
package com.example;
import com.jayway.jsonpath.DocumentContext;
import com.jayway.jsonpath.JsonPath;
import org.junit.Test;
import org.junit.Rule;
import javax.inject.Inject;
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierObjectMapper;
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierMessage;
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierMessaging;
import static org.springframework.cloud.contract.verifier.assertion.SpringCloudContractAssertions.assertThat;
import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.*;
import static com.toomuchcoding.jsonassert.JsonAssertion.assertThatJson;
import static org.springframework.cloud.contract.verifier.messaging.util.ContractVerifierMessagingUtil.headers;
import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.fileToBytes;
@SuppressWarnings("rawtypes")
public class FooTest {
\t@Inject ContractVerifierMessaging contractVerifierMessaging;
\t@Inject ContractVerifierObjectMapper contractVerifierObjectMapper;
\t@Test
\tpublic void validate_foo() throws Exception {
\t\t// given:
\t\t\tContractVerifierMessage inputMessage = contractVerifierMessaging.create(
\t\t\t\t\t"{\\"bookName\\":\\"foo\\"}"
\t\t\t\t\t\t, headers()
\t\t\t\t\t\t\t.header("sample", "header")
\t\t\t);
\t\t// when:
\t\t\tcontractVerifierMessaging.send(inputMessage, "jms:input");
\t\t// then:
\t\t\tContractVerifierMessage response = contractVerifierMessaging.receive("jms:output");
\t\t\tassertThat(response).isNotNull();
\t\t// and:
\t\t\tassertThat(response.getHeader("BOOK-NAME")).isNotNull();
\t\t\tassertThat(response.getHeader("BOOK-NAME").toString()).isEqualTo("foo");
\t\t// and:
\t\t\tDocumentContext parsedJson = JsonPath.parse(contractVerifierObjectMapper.writeValueAsString(response.getPayload()));
\t\t\tassertThatJson(parsedJson).field("['bookName']").isEqualTo("foo");
\t}
}
'''</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Spock</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy"> """\
package com.example
import com.jayway.jsonpath.DocumentContext
import com.jayway.jsonpath.JsonPath
import spock.lang.Specification
import javax.inject.Inject
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierObjectMapper
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierMessage
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierMessaging
import static org.springframework.cloud.contract.verifier.assertion.SpringCloudContractAssertions.assertThat
import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.*
import static com.toomuchcoding.jsonassert.JsonAssertion.assertThatJson
import static org.springframework.cloud.contract.verifier.messaging.util.ContractVerifierMessagingUtil.headers
import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.fileToBytes
@SuppressWarnings("rawtypes")
class FooSpec extends Specification {
\t@Inject ContractVerifierMessaging contractVerifierMessaging
\t@Inject ContractVerifierObjectMapper contractVerifierObjectMapper
\tdef validate_foo() throws Exception {
\t\tgiven:
\t\t\tContractVerifierMessage inputMessage = contractVerifierMessaging.create(
\t\t\t\t\t'''{"bookName":"foo"}'''
\t\t\t\t\t\t, headers()
\t\t\t\t\t\t\t.header("sample", "header")
\t\t\t)
\t\twhen:
\t\t\tcontractVerifierMessaging.send(inputMessage, "jms:input")
\t\tthen:
\t\t\tContractVerifierMessage response = contractVerifierMessaging.receive("jms:output")
\t\t\tresponse != null
\t\tand:
\t\t\tresponse.getHeader("BOOK-NAME") != null
\t\t\tresponse.getHeader("BOOK-NAME").toString() == 'foo'
\t\tand:
\t\t\tDocumentContext parsedJson = JsonPath.parse(contractVerifierObjectMapper.writeValueAsString(response.getPayload()))
\t\t\tassertThatJson(parsedJson).field("['bookName']").isEqualTo("foo")
\t}
}
"""</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="features-messaging-scenario3"><a class="anchor" href="#features-messaging-scenario3"></a><a class="link" href="#features-messaging-scenario3">4.3.3. Scenario 3: No Output Message</a></h4>
<div class="paragraph">
<p>Consider the following contract:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">groovy</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">def contractDsl = Contract.make {
name "foo"
label 'some_label'
input {
messageFrom('jms:delete')
messageBody([
bookName: 'foo'
])
messageHeaders {
header('sample', 'header')
}
assertThat('bookWasDeleted()')
}
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">yml</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">label: some_label
input:
messageFrom: jms:delete
messageBody:
bookName: 'foo'
messageHeaders:
sample: header
assertThat: bookWasDeleted()</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>For the preceding contract, the following test would be created:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">JUnit</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java"> """\
package com.example;
import com.jayway.jsonpath.DocumentContext;
import com.jayway.jsonpath.JsonPath;
import org.junit.Test;
import org.junit.Rule;
import javax.inject.Inject;
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierObjectMapper;
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierMessage;
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierMessaging;
import static org.springframework.cloud.contract.verifier.assertion.SpringCloudContractAssertions.assertThat;
import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.*;
import static com.toomuchcoding.jsonassert.JsonAssertion.assertThatJson;
import static org.springframework.cloud.contract.verifier.messaging.util.ContractVerifierMessagingUtil.headers;
import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.fileToBytes;
@SuppressWarnings("rawtypes")
public class FooTest {
\t@Inject ContractVerifierMessaging contractVerifierMessaging;
\t@Inject ContractVerifierObjectMapper contractVerifierObjectMapper;
\t@Test
\tpublic void validate_foo() throws Exception {
\t\t// given:
\t\t\tContractVerifierMessage inputMessage = contractVerifierMessaging.create(
\t\t\t\t\t"{\\"bookName\\":\\"foo\\"}"
\t\t\t\t\t\t, headers()
\t\t\t\t\t\t\t.header("sample", "header")
\t\t\t);
\t\t// when:
\t\t\tcontractVerifierMessaging.send(inputMessage, "jms:delete");
\t\t\tbookWasDeleted();
\t}
}
"""</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Spock</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy"> """\
package com.example
import com.jayway.jsonpath.DocumentContext
import com.jayway.jsonpath.JsonPath
import spock.lang.Specification
import javax.inject.Inject
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierObjectMapper
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierMessage
import org.springframework.cloud.contract.verifier.messaging.internal.ContractVerifierMessaging
import static org.springframework.cloud.contract.verifier.assertion.SpringCloudContractAssertions.assertThat
import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.*
import static com.toomuchcoding.jsonassert.JsonAssertion.assertThatJson
import static org.springframework.cloud.contract.verifier.messaging.util.ContractVerifierMessagingUtil.headers
import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.fileToBytes
@SuppressWarnings("rawtypes")
class FooSpec extends Specification {
\t@Inject ContractVerifierMessaging contractVerifierMessaging
\t@Inject ContractVerifierObjectMapper contractVerifierObjectMapper
\tdef validate_foo() throws Exception {
\t\tgiven:
\t\t\tContractVerifierMessage inputMessage = contractVerifierMessaging.create(
\t\t\t\t\t'''{"bookName":"foo"}'''
\t\t\t\t\t\t, headers()
\t\t\t\t\t\t\t.header("sample", "header")
\t\t\t)
\t\twhen:
\t\t\tcontractVerifierMessaging.send(inputMessage, "jms:delete")
\t\t\tbookWasDeleted()
\t\tthen:
\t\t\tnoExceptionThrown()
\t}
}
"""</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-messaging-consumer"><a class="anchor" href="#features-messaging-consumer"></a><a class="link" href="#features-messaging-consumer">4.4. Consumer Stub Generation</a></h3>
<div class="paragraph">
<p>Unlike in the HTTP part, in messaging, we need to publish the contract definition inside the JAR with
a stub. Then it is parsed on the consumer side, and proper stubbed routes are created.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
If you have multiple frameworks on the classpath, Stub Runner needs to
define which one should be used. Assume that you have AMQP, Spring Cloud Stream, and Spring Integration
on the classpath and that you want to use Spring AMQP. Then you need to set
<code>stubrunner.stream.enabled=false</code> and <code>stubrunner.integration.enabled=false</code>.
That way, the only remaining framework is Spring AMQP.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-triggering"><a class="anchor" href="#features-messaging-stub-triggering"></a><a class="link" href="#features-messaging-stub-triggering">4.4.1. Stub triggering</a></h4>
<div class="paragraph">
<p>To trigger a message, use the <code>StubTrigger</code> interface, as the following example shows:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">package org.springframework.cloud.contract.stubrunner;
import java.util.Collection;
import java.util.Map;
/**
* Contract for triggering stub messages.
*
* @author Marcin Grzejszczak
*/
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.
* @param ivyNotation ivy notation of a stub
* @param labelName name of the label to trigger
* @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.
* @param labelName name of the label to trigger
* @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();
/**
* Feature related to messaging.
* @return a mapping of ivy notation of a dependency to all the labels it has.
*/
Map&lt;String, Collection&lt;String&gt;&gt; labels();
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>For convenience, the <code>StubFinder</code> interface extends <code>StubTrigger</code>, so you only need one
or the other in your tests.</p>
</div>
<div class="paragraph">
<p><code>StubTrigger</code> gives you the following options to trigger a message:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#features-messaging-trigger-label">Trigger by Label</a></p>
</li>
<li>
<p><a href="#features-messaging-trigger-group-artifact-ids">Trigger by Group and Artifact Ids</a></p>
</li>
<li>
<p><a href="#features-messaging-trigger-artifact-ids">Trigger by Artifact IDs</a></p>
</li>
<li>
<p><a href="#features-messaging-trigger-all-messages">Trigger All Messages</a></p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="features-messaging-trigger-label"><a class="anchor" href="#features-messaging-trigger-label"></a><a class="link" href="#features-messaging-trigger-label">4.4.2. Trigger by Label</a></h4>
<div class="paragraph">
<p>The following example shows how to trigger a message with a label:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">stubFinder.trigger('return_book_1')</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="features-messaging-trigger-group-artifact-ids"><a class="anchor" href="#features-messaging-trigger-group-artifact-ids"></a><a class="link" href="#features-messaging-trigger-group-artifact-ids">4.4.3. Trigger by Group and Artifact Ids</a></h4>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">stubFinder.trigger('org.springframework.cloud.contract.verifier.stubs:streamService', 'return_book_1')</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="features-messaging-trigger-artifact-ids"><a class="anchor" href="#features-messaging-trigger-artifact-ids"></a><a class="link" href="#features-messaging-trigger-artifact-ids">4.4.4. Trigger by Artifact IDs</a></h4>
<div class="paragraph">
<p>The following example shows how to trigger a message from artifact IDs:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">stubFinder.trigger('streamService', 'return_book_1')</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="features-messaging-trigger-all-messages"><a class="anchor" href="#features-messaging-trigger-all-messages"></a><a class="link" href="#features-messaging-trigger-all-messages">4.4.5. Trigger All Messages</a></h4>
<div class="paragraph">
<p>The following example shows how to trigger all messages:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">stubFinder.trigger()</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-messaging-stub-runner-camel"><a class="anchor" href="#features-messaging-stub-runner-camel"></a><a class="link" href="#features-messaging-stub-runner-camel">4.5. Consumer Side Messaging With Apache Camel</a></h3>
<div class="paragraph">
<p>Spring Cloud Contract Stub Runner&#8217;s messaging module gives you an easy way to integrate with Apache Camel.
For the provided artifacts, it automatically downloads the stubs and registers the required
routes.</p>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-runner-camel-adding"><a class="anchor" href="#features-messaging-stub-runner-camel-adding"></a><a class="link" href="#features-messaging-stub-runner-camel-adding">4.5.1. Adding Apache Camel to the Project</a></h4>
<div class="paragraph">
<p>You can have both Apache Camel and Spring Cloud Contract Stub Runner on the classpath.
Remember to annotate your test class with <code>@AutoConfigureStubRunner</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-runner-camel-disabling"><a class="anchor" href="#features-messaging-stub-runner-camel-disabling"></a><a class="link" href="#features-messaging-stub-runner-camel-disabling">4.5.2. Disabling the Functionality</a></h4>
<div class="paragraph">
<p>If you need to disable this functionality, set the <code>stubrunner.camel.enabled=false</code> property.</p>
</div>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-runner-camel-example"><a class="anchor" href="#features-messaging-stub-runner-camel-example"></a><a class="link" href="#features-messaging-stub-runner-camel-example">4.5.3. Examples</a></h4>
<div class="paragraph">
<p>Assume that we have the following Maven repository with deployed stubs for the
<code>camelService</code> application.</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">└── .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</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Further assume that the stubs contain the following structure:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">├── META-INF
│   └── MANIFEST.MF
└── repository
├── accurest
│   ├── bookDeleted.groovy
│   ├── bookReturned1.groovy
│   └── bookReturned2.groovy
└── mappings</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Now consider the following contracts (we number them 1 and 2):</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Contract.make {
label 'return_book_1'
input {
triggeredBy('bookReturnedTriggered()')
}
outputMessage {
sentTo('jms:output')
body('''{ "bookName" : "foo" }''')
headers {
header('BOOK-NAME', 'foo')
}
}
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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')
}
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-camel-scenario1"><a class="anchor" href="#features-messaging-stub-runner-camel-scenario1"></a><a class="link" href="#features-messaging-stub-runner-camel-scenario1">Scenario 1 (No Input Message)</a></h5>
<div class="paragraph">
<p>To trigger a message from the <code>return_book_1</code> label, we use the <code>StubTigger</code> interface, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">stubFinder.trigger('return_book_1')</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Next, we want to listen to the output of the message sent to <code>jms:output</code>:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Exchange receivedMessage = consumerTemplate.receive('jms:output', 5000)</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The received message would then pass the following assertions:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">receivedMessage != null
assertThatBodyContainsBookNameFoo(receivedMessage.in.body)
receivedMessage.in.headers.get('BOOK-NAME') == 'foo'</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-camel-scenario2"><a class="anchor" href="#features-messaging-stub-runner-camel-scenario2"></a><a class="link" href="#features-messaging-stub-runner-camel-scenario2">Scenario 2 (Output Triggered by Input)</a></h5>
<div class="paragraph">
<p>Since the route is set for you, you can send a message to the <code>jms:output</code> destination.</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">producerTemplate.
sendBodyAndHeaders('jms:input', new BookReturned('foo'), [sample: 'header'])</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Next, we want to listen to the output of the message sent to <code>jms:output</code>, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Exchange receivedMessage = consumerTemplate.receive('jms:output', 5000)</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The received message would pass the following assertions:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">receivedMessage != null
assertThatBodyContainsBookNameFoo(receivedMessage.in.body)
receivedMessage.in.headers.get('BOOK-NAME') == 'foo'</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-camel-scenario3"><a class="anchor" href="#features-messaging-stub-runner-camel-scenario3"></a><a class="link" href="#features-messaging-stub-runner-camel-scenario3">Scenario 3 (Input with No Output)</a></h5>
<div class="paragraph">
<p>Since the route is set for you, you can send a message to the <code>jms:output</code> destination, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">producerTemplate.
sendBodyAndHeaders('jms:delete', new BookReturned('foo'), [sample: 'header'])</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-messaging-stub-runner-integration"><a class="anchor" href="#features-messaging-stub-runner-integration"></a><a class="link" href="#features-messaging-stub-runner-integration">4.6. Consumer Side Messaging with Spring Integration</a></h3>
<div class="paragraph">
<p>Spring Cloud Contract 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.</p>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-runner-integration-adding"><a class="anchor" href="#features-messaging-stub-runner-integration-adding"></a><a class="link" href="#features-messaging-stub-runner-integration-adding">4.6.1. Adding the Runner to the Project</a></h4>
<div class="paragraph">
<p>You can have both Spring Integration and Spring Cloud Contract Stub Runner on the
classpath. Remember to annotate your test class with <code>@AutoConfigureStubRunner</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-runner-integration-disabling"><a class="anchor" href="#features-messaging-stub-runner-integration-disabling"></a><a class="link" href="#features-messaging-stub-runner-integration-disabling">4.6.2. Disabling the Functionality</a></h4>
<div class="paragraph">
<p>If you need to disable this functionality, set the
<code>stubrunner.integration.enabled=false</code> property.</p>
</div>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-runner-integration-example"><a class="anchor" href="#features-messaging-stub-runner-integration-example"></a><a class="link" href="#features-messaging-stub-runner-integration-example">4.6.3. Examples</a></h4>
<div class="paragraph">
<p>Assume that you have the following Maven repository with deployed stubs for the
<code>integrationService</code> application:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">└── .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</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Further assume the stubs contain the following structure:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">├── META-INF
│   └── MANIFEST.MF
└── repository
├── accurest
│   ├── bookDeleted.groovy
│   ├── bookReturned1.groovy
│   └── bookReturned2.groovy
└── mappings</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Consider the following contracts (numbered 1 and 2):</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Contract.make {
label 'return_book_1'
input {
triggeredBy('bookReturnedTriggered()')
}
outputMessage {
sentTo('output')
body('''{ "bookName" : "foo" }''')
headers {
header('BOOK-NAME', 'foo')
}
}
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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')
}
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Now consider the following Spring Integration Route:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans:beans xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:beans="http://www.springframework.org/schema/beans"
xmlns="http://www.springframework.org/schema/integration"
xsi:schemaLocation="http://www.springframework.org/schema/beans
https://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;</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>These examples lend themselves to three scenarios:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p><a href="#features-messaging-stub-runner-integration-scenario1">Scenario 1 (No Input Message)</a></p>
</li>
<li>
<p><a href="#features-messaging-stub-runner-integration-scenario2">Scenario 2 (Output Triggered by Input)</a></p>
</li>
<li>
<p><a href="#features-messaging-stub-runner-integration-scenario3">Scenario 3 (Input with No Output)</a></p>
</li>
</ol>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-integration-scenario1"><a class="anchor" href="#features-messaging-stub-runner-integration-scenario1"></a><a class="link" href="#features-messaging-stub-runner-integration-scenario1">Scenario 1 (No Input Message)</a></h5>
<div class="paragraph">
<p>To trigger a message from the <code>return_book_1</code> label, use the <code>StubTigger</code> interface, as
follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">stubFinder.trigger('return_book_1')</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The following listing shows how to listen to the output of the message sent to <code>jms:output</code>:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Message&lt;?&gt; receivedMessage = messaging.receive('outputTest')</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The received message would pass the following assertions:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">receivedMessage != null
assertJsons(receivedMessage.payload)
receivedMessage.headers.get('BOOK-NAME') == 'foo'</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-integration-scenario2"><a class="anchor" href="#features-messaging-stub-runner-integration-scenario2"></a><a class="link" href="#features-messaging-stub-runner-integration-scenario2">Scenario 2 (Output Triggered by Input)</a></h5>
<div class="paragraph">
<p>Since the route is set for you, you can send a message to the <code>jms:output</code>
destination, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">messaging.send(new BookReturned('foo'), [sample: 'header'], 'input')</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The following listing shows how to listen to the output of the message sent to <code>jms:output</code>:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Message&lt;?&gt; receivedMessage = messaging.receive('outputTest')</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The received message passes the following assertions:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">receivedMessage != null
assertJsons(receivedMessage.payload)
receivedMessage.headers.get('BOOK-NAME') == 'foo'</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-integration-scenario3"><a class="anchor" href="#features-messaging-stub-runner-integration-scenario3"></a><a class="link" href="#features-messaging-stub-runner-integration-scenario3">Scenario 3 (Input with No Output)</a></h5>
<div class="paragraph">
<p>Since the route is set for you, you can send a message to the <code>jms:input</code> destination, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">messaging.send(new BookReturned('foo'), [sample: 'header'], 'delete')</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-messaging-stub-runner-stream"><a class="anchor" href="#features-messaging-stub-runner-stream"></a><a class="link" href="#features-messaging-stub-runner-stream">4.7. Consumer Side Messaging With Spring Cloud Stream</a></h3>
<div class="paragraph">
<p>Spring Cloud Contract 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.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
If Stub Runner&#8217;s integration with the Stream <code>messageFrom</code> or <code>sentTo</code> strings
are resolved first as the <code>destination</code> of a channel and no such <code>destination</code> exists, the
destination is resolved as a channel name.
</td>
</tr>
</table>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
<div class="paragraph">
<p>If you want to use Spring Cloud Stream, remember to add a dependency on
<code>org.springframework.cloud:spring-cloud-stream-test-support</code>, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">Maven</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml">&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;</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Gradle</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">testCompile "org.springframework.cloud:spring-cloud-stream-test-support"</code></pre>
</div>
</div>
</div>
</div>
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-runner-stream-adding"><a class="anchor" href="#features-messaging-stub-runner-stream-adding"></a><a class="link" href="#features-messaging-stub-runner-stream-adding">4.7.1. Adding the Runner to the Project</a></h4>
<div class="paragraph">
<p>You can have both Spring Cloud Stream and Spring Cloud Contract Stub Runner on the
classpath. Remember to annotate your test class with <code>@AutoConfigureStubRunner</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-runner-stream-disabling"><a class="anchor" href="#features-messaging-stub-runner-stream-disabling"></a><a class="link" href="#features-messaging-stub-runner-stream-disabling">4.7.2. Disabling the Functionality</a></h4>
<div class="paragraph">
<p>If you need to disable this functionality, set the <code>stubrunner.stream.enabled=false</code>
property.</p>
</div>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-runner-stream-example"><a class="anchor" href="#features-messaging-stub-runner-stream-example"></a><a class="link" href="#features-messaging-stub-runner-stream-example">4.7.3. Examples</a></h4>
<div class="paragraph">
<p>Assume that you have the following Maven repository with deployed stubs for the
<code>streamService</code> application:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">└── .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</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Further assume the stubs contain the following structure:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">├── META-INF
│   └── MANIFEST.MF
└── repository
├── accurest
│   ├── bookDeleted.groovy
│   ├── bookReturned1.groovy
│   └── bookReturned2.groovy
└── mappings</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Consider the following contracts (numbered 1 and 2):</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Contract.make {
label 'return_book_1'
input { triggeredBy('bookReturnedTriggered()') }
outputMessage {
sentTo('returnBook')
body('''{ "bookName" : "foo" }''')
headers { header('BOOK-NAME', 'foo') }
}
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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') }
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Now consider the following Spring configuration:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">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</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>These examples lend themselves to three scenarios:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#features-messaging-stub-runner-stream-scenario1">Scenario 1 (No Input Message)</a></p>
</li>
<li>
<p><a href="#features-messaging-stub-runner-stream-scenario2">Scenario 2 (Output Triggered by Input)</a></p>
</li>
<li>
<p><a href="#features-messaging-stub-runner-stream-scenario3">Scenario 3 (Input with No Output)</a></p>
</li>
</ul>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-stream-scenario1"><a class="anchor" href="#features-messaging-stub-runner-stream-scenario1"></a><a class="link" href="#features-messaging-stub-runner-stream-scenario1">Scenario 1 (No Input Message)</a></h5>
<div class="paragraph">
<p>To trigger a message from the <code>return_book_1</code> label, use the <code>StubTrigger</code> interface as
follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">stubFinder.trigger('return_book_1')</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The following example shows how to listen to the output of the message sent to a channel whose <code>destination</code> is
<code>returnBook</code>:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Message&lt;?&gt; receivedMessage = messaging.receive('returnBook')</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The received message passes the following assertions:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">receivedMessage != null
assertJsons(receivedMessage.payload)
receivedMessage.headers.get('BOOK-NAME') == 'foo'</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-stream-scenario2"><a class="anchor" href="#features-messaging-stub-runner-stream-scenario2"></a><a class="link" href="#features-messaging-stub-runner-stream-scenario2">Scenario 2 (Output Triggered by Input)</a></h5>
<div class="paragraph">
<p>Since the route is set for you, you can send a message to the <code>bookStorage</code>
<code>destination</code>, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">messaging.send(new BookReturned('foo'), [sample: 'header'], 'bookStorage')</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The following example shows how to listen to the output of the message sent to <code>returnBook</code>:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Message&lt;?&gt; receivedMessage = messaging.receive('returnBook')</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The received message passes the following assertions:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">receivedMessage != null
assertJsons(receivedMessage.payload)
receivedMessage.headers.get('BOOK-NAME') == 'foo'</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-stream-scenario3"><a class="anchor" href="#features-messaging-stub-runner-stream-scenario3"></a><a class="link" href="#features-messaging-stub-runner-stream-scenario3">Scenario 3 (Input with No Output)</a></h5>
<div class="paragraph">
<p>Since the route is set for you, you can send a message to the <code>jms:output</code>
destination, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">messaging.send(new BookReturned('foo'), [sample: 'header'], 'delete')</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-messaging-stub-runner-amqp"><a class="anchor" href="#features-messaging-stub-runner-amqp"></a><a class="link" href="#features-messaging-stub-runner-amqp">4.8. Consumer Side Messaging With Spring AMQP</a></h3>
<div class="paragraph">
<p>Spring Cloud Contract 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.</p>
</div>
<div class="paragraph">
<p>The integration tries to work standalone (that is, without interaction with a running
RabbitMQ message broker). It expects a <code>RabbitTemplate</code> on the application context and
uses it as a spring boot test named <code>@SpyBean</code>. As a result, it can use the Mockito spy
functionality to verify and inspect messages sent by the application.</p>
</div>
<div class="paragraph">
<p>On the message consumer side, the stub runner considers all <code>@RabbitListener</code> annotated
endpoints and all <code>SimpleMessageListenerContainer</code> objects on the application context.</p>
</div>
<div class="paragraph">
<p>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
matches 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.</p>
</div>
<div class="paragraph">
<p>If you need to work with routing keys, you can pass them by using the <code>amqp_receivedRoutingKey</code>
messaging header.</p>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-runner-amqp-adding"><a class="anchor" href="#features-messaging-stub-runner-amqp-adding"></a><a class="link" href="#features-messaging-stub-runner-amqp-adding">4.8.1. Adding the Runner to the Project</a></h4>
<div class="paragraph">
<p>You can have both Spring AMQP and Spring Cloud Contract Stub Runner on the classpath and
set the property <code>stubrunner.amqp.enabled=true</code>. Remember to annotate your test class
with <code>@AutoConfigureStubRunner</code>.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
If you already have Stream and Integration on the classpath, you need
to disable them explicitly by setting the <code>stubrunner.stream.enabled=false</code> and
<code>stubrunner.integration.enabled=false</code> properties.
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-runner-amqp-example"><a class="anchor" href="#features-messaging-stub-runner-amqp-example"></a><a class="link" href="#features-messaging-stub-runner-amqp-example">4.8.2. Examples</a></h4>
<div class="paragraph">
<p>Assume that you have the following Maven repository with a deployed stubs for the
<code>spring-cloud-contract-amqp-test</code> application:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">└── .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</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Further assume that the stubs contain the following structure:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">├── META-INF
│   └── MANIFEST.MF
└── contracts
└── shouldProduceValidPersonData.groovy</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Then consider the following contract:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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"
])
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Now consider the following Spring configuration:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">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</code></pre>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-amqp-triggering"><a class="anchor" href="#features-messaging-stub-runner-amqp-triggering"></a><a class="link" href="#features-messaging-stub-runner-amqp-triggering">Triggering the Message</a></h5>
<div class="paragraph">
<p>To trigger a message using the contract in the preceding section, use the <code>StubTrigger</code> interface as
follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">stubTrigger.trigger("contract-test.person.created.event")</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The message has a destination of <code>contract-test.exchange</code>, so the Spring AMQP stub runner
integration looks for bindings related to this exchange, as the following example shows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Bean
public Binding binding() {
return BindingBuilder.bind(new Queue("test.queue"))
.to(new DirectExchange("contract-test.exchange")).with("#");
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The binding definition binds the queue called <code>test.queue</code>. As a result, the following listener
definition is matched and invoked with the contract message:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Bean
public SimpleMessageListenerContainer simpleMessageListenerContainer(
ConnectionFactory connectionFactory,
MessageListenerAdapter listenerAdapter) {
SimpleMessageListenerContainer container = new SimpleMessageListenerContainer();
container.setConnectionFactory(connectionFactory);
container.setQueueNames("test.queue");
container.setMessageListener(listenerAdapter);
return container;
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Also, the following annotated listener matches and is invoked:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@RabbitListener(bindings = @QueueBinding(value = @Queue("test.queue"),
exchange = @Exchange(value = "contract-test.exchange",
ignoreDeclarationExceptions = "true")))
public void handlePerson(Person person) {
this.person = person;
}</code></pre>
</div>
</div>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
The message is directly handed over to the <code>onMessage</code> method of the
<code>MessageListener</code> associated with the matching <code>SimpleMessageListenerContainer</code>.
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-amqp-configuration"><a class="anchor" href="#features-messaging-stub-runner-amqp-configuration"></a><a class="link" href="#features-messaging-stub-runner-amqp-configuration">Spring AMQP Test Configuration</a></h5>
<div class="paragraph">
<p>In order to avoid Spring AMQP trying to connect to a running broker during our tests, we
configure a mock <code>ConnectionFactory</code>.</p>
</div>
<div class="paragraph">
<p>To disable the mocked <code>ConnectionFactory</code>, set the following property:
<code>stubrunner.amqp.mockConnection=false</code>, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-yaml hljs" data-lang="yaml">stubrunner:
amqp:
mockConnection: false</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-messaging-stub-runner-jms"><a class="anchor" href="#features-messaging-stub-runner-jms"></a><a class="link" href="#features-messaging-stub-runner-jms">4.9. Consumer Side Messaging With Spring JMS</a></h3>
<div class="paragraph">
<p>Spring Cloud Contract Stub Runner&#8217;s messaging module provides an easy way to
integrate with Spring JMS.</p>
</div>
<div class="paragraph">
<p>The integration assumes that you have a running instance of a JMS broker (e.g. <code>activemq</code> embedded broker).</p>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-runner-jms-adding"><a class="anchor" href="#features-messaging-stub-runner-jms-adding"></a><a class="link" href="#features-messaging-stub-runner-jms-adding">4.9.1. Adding the Runner to the Project</a></h4>
<div class="paragraph">
<p>You need to have both Spring JMS and Spring Cloud Contract Stub Runner on the classpath. Remember to annotate your test class
with <code>@AutoConfigureStubRunner</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-runner-jms-example"><a class="anchor" href="#features-messaging-stub-runner-jms-example"></a><a class="link" href="#features-messaging-stub-runner-jms-example">4.9.2. Examples</a></h4>
<div class="paragraph">
<p>Assume that the stub structure looks as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">├── stubs
├── bookDeleted.groovy
├── bookReturned1.groovy
└── bookReturned2.groovy</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Further assume the following test configuration:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">stubrunner:
repository-root: stubs:classpath:/stubs/
ids: my:stubs
stubs-mode: remote
spring:
activemq:
send-timeout: 1000
jms:
template:
receive-timeout: 1000</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Now consider the following contracts (we number them 1 and 2):</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Contract.make {
label 'return_book_1'
input {
triggeredBy('bookReturnedTriggered()')
}
outputMessage {
sentTo('output')
body('''{ "bookName" : "foo" }''')
headers {
header('BOOK-NAME', 'foo')
}
}
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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')
}
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-jms-scenario1"><a class="anchor" href="#features-messaging-stub-runner-jms-scenario1"></a><a class="link" href="#features-messaging-stub-runner-jms-scenario1">Scenario 1 (No Input Message)</a></h5>
<div class="paragraph">
<p>To trigger a message from the <code>return_book_1</code> label, we use the <code>StubTigger</code> interface, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">stubFinder.trigger('return_book_1')</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Next, we want to listen to the output of the message sent to <code>output</code>:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">TextMessage receivedMessage = (TextMessage) jmsTemplate.receive('output')</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The received message would then pass the following assertions:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">receivedMessage != null
assertThatBodyContainsBookNameFoo(receivedMessage.getText())
receivedMessage.getStringProperty('BOOK-NAME') == 'foo'</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-jms-scenario2"><a class="anchor" href="#features-messaging-stub-runner-jms-scenario2"></a><a class="link" href="#features-messaging-stub-runner-jms-scenario2">Scenario 2 (Output Triggered by Input)</a></h5>
<div class="paragraph">
<p>Since the route is set for you, you can send a message to the <code>output</code> destination.</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">jmsTemplate.
convertAndSend('input', new BookReturned('foo'), new MessagePostProcessor() {
@Override
Message postProcessMessage(Message message) throws JMSException {
message.setStringProperty("sample", "header")
return message
}
})</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Next, we want to listen to the output of the message sent to <code>output</code>, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">TextMessage receivedMessage = (TextMessage) jmsTemplate.receive('output')</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The received message would pass the following assertions:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">receivedMessage != null
assertThatBodyContainsBookNameFoo(receivedMessage.getText())
receivedMessage.getStringProperty('BOOK-NAME') == 'foo'</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-jms-scenario3"><a class="anchor" href="#features-messaging-stub-runner-jms-scenario3"></a><a class="link" href="#features-messaging-stub-runner-jms-scenario3">Scenario 3 (Input with No Output)</a></h5>
<div class="paragraph">
<p>Since the route is set for you, you can send a message to the <code>output</code> destination, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">jmsTemplate.
convertAndSend('delete', new BookReturned('foo'), new MessagePostProcessor() {
@Override
Message postProcessMessage(Message message) throws JMSException {
message.setStringProperty("sample", "header")
return message
}
})</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-messaging-stub-runner-kafka"><a class="anchor" href="#features-messaging-stub-runner-kafka"></a><a class="link" href="#features-messaging-stub-runner-kafka">4.10. Consumer Side Messaging With Spring Kafka</a></h3>
<div class="paragraph">
<p>Spring Cloud Contract Stub Runner&#8217;s messaging module provides an easy way to
integrate with Spring Kafka.</p>
</div>
<div class="paragraph">
<p>The integration assumes that you have a running instance of a embedded Kafka broker (via the <code>spring-kafka-test</code> dependency).</p>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-runner-kafka-adding"><a class="anchor" href="#features-messaging-stub-runner-kafka-adding"></a><a class="link" href="#features-messaging-stub-runner-kafka-adding">4.10.1. Adding the Runner to the Project</a></h4>
<div class="paragraph">
<p>You need to have both Spring Kafka, Spring Kafka Test (to run the <code>@EmbeddedBroker</code>) and Spring Cloud Contract Stub Runner on the classpath. Remember to annotate your test class
with <code>@AutoConfigureStubRunner</code>.</p>
</div>
<div class="paragraph">
<p>With Kafka integration, in order to poll for a single message we need to register a consumer upon Spring context startup. That may lead to a situation that, when you&#8217;re on the consumer side, Stub Runner can register an additional consumer for the same group id and topic. That could lead to a situation that only one of the components would actually poll for the message. Since on the consumer side you have both the Spring Cloud Contract Stub Runner and Spring Cloud Contract Verifier classpath, we need to be able to switch off such behaviour. That&#8217;s done automatically via the <code>stubrunner.kafka.initializer.enabled</code> flag, that will disable the Contact Verifier consumer registration. If your application is both the consumer and the producer of a kafka message, you might need to manually toggle that property to <code>false</code> in the base class of your generated tests.</p>
</div>
</div>
<div class="sect3">
<h4 id="features-messaging-stub-runner-kafka-example"><a class="anchor" href="#features-messaging-stub-runner-kafka-example"></a><a class="link" href="#features-messaging-stub-runner-kafka-example">4.10.2. Examples</a></h4>
<div class="paragraph">
<p>Assume that the stub structure looks as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">├── stubs
├── bookDeleted.groovy
├── bookReturned1.groovy
└── bookReturned2.groovy</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Further assume the following test configuration (notice the <code>spring.kafka.bootstrap-servers</code> pointing to the embedded broker&#8217;s IP via <code>${spring.embedded.kafka.brokers}</code>):</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">stubrunner:
repository-root: stubs:classpath:/stubs/
ids: my:stubs
stubs-mode: remote
spring:
kafka:
bootstrap-servers: ${spring.embedded.kafka.brokers}
producer:
properties:
"value.serializer": "org.springframework.kafka.support.serializer.JsonSerializer"
"spring.json.trusted.packages": "*"
consumer:
properties:
"value.deserializer": "org.springframework.kafka.support.serializer.JsonDeserializer"
"value.serializer": "org.springframework.kafka.support.serializer.JsonSerializer"
"spring.json.trusted.packages": "*"
group-id: groupId</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Now consider the following contracts (we number them 1 and 2):</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Contract.make {
label 'return_book_1'
input {
triggeredBy('bookReturnedTriggered()')
}
outputMessage {
sentTo('output')
body('''{ "bookName" : "foo" }''')
headers {
header('BOOK-NAME', 'foo')
}
}
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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')
}
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-kafka-scenario1"><a class="anchor" href="#features-messaging-stub-runner-kafka-scenario1"></a><a class="link" href="#features-messaging-stub-runner-kafka-scenario1">Scenario 1 (No Input Message)</a></h5>
<div class="paragraph">
<p>To trigger a message from the <code>return_book_1</code> label, we use the <code>StubTigger</code> interface, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">stubFinder.trigger('return_book_1')</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Next, we want to listen to the output of the message sent to <code>output</code>:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Message receivedMessage = receiveFromOutput()</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The received message would then pass the following assertions:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">assert receivedMessage != null
assert assertThatBodyContainsBookNameFoo(receivedMessage.getPayload())
assert receivedMessage.getHeaders().get('BOOK-NAME') == 'foo'</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-kafka-scenario2"><a class="anchor" href="#features-messaging-stub-runner-kafka-scenario2"></a><a class="link" href="#features-messaging-stub-runner-kafka-scenario2">Scenario 2 (Output Triggered by Input)</a></h5>
<div class="paragraph">
<p>Since the route is set for you, you can send a message to the <code>output</code> destination.</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Message message = MessageBuilder.createMessage(new BookReturned('foo'), new MessageHeaders([sample: "header",]))
kafkaTemplate.setDefaultTopic('input')
kafkaTemplate.send(message)</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Next, we want to listen to the output of the message sent to <code>output</code>, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Message receivedMessage = receiveFromOutput()</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The received message would pass the following assertions:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">assert receivedMessage != null
assert assertThatBodyContainsBookNameFoo(receivedMessage.getPayload())
assert receivedMessage.getHeaders().get('BOOK-NAME') == 'foo'</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-messaging-stub-runner-kafka-scenario3"><a class="anchor" href="#features-messaging-stub-runner-kafka-scenario3"></a><a class="link" href="#features-messaging-stub-runner-kafka-scenario3">Scenario 3 (Input with No Output)</a></h5>
<div class="paragraph">
<p>Since the route is set for you, you can send a message to the <code>output</code> destination, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">Message message = MessageBuilder.createMessage(new BookReturned('foo'), new MessageHeaders([sample: "header",]))
kafkaTemplate.setDefaultTopic('delete')
kafkaTemplate.send(message)</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="features-stub-runner"><a class="anchor" href="#features-stub-runner"></a><a class="link" href="#features-stub-runner">5. Spring Cloud Contract Stub Runner</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>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.</p>
</div>
<div class="paragraph">
<p>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.</p>
</div>
<div class="sect2">
<h3 id="features-stub-runner-snapshot-versions"><a class="anchor" href="#features-stub-runner-snapshot-versions"></a><a class="link" href="#features-stub-runner-snapshot-versions">5.1. Snapshot Versions</a></h3>
<div class="paragraph">
<p>You can add the additional snapshot repository to your <code>build.gradle</code> file to use snapshot
versions, which are automatically uploaded after every successful build, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">Maven</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml">&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;</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Gradle</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">/*
We need to use the [buildscript {}] section when we have to modify
the classpath for the plugins. If that's not the case this section
can be skipped.
If you don't need to modify the classpath (e.g. add a Pact dependency),
then you can just set the [pluginManagement {}] section in [settings.gradle] file.
// settings.gradle
pluginManagement {
repositories {
// for snapshots
maven {url "https://repo.spring.io/snapshot"}
// for milestones
maven {url "https://repo.spring.io/milestone"}
// for GA versions
gradlePluginPortal()
}
}
*/
buildscript {
repositories {
mavenCentral()
mavenLocal()
maven { url "https://repo.spring.io/snapshot" }
maven { url "https://repo.spring.io/milestone" }
maven { url "https://repo.spring.io/release" }
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-stub-runner-publishing-stubs-as-jars"><a class="anchor" href="#features-stub-runner-publishing-stubs-as-jars"></a><a class="link" href="#features-stub-runner-publishing-stubs-as-jars">5.2. Publishing Stubs as JARs</a></h3>
<div class="paragraph">
<p>The easiest approach to publishing stubs as jars is to centralize the way stubs are kept.
For example, you can keep them as jars in a Maven repository.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
For both Maven and Gradle, the setup comes ready to work. However, you can customize
it if you want to.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The following example shows how to publish stubs as jars:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">Maven</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml">&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 https://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;</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Gradle</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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
}
}
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-stub-runner-core"><a class="anchor" href="#features-stub-runner-core"></a><a class="link" href="#features-stub-runner-core">5.3. Stub Runner Core</a></h3>
<div class="paragraph">
<p>The stub runner core runs stubs for service collaborators. Treating stubs as contracts of
services lets you use stub-runner as an implementation of
<a href="https://martinfowler.com/articles/consumerDrivenContracts.html">Consumer-driven Contracts</a>.</p>
</div>
<div class="paragraph">
<p>Stub Runner lets you 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.</p>
</div>
<div class="sect3">
<h4 id="features-stub-runner-retrieving"><a class="anchor" href="#features-stub-runner-retrieving"></a><a class="link" href="#features-stub-runner-retrieving">5.3.1. Retrieving stubs</a></h4>
<div class="paragraph">
<p>You can pick from the following options of acquiring stubs:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Aether-based solution that downloads JARs with stubs from Artifactory or Nexus</p>
</li>
<li>
<p>Classpath-scanning solution that searches the classpath with a pattern to retrieve stubs</p>
</li>
<li>
<p>Writing your own implementation of the <code>org.springframework.cloud.contract.stubrunner.StubDownloaderBuilder</code> for full customization</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The latter example is described in the <a href="advanced.html#customization-custom-stub-runner">Custom Stub Runner</a> section.</p>
</div>
<div class="sect4">
<h5 id="features-stub-runner-downloading-stub"><a class="anchor" href="#features-stub-runner-downloading-stub"></a><a class="link" href="#features-stub-runner-downloading-stub">Downloading Stubs</a></h5>
<div class="paragraph">
<p>You can control the downloading of stubs with the <code>stubsMode</code> switch. It picks value from the
<code>StubRunnerProperties.StubsMode</code> enumeration. You can use the following options:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>StubRunnerProperties.StubsMode.CLASSPATH</code> (default value): Picks stubs from the classpath</p>
</li>
<li>
<p><code>StubRunnerProperties.StubsMode.LOCAL</code>: Picks stubs from a local storage (for example, <code>.m2</code>)</p>
</li>
<li>
<p><code>StubRunnerProperties.StubsMode.REMOTE</code>: Picks stubs from a remote location</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The following example picks stubs from a local location:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@AutoConfigureStubRunner(repositoryRoot="https://foo.bar", ids = "com.example:beer-api-producer:+:stubs:8095", stubsMode = StubRunnerProperties.StubsMode.LOCAL)</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-stub-runner-classpath-scanning"><a class="anchor" href="#features-stub-runner-classpath-scanning"></a><a class="link" href="#features-stub-runner-classpath-scanning">Classpath scanning</a></h5>
<div class="paragraph">
<p>If you set the <code>stubsMode</code> property to <code>StubRunnerProperties.StubsMode.CLASSPATH</code>
(or set nothing since <code>CLASSPATH</code> is the default value), the classpath is scanned.
Consider the following example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@AutoConfigureStubRunner(ids = {
"com.example:beer-api-producer:+:stubs:8095",
"com.example.foo:bar:1.0.0:superstubs:8096"
})</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>You can add the dependencies to your classpath, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">Maven</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-xml hljs" data-lang="xml">&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.thing1&lt;/groupId&gt;
&lt;artifactId&gt;thing2&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;</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">Gradle</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">testCompile("com.example:beer-api-producer-restdocs:0.0.1-SNAPSHOT:stubs") {
transitive = false
}
testCompile("com.example.thing1:thing2:1.0.0:superstubs") {
transitive = false
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Then the specified locations on your classpath get scanned. For <code>com.example:beer-api-producer-restdocs</code>,
the following locations are scanned:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>/META-INF/com.example/beer-api-producer-restdocs/<strong>*/</strong>.*</p>
</li>
<li>
<p>/contracts/com.example/beer-api-producer-restdocs/<strong>*/</strong>.*</p>
</li>
<li>
<p>/mappings/com.example/beer-api-producer-restdocs/<strong>*/</strong>.*</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>For <code>com.example.thing1:thing2</code>, the following locations are scanned:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>/META-INF/com.example.thing1/thing2/<strong>*/</strong>.*</p>
</li>
<li>
<p>/contracts/com.example.thing1/thing2/<strong>*/</strong>.*</p>
</li>
<li>
<p>/mappings/com.example.thing1/thing2/<strong>*/</strong>.*</p>
</li>
</ul>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
You have to explicitly provide the group and artifact IDs when you package the
producer stubs.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>To achieve proper stub packaging, the producer would set up the contracts as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">└── src
└── test
└── resources
└── contracts
   └── com.example
      └── beer-api-producer-restdocs
      └── nested
      └── contract3.groovy</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>By using the <a href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/blob/2.2.x/producer_with_restdocs/pom.xml">Maven <code>assembly</code> plugin</a> or
<a href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/blob/2.2.x/producer_with_restdocs/build.gradle">Gradle Jar</a> task, you have to create the following
structure in your stubs jar:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">└── META-INF
└── com.example
└── beer-api-producer-restdocs
└── 2.0.0
├── contracts
│   └── nested
   │ └── contract2.groovy
   └── mappings
   └── mapping.json</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>By maintaining this structure, the classpath gets scanned and you can profit from the messaging or
HTTP stubs without the need to download artifacts.</p>
</div>
</div>
<div class="sect4">
<h5 id="features-stub-runner-configuring-http-server-stubs"><a class="anchor" href="#features-stub-runner-configuring-http-server-stubs"></a><a class="link" href="#features-stub-runner-configuring-http-server-stubs">Configuring HTTP Server Stubs</a></h5>
<div class="paragraph">
<p>Stub Runner has a notion of a <code>HttpServerStub</code> that abstracts the underlying
concrete implementation of the HTTP server (for example, WireMock is one of the implementations).
Sometimes, you need to perform some additional tuning (which is concrete for the given implementation) of the stub servers.
To do that, Stub Runner gives you
the <code>httpServerStubConfigurer</code> property that is available in the annotation and the
JUnit rule and is accessible through system properties, where you can provide
your implementation of the <code>org.springframework.cloud.contract.stubrunner.HttpServerStubConfigurer</code>
interface. The implementations can alter
the configuration files for the given HTTP server stub.</p>
</div>
<div class="paragraph">
<p>Spring Cloud Contract Stub Runner comes with an implementation that you
can extend for WireMock:
<code>org.springframework.cloud.contract.stubrunner.provider.wiremock.WireMockHttpServerStubConfigurer</code>.
In the <code>configure</code> method,
you can provide your own custom configuration for the given stub. The use
case might be starting WireMock for the given artifact ID, on an HTTPS port. The following
example shows how to do so:</p>
</div>
<div class="exampleblock">
<div class="title">Example 1. WireMockHttpServerStubConfigurer implementation</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">@CompileStatic
static class HttpsForFraudDetection extends WireMockHttpServerStubConfigurer {
private static final Log log = LogFactory.getLog(HttpsForFraudDetection)
@Override
WireMockConfiguration configure(WireMockConfiguration httpStubConfiguration, HttpServerStubConfiguration httpServerStubConfiguration) {
if (httpServerStubConfiguration.stubConfiguration.artifactId == "fraudDetectionServer") {
int httpsPort = SocketUtils.findAvailableTcpPort()
log.info("Will set HTTPs port [" + httpsPort + "] for fraud detection server")
return httpStubConfiguration
.httpsPort(httpsPort)
}
return httpStubConfiguration
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>You can then reuse it with the <code>@AutoConfigureStubRunner</code> annotation, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">@AutoConfigureStubRunner(mappingsOutputFolder = "target/outputmappings/",
httpServerStubConfigurer = HttpsForFraudDetection)</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Whenever an HTTPS port is found, it takes precedence over the HTTP port.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="features-stub-runner-running-stubs"><a class="anchor" href="#features-stub-runner-running-stubs"></a><a class="link" href="#features-stub-runner-running-stubs">5.3.2. Running stubs</a></h4>
<div class="paragraph">
<p>This section describes how to run stubs. It contains the following topics:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#features-stub-runner-http-stubs">HTTP Stubs</a></p>
</li>
<li>
<p><a href="#features-stub-runner-viewing">Viewing Registered Mappings</a></p>
</li>
<li>
<p><a href="#features-stub-runner-messaging">Messaging Stubs</a></p>
</li>
</ul>
</div>
<div class="sect4">
<h5 id="features-stub-runner-http-stubs"><a class="anchor" href="#features-stub-runner-http-stubs"></a><a class="link" href="#features-stub-runner-http-stubs">HTTP Stubs</a></h5>
<div class="paragraph">
<p>Stubs are defined in JSON documents, whose syntax is defined in <a href="http://wiremock.org/stubbing.html">WireMock documentation</a></p>
</div>
<div class="paragraph">
<p>The following example defines a stub in JSON:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-javascript hljs" data-lang="javascript">{
"request": {
"method": "GET",
"url": "/ping"
},
"response": {
"status": 200,
"body": "pong",
"headers": {
"Content-Type": "text/plain"
}
}
}</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-stub-runner-viewing"><a class="anchor" href="#features-stub-runner-viewing"></a><a class="link" href="#features-stub-runner-viewing">Viewing Registered Mappings</a></h5>
<div class="paragraph">
<p>Every stubbed collaborator exposes a list of defined mappings under the <code>__/admin/</code> endpoint.</p>
</div>
<div class="paragraph">
<p>You can also use the <code>mappingsOutputFolder</code> property to dump the mappings to files.
For the annotation-based approach, it would resembling the following example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@AutoConfigureStubRunner(ids="a.b.c:loanIssuance,a.b.c:fraudDetectionServer",
mappingsOutputFolder = "target/outputmappings/")</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>For the JUnit approach, it resembles the following example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@ClassRule @Shared StubRunnerRule rule = new StubRunnerRule()
.repoRoot("https://some_url")
.downloadStub("a.b.c", "loanIssuance")
.downloadStub("a.b.c:fraudDetectionServer")
.withMappingsOutputFolder("target/outputmappings")</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Then, if you check out the <code>target/outputmappings</code> folder, you would see the following structure;</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">.
├── fraudDetectionServer_13705
└── loanIssuance_12255</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>That means that there were two stubs registered. <code>fraudDetectionServer</code> was registered at port <code>13705</code>
and <code>loanIssuance</code> at port <code>12255</code>. If we take a look at one of the files, we would see (for WireMock)
the mappings available for the given server:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-json hljs" data-lang="json">[{
"id" : "f9152eb9-bf77-4c38-8289-90be7d10d0d7",
"request" : {
"url" : "/name",
"method" : "GET"
},
"response" : {
"status" : 200,
"body" : "fraudDetectionServer"
},
"uuid" : "f9152eb9-bf77-4c38-8289-90be7d10d0d7"
},
...
]</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-stub-runner-messaging"><a class="anchor" href="#features-stub-runner-messaging"></a><a class="link" href="#features-stub-runner-messaging">Messaging Stubs</a></h5>
<div class="paragraph">
<p>Depending on the provided Stub Runner dependency and the DSL, the messaging routes are automatically set up.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-stub-runner-junit"><a class="anchor" href="#features-stub-runner-junit"></a><a class="link" href="#features-stub-runner-junit">5.4. Stub Runner JUnit Rule and Stub Runner JUnit5 Extension</a></h3>
<div class="paragraph">
<p>Stub Runner comes with a JUnit rule that lets you can download and run stubs for a given
group and artifact ID, as the following example shows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@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");
@BeforeClass
@AfterClass
public static void setupProps() {
System.clearProperty("stubrunner.repository.root");
System.clearProperty("stubrunner.classifier");
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>A <code>StubRunnerExtension</code> is also available for JUnit 5. <code>StubRunnerRule</code> and
<code>StubRunnerExtension</code> work in a very similar fashion. After the rule or extension is
executed, Stub Runner connects to your Maven repository and, for the given list of
dependencies, tries to:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Download them</p>
</li>
<li>
<p>Cache them locally</p>
</li>
<li>
<p>Unzip them to a temporary folder</p>
</li>
<li>
<p>Start a WireMock server for each Maven dependency on a random port from the provided
range of ports or the provided port</p>
</li>
<li>
<p>Feed the WireMock server with all JSON files that are valid WireMock definitions</p>
</li>
<li>
<p>Send messages (remember to pass an implementation of <code>MessageVerifier</code> interface)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Stub Runner uses the <a href="https://wiki.eclipse.org/Aether">Eclipse Aether</a> mechanism to download the Maven dependencies.
Check their <a href="https://wiki.eclipse.org/Aether">docs</a> for more information.</p>
</div>
<div class="paragraph">
<p>Since the <code>StubRunnerRule</code> and <code>StubRunnerExtension</code> implement the <code>StubFinder</code> they let
you find the started stubs, as the following example shows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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;
/**
* Contract for finding registered stubs.
*
* @author Marcin Grzejszczak
*/
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
* @param artifactId - artifact id of the stub
* @return URL of a running stub or throws exception if not found
* @throws StubNotFoundException in case of not finding a stub
*/
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
* @throws StubNotFoundException in case of not finding a stub
*/
URL findStubUrl(String ivyNotation) throws StubNotFoundException;
/**
* @return all running stubs
*/
RunningStubs findAllRunningStubs();
/**
* @return the list of Contracts
*/
Map&lt;StubConfiguration, Collection&lt;Contract&gt;&gt; getContracts();
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The following examples provide more detail about using Stub Runner:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">spock</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">@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()
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">junit 4</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@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");
}</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">junit 5</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">// 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");
@BeforeAll
@AfterAll
static void setupProps() {
System.clearProperty("stubrunner.repository.root");
System.clearProperty("stubrunner.classifier");
}
private static String repoRoot() {
try {
return StubRunnerRuleJUnitTest.class.getResource("/m2repo/repository/")
.toURI().toString();
}
catch (Exception e) {
return "";
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>See the <a href="#features-stub-runner-common-properties-junit-spring">Common Properties for JUnit and Spring</a> for more information on
how to apply global configuration of Stub Runner.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
To use the JUnit rule or JUnit 5 extension together with messaging, you have to provide an implementation of the
<code>MessageVerifier</code> interface to the rule builder (for example, <code>rule.messageVerifier(new MyMessageVerifier())</code>).
If you do not do this, then, whenever you try to send a message, an exception is thrown.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="features-stub-runner-rule-maven-settings"><a class="anchor" href="#features-stub-runner-rule-maven-settings"></a><a class="link" href="#features-stub-runner-rule-maven-settings">5.4.1. Maven Settings</a></h4>
<div class="paragraph">
<p>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 by using the properties mentioned above.</p>
</div>
</div>
<div class="sect3">
<h4 id="features-stub-runner-rule-fixed-ports"><a class="anchor" href="#features-stub-runner-rule-fixed-ports"></a><a class="link" href="#features-stub-runner-rule-fixed-ports">5.4.2. Providing Fixed Ports</a></h4>
<div class="paragraph">
<p>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 is to use the fluent API of
JUnit rule.</p>
</div>
</div>
<div class="sect3">
<h4 id="features-stub-runner-rule-fluent-api"><a class="anchor" href="#features-stub-runner-rule-fluent-api"></a><a class="link" href="#features-stub-runner-rule-fluent-api">5.4.3. Fluent API</a></h4>
<div class="paragraph">
<p>When using the <code>StubRunnerRule</code> or <code>StubRunnerExtension</code>, you can add a stub to download
and then pass the port for the last downloaded stub. The following example shows how to do so:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@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");
@BeforeClass
@AfterClass
public static void setupProps() {
System.clearProperty("stubrunner.repository.root");
System.clearProperty("stubrunner.classifier");
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>For the preceding example, the following test is valid:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">then(rule.findStubUrl("loanIssuance"))
.isEqualTo(URI.create("http://localhost:12345").toURL());
then(rule.findStubUrl("fraudDetectionServer"))
.isEqualTo(URI.create("http://localhost:12346").toURL());</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="features-stub-runner-rule-spring"><a class="anchor" href="#features-stub-runner-rule-spring"></a><a class="link" href="#features-stub-runner-rule-spring">5.4.4. Stub Runner with Spring</a></h4>
<div class="paragraph">
<p>Stub Runner with Spring sets up Spring configuration of the Stub Runner project.</p>
</div>
<div class="paragraph">
<p>By providing a list of stubs inside your configuration file, Stub Runner automatically downloads
and registers in WireMock the selected stubs.</p>
</div>
<div class="paragraph">
<p>If you want to find the URL of your stubbed dependency, you can autowire the <code>StubFinder</code> interface and use
its methods, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">@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/",
httpServerStubConfigurer = HttpsForFraudDetection)
@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'
and: 'Fraud Detection is an HTTPS endpoint'
stubFinder.findStubUrl('fraudDetectionServer').toString().startsWith("https")
}
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 {}
@CompileStatic
static class HttpsForFraudDetection extends WireMockHttpServerStubConfigurer {
private static final Log log = LogFactory.getLog(HttpsForFraudDetection)
@Override
WireMockConfiguration configure(WireMockConfiguration httpStubConfiguration, HttpServerStubConfiguration httpServerStubConfiguration) {
if (httpServerStubConfiguration.stubConfiguration.artifactId == "fraudDetectionServer") {
int httpsPort = SocketUtils.findAvailableTcpPort()
log.info("Will set HTTPs port [" + httpsPort + "] for fraud detection server")
return httpStubConfiguration
.httpsPort(httpsPort)
}
return httpStubConfiguration
}
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Doing so depends on the following configuration file:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">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</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Instead of using the properties, you can also use the properties inside the <code>@AutoConfigureStubRunner</code>.
The following example achieves the same result by setting values on the annotation:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">@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/")</code></pre>
</div>
</div>
<div class="paragraph">
<p>Stub Runner Spring registers environment variables in the following manner
for every registered WireMock server. The following example shows Stub Runner IDs for
<code>com.example:thing1</code> and <code>com.example:thing2</code>:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>stubrunner.runningstubs.thing1.port</code></p>
</li>
<li>
<p><code>stubrunner.runningstubs.com.example.thing1.port</code></p>
</li>
<li>
<p><code>stubrunner.runningstubs.thing2.port</code></p>
</li>
<li>
<p><code>stubrunner.runningstubs.com.example.thing2.port</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>You can reference these values in your code.</p>
</div>
<div class="paragraph">
<p>You can also use the <code>@StubRunnerPort</code> annotation to inject the port of a running stub.
The value of the annotation can be the <code>groupid:artifactid</code> or just the <code>artifactid</code>.
The following example works shows Stub Runner IDs for
<code>com.example:thing1</code> and <code>com.example:thing2</code>.</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@StubRunnerPort("thing1")
int thing1Port;
@StubRunnerPort("com.example:thing2")
int thing2Port;</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-stub-runner-cloud"><a class="anchor" href="#features-stub-runner-cloud"></a><a class="link" href="#features-stub-runner-cloud">5.5. Stub Runner Spring Cloud</a></h3>
<div class="paragraph">
<p>Stub Runner can integrate with Spring Cloud.</p>
</div>
<div class="paragraph">
<p>For real life examples, see:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/2.2.x/producer">The producer app sample</a></p>
</li>
<li>
<p><a href="https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/2.2.x/consumer_with_discovery">The consumer app sample</a></p>
</li>
</ul>
</div>
<div class="sect3">
<h4 id="features-stub-runner-cloud-stubbing-discovery"><a class="anchor" href="#features-stub-runner-cloud-stubbing-discovery"></a><a class="link" href="#features-stub-runner-cloud-stubbing-discovery">5.5.1. Stubbing Service Discovery</a></h4>
<div class="paragraph">
<p>The most important feature of <code>Stub Runner Spring Cloud</code> is the fact that it stubs:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>DiscoveryClient</code></p>
</li>
<li>
<p><code>Ribbon</code> <code>ServerList</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>That means that, regardless of whether you use Zookeeper, Consul, Eureka, or anything
else, you do not need that in your tests. We are starting WireMock instances of your
dependencies and we are telling your application, whenever you use <code>Feign</code>, to load a
balanced <code>RestTemplate</code> or <code>DiscoveryClient</code> directly, to call those stubbed servers
instead of calling the real Service Discovery tool.</p>
</div>
<div class="paragraph">
<p>For example, the following test passes:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">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'
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Note that the preceding example requires the following configuration file:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">stubrunner:
idsToServiceIds:
ivyNotation: someValueInsideYourCode
fraudDetectionServer: someNameThatShouldMapFraudDetectionServer</code></pre>
</div>
</div>
</div>
</div>
<div class="sect4">
<h5 id="features-stub-runner-cloud-stubbing-profiles"><a class="anchor" href="#features-stub-runner-cloud-stubbing-profiles"></a><a class="link" href="#features-stub-runner-cloud-stubbing-profiles">Test Profiles and Service Discovery</a></h5>
<div class="paragraph">
<p>In your integration tests, you typically do not want to call either a discovery service (such as Eureka)
or Config Server. That is why you create an additional test configuration in which you want to disable
these features.</p>
</div>
<div class="paragraph">
<p>Due to certain limitations of <a href="https://github.com/spring-cloud/spring-cloud-commons/issues/156"><code>spring-cloud-commons</code></a>,
to achieve this, you have to disable these properties
in a static block such as the following example (for Eureka):</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java"> //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");
}</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="features-stub-runner-additional-config"><a class="anchor" href="#features-stub-runner-additional-config"></a><a class="link" href="#features-stub-runner-additional-config">5.5.2. Additional Configuration</a></h4>
<div class="paragraph">
<p>You can match the <code>artifactId</code> of the stub with the name of your application by using the <code>stubrunner.idsToServiceIds:</code> map.
You can disable Stub Runner Ribbon support by setting <code>stubrunner.cloud.ribbon.enabled</code> to <code>false</code>
You can disable Stub Runner support by setting <code>stubrunner.cloud.enabled</code> to <code>false</code></p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
By default, all service discovery is stubbed. This means that, regardless of whether you have
an existing <code>DiscoveryClient</code>, its results are ignored. However, if you want to reuse it, you can set
<code>stubrunner.cloud.delegate.enabled</code> to <code>true</code>, and then your existing <code>DiscoveryClient</code> results are
merged with the stubbed ones.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The default Maven configuration used by Stub Runner can be tweaked either
by setting the following system properties or by setting the corresponding environment variables:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>maven.repo.local</code>: Path to the custom maven local repository location</p>
</li>
<li>
<p><code>org.apache.maven.user-settings</code>: Path to custom maven user settings location</p>
</li>
<li>
<p><code>org.apache.maven.global-settings</code>: Path to maven global settings location</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-stub-runner-boot"><a class="anchor" href="#features-stub-runner-boot"></a><a class="link" href="#features-stub-runner-boot">5.6. Using the Stub Runner Boot Application</a></h3>
<div class="paragraph">
<p>Spring Cloud Contract Stub Runner Boot is a Spring Boot application that exposes REST endpoints to
trigger the messaging labels and to access WireMock servers.</p>
</div>
<div class="paragraph">
<p>One of the use cases is to run some smoke (end-to-end) tests on a deployed application.
You can check out the <a href="https://github.com/spring-cloud/spring-cloud-pipelines">Spring Cloud Pipelines</a>
project for more information.</p>
</div>
<div class="sect3">
<h4 id="features-stub-runner-boot-server"><a class="anchor" href="#features-stub-runner-boot-server"></a><a class="link" href="#features-stub-runner-boot-server">5.6.1. Stub Runner Server</a></h4>
<div class="paragraph">
<p>To use the Stub Runner Server, add the following dependency:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">compile "org.springframework.cloud:spring-cloud-starter-stub-runner"</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Then annotate a class with <code>@EnableStubRunnerServer</code>, build a fat jar, and it is ready to work.</p>
</div>
<div class="paragraph">
<p>For the properties, see the <a href="#features-stub-runner-rule-spring">Stub Runner Spring</a> section.</p>
</div>
</div>
<div class="sect3">
<h4 id="features-stub-runner-boot-how-fat-jar"><a class="anchor" href="#features-stub-runner-boot-how-fat-jar"></a><a class="link" href="#features-stub-runner-boot-how-fat-jar">5.6.2. Stub Runner Server Fat Jar</a></h4>
<div class="paragraph">
<p>You can download a standalone JAR from Maven (for example, for version 2.0.1.RELEASE)
by running the following commands:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">$ 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=...</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="features-stub-runner-boot-how-cli"><a class="anchor" href="#features-stub-runner-boot-how-cli"></a><a class="link" href="#features-stub-runner-boot-how-cli">5.6.3. Spring Cloud CLI</a></h4>
<div class="paragraph">
<p>Starting from the <code>1.4.0.RELEASE</code> version of the <a href="https://cloud.spring.io/spring-cloud-cli">Spring Cloud CLI</a>
project, you can start Stub Runner Boot by running <code>spring cloud stubrunner</code>.</p>
</div>
<div class="paragraph">
<p>In order to pass the configuration, you can create a <code>stubrunner.yml</code> file in the current working directory,
in a subdirectory called <code>config</code>, or in <code>~/.spring-cloud</code>. The file could resemble the following
example for running stubs installed locally:</p>
</div>
<div class="exampleblock">
<div class="title">Example 2. stubrunner.yml</div>
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-yml hljs" data-lang="yml">stubrunner:
stubsMode: LOCAL
ids:
- com.example:beer-api-producer:+:9876</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Then you can call <code>spring cloud stubrunner</code> from your terminal window to start
the Stub Runner server. It is available at port <code>8750</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="features-stub-runner-boot-endpoints"><a class="anchor" href="#features-stub-runner-boot-endpoints"></a><a class="link" href="#features-stub-runner-boot-endpoints">5.6.4. Endpoints</a></h4>
<div class="paragraph">
<p>Stub Runner Boot offers two endpoints:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#features-stub-runner-boot-endpoints-http">HTTP</a></p>
</li>
<li>
<p><a href="#features-stub-runner-boot-endpoints-messaging">Messaging</a></p>
</li>
</ul>
</div>
<div class="sect4">
<h5 id="features-stub-runner-boot-endpoints-http"><a class="anchor" href="#features-stub-runner-boot-endpoints-http"></a><a class="link" href="#features-stub-runner-boot-endpoints-http">HTTP</a></h5>
<div class="paragraph">
<p>For HTTP, Stub Runner Boot makes the following endpoints available:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>GET <code>/stubs</code>: Returns a list of all running stubs in <code>ivy:integer</code> notation</p>
</li>
<li>
<p>GET <code>/stubs/{ivy}</code>: Returns a port for the given <code>ivy</code> notation (when calling the endpoint <code>ivy</code> can also be <code>artifactId</code> only)</p>
</li>
</ul>
</div>
</div>
<div class="sect4">
<h5 id="features-stub-runner-boot-endpoints-messaging"><a class="anchor" href="#features-stub-runner-boot-endpoints-messaging"></a><a class="link" href="#features-stub-runner-boot-endpoints-messaging">Messaging</a></h5>
<div class="paragraph">
<p>For Messaging, Stub Runner Boot makes the following endpoints available:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>GET <code>/triggers</code>: Returns a list of all running labels in <code>ivy : [ label1, label2 &#8230;&#8203;]</code> notation</p>
</li>
<li>
<p>POST <code>/triggers/{label}</code>: Runs a trigger with <code>label</code></p>
</li>
<li>
<p>POST <code>/triggers/{ivy}/{label}</code>: Runs a trigger with a <code>label</code> for the given <code>ivy</code> notation
(when calling the endpoint, <code>ivy</code> can also be <code>artifactId</code> only)</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect3">
<h4 id="features-stub-runner-boot-endpoints-example"><a class="anchor" href="#features-stub-runner-boot-endpoints-example"></a><a class="link" href="#features-stub-runner-boot-endpoints-example">5.6.5. Example</a></h4>
<div class="paragraph">
<p>The following example shows typical usage of Stub Runner Boot:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">@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=")
}
}</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="features-stub-runner-boot-service-discovery"><a class="anchor" href="#features-stub-runner-boot-service-discovery"></a><a class="link" href="#features-stub-runner-boot-service-discovery">5.6.6. Stub Runner Boot with Service Discovery</a></h4>
<div class="paragraph">
<p>One way to use Stub Runner Boot is to use it as a feed of stubs for &#8220;smoke tests&#8221;. What does that mean?
Assume that you do not want to deploy 50 microservices to a test environment in order
to see whether your application works. You have already executed a suite of tests during the build process,
but you would also like to ensure that the packaging of your application works. You can
deploy your application to an environment, start it, and run a couple of tests on it to see whether
it works. We can call those tests &#8220;smoke tests&#8221;, because their purpose is to check only a handful
of testing scenarios.</p>
</div>
<div class="paragraph">
<p>The problem with this approach is thatm if you use microservices, you most likely also
use a service discovery tool. Stub Runner Boot lets you solve this issue by starting the
required stubs and registering them in a service discovery tool. Consider the following example of
such a setup with Eureka (assume that Eureka is already running):</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@SpringBootApplication
@EnableStubRunnerServer
@EnableEurekaClient
@AutoConfigureStubRunner
public class StubRunnerBootEurekaExample {
public static void main(String[] args) {
SpringApplication.run(StubRunnerBootEurekaExample.class, args);
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>We want to start a Stub Runner Boot server (<code>@EnableStubRunnerServer</code>), enable the Eureka client (<code>@EnableEurekaClient</code>),
and have the stub runner feature turned on (<code>@AutoConfigureStubRunner</code>).</p>
</div>
<div class="paragraph">
<p>Now assume that we want to start this application so that the stubs get automatically registered.
We can do so by running the application with <code>java -jar ${SYSTEM_PROPS} stub-runner-boot-eureka-example.jar</code>, where
<code>${SYSTEM_PROPS}</code> contains the following list of properties:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">* -Dstubrunner.repositoryRoot=https://repo.spring.io/snapshot (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</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>That way, your deployed application can send requests to started WireMock servers through service
discovery. Most likely, points 1 through 3 could be set by default in <code>application.yml</code>, because 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.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-stub-runner-stubs-per-consumer"><a class="anchor" href="#features-stub-runner-stubs-per-consumer"></a><a class="link" href="#features-stub-runner-stubs-per-consumer">5.7. Consumer-Driven Contracts: Stubs Per Consumer</a></h3>
<div class="paragraph">
<p>There are cases in which two consumers of the same endpoint want to have two different responses.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
This approach also lets you immediately know which consumer uses which part of your API.
You can remove part of a response that your API produces and see which of your autogenerated tests
fails. If none fails, you can safely delete that part of the response, because nobody uses it.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Consider the following example of a contract defined for the producer called <code>producer</code>,
which has two consumers (<code>foo-consumer</code> and <code>bar-consumer</code>):</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="title">Consumer <code>foo-service</code></div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">request {
url '/foo'
method GET()
}
response {
status OK()
body(
foo: "foo"
}
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="title">Consumer <code>bar-service</code></div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">request {
url '/bar'
method GET()
}
response {
status OK()
body(
bar: "bar"
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>You cannot produce two different responses for the same request. That is why you can properly package the
contracts and then profit from the <code>stubsPerConsumer</code> feature.</p>
</div>
<div class="paragraph">
<p>On the producer side, the consumers can have a folder that contains contracts related only to them.
By setting the <code>stubrunner.stubs-per-consumer</code> flag to <code>true</code>, we no longer register all stubs but only those that
correspond to the consumer application&#8217;s name. In other words, we scan the path of every stub and,
if it contains a subfolder with name of the consumer in the path, only then is it registered.</p>
</div>
<div class="paragraph">
<p>On the <code>foo</code> producer side the contracts would look like this</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">.
└── contracts
├── bar-consumer
│   ├── bookReturnedForBar.groovy
│   └── shouldCallBar.groovy
└── foo-consumer
├── bookReturnedForFoo.groovy
└── shouldCallFoo.groovy</code></pre>
</div>
</div>
<div class="paragraph">
<p>The <code>bar-consumer</code> consumer can either set the <code>spring.application.name</code> or the <code>stubrunner.consumer-name</code> to <code>bar-consumer</code>
Alternatively, you can set the test as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">@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 {
...
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Then only the stubs registered under a path that contains <code>bar-consumer</code> in its name (that is, those from the
<code>src/test/resources/contracts/bar-consumer/some/contracts/&#8230;&#8203;</code> folder) are allowed to be referenced.</p>
</div>
<div class="paragraph">
<p>You can also set the consumer name explicitly, as follows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-groovy hljs" data-lang="groovy">@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 {
...
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Then only the stubs registered under a path that contains the <code>foo-consumer</code> in its name (that is, those from the
<code>src/test/resources/contracts/foo-consumer/some/contracts/&#8230;&#8203;</code> folder) are allowed to be referenced.</p>
</div>
<div class="paragraph">
<p>See <a href="https://github.com/spring-cloud/spring-cloud-contract/issues/224">issue 224</a> for more
information about the reasons behind this change.</p>
</div>
</div>
<div class="sect2">
<h3 id="features-stub-runner-stubs-protocol"><a class="anchor" href="#features-stub-runner-stubs-protocol"></a><a class="link" href="#features-stub-runner-stubs-protocol">5.8. Fetching Stubs or Contract Definitions From A Location</a></h3>
<div class="paragraph">
<p>Instead of picking the stubs or contract definitions from
Artifactory / Nexus or Git, one can just want to point to
a location on drive or classpath. This can be especially useful in a multimodule project, where one module wants
to reuse stubs or contracts from another module without
the need to actually install those in a local maven
repository ot commit those changes to Git.</p>
</div>
<div class="paragraph">
<p>In order to achieve this it&#8217;s enough to use the <code>stubs://</code>
protocol when the repository root parameter is set either
in Stub Runner or in a Spring Cloud Contract plugin.</p>
</div>
<div class="paragraph">
<p>In this example the <code>producer</code> project has been successfully
built and stubs were generated under the <code>target/stubs</code> folder. As a consumer one can setup the Stub Runner to pick the stubs from that location using the <code>stubs://</code> protocol.</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">Annotation</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@AutoConfigureStubRunner(
stubsMode = StubRunnerProperties.StubsMode.REMOTE,
repositoryRoot = "stubs://file://location/to/the/producer/target/stubs/",
ids = "com.example:some-producer")</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">JUnit 4 Rule</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Rule
public StubRunnerRule rule = new StubRunnerRule()
.downloadStub("com.example:some-producer")
.repoRoot("stubs://file://location/to/the/producer/target/stubs/")
.stubsMode(StubRunnerProperties.StubsMode.REMOTE);</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">JUnit 5 Extension</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@RegisterExtension
public StubRunnerExtension stubRunnerExtension = new StubRunnerExtension()
.downloadStub("com.example:some-producer")
.repoRoot("stubs://file://location/to/the/producer/target/stubs/")
.stubsMode(StubRunnerProperties.StubsMode.REMOTE);</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Contracts and stubs may be stored in a location, where each producer has its own, dedicated folder for contracts and stub mappings. Under that folder each consumer can have its own setup. To make Stub Runner find the dedicated folder from the provided ids one can pass a property <code>stubs.find-producer=true</code> or a system property <code>stubrunner.stubs.find-producer=true</code> .</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-bash hljs" data-lang="bash">└── com.example <i class="conum" data-value="1"></i><b>(1)</b>
├── some-artifact-id <i class="conum" data-value="2"></i><b>(2)</b>
│   └── 0.0.1
│   ├── contracts <i class="conum" data-value="3"></i><b>(3)</b>
│   │   └── shouldReturnStuffForArtifactId.groovy
│   └── mappings <i class="conum" data-value="4"></i><b>(4)</b>
│   └── shouldReturnStuffForArtifactId.json
└── some-other-artifact-id <i class="conum" data-value="5"></i><b>(5)</b>
├── contracts
│   └── shouldReturnStuffForOtherArtifactId.groovy
└── mappings
└── shouldReturnStuffForOtherArtifactId.json</code></pre>
</div>
</div>
<div class="colist arabic">
<table>
<tr>
<td><i class="conum" data-value="1"></i><b>1</b></td>
<td>group id of the consumers</td>
</tr>
<tr>
<td><i class="conum" data-value="2"></i><b>2</b></td>
<td>consumer with artifact id [some-artifact-id]</td>
</tr>
<tr>
<td><i class="conum" data-value="3"></i><b>3</b></td>
<td>contracts for the consumer with artifact id [some-artifact-id]</td>
</tr>
<tr>
<td><i class="conum" data-value="4"></i><b>4</b></td>
<td>mappings for the consumer with artifact id [some-artifact-id]</td>
</tr>
<tr>
<td><i class="conum" data-value="5"></i><b>5</b></td>
<td>consumer with artifact id [some-other-artifact-id]</td>
</tr>
</table>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">Annotation</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@AutoConfigureStubRunner(
stubsMode = StubRunnerProperties.StubsMode.REMOTE,
repositoryRoot = "stubs://file://location/to/the/contracts/directory",
ids = "com.example:some-producer",
properties="stubs.find-producer=true")</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">JUnit 4 Rule</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java"> static Map&lt;String, String&gt; contractProperties() {
Map&lt;String, String&gt; map = new HashMap&lt;&gt;();
map.put("stubs.find-producer", "true");
return map;
}
@Rule
public StubRunnerRule rule = new StubRunnerRule()
.downloadStub("com.example:some-producer")
.repoRoot("stubs://file://location/to/the/contracts/directory")
.stubsMode(StubRunnerProperties.StubsMode.REMOTE)
.properties(contractProperties());</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">JUnit 5 Extension</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java"> static Map&lt;String, String&gt; contractProperties() {
Map&lt;String, String&gt; map = new HashMap&lt;&gt;();
map.put("stubs.find-producer", "true");
return map;
}
@RegisterExtension
public StubRunnerExtension stubRunnerExtension = new StubRunnerExtension()
.downloadStub("com.example:some-producer")
.repoRoot("stubs://file://location/to/the/contracts/directory")
.stubsMode(StubRunnerProperties.StubsMode.REMOTE)
.properties(contractProperties());</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-stub-runner-generate-stubs-at-runtime"><a class="anchor" href="#features-stub-runner-generate-stubs-at-runtime"></a><a class="link" href="#features-stub-runner-generate-stubs-at-runtime">5.9. Generating Stubs at Runtime</a></h3>
<div class="paragraph">
<p>As a consumer, you might not want to wait for the producer to finish its implementation and then publish their stubs. A solution to this problem can be generation of stubs at runtime.</p>
</div>
<div class="paragraph">
<p>As a producer, when a contract is defined, you are required to make the generated tests pass in order for the stubs to be published. There are cases where you would like to unblock the consumers so that they can fetch the stubs before your tests are actually passing. In this case you should set such contracts as in progress. You can read more about this under the <a href="#contract-dsl-in-progress">Contracts in Progress</a> section. That way your tests will not be generated, but the stubs will.</p>
</div>
<div class="paragraph">
<p>As a consumer, you can toggle a switch to generate stubs at runtime. Stub Runner will ignore all the existing stub mappings and will generate new ones for all the contract definitions. Another option is to pass the <code>stubrunner.generate-stubs</code> system property. Below you can find an example of such setup.</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">Annotation</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@AutoConfigureStubRunner(
stubsMode = StubRunnerProperties.StubsMode.REMOTE,
repositoryRoot = "stubs://file://location/to/the/contracts",
ids = "com.example:some-producer",
generateStubs = true)</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">JUnit 4 Rule</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Rule
public StubRunnerRule rule = new StubRunnerRule()
.downloadStub("com.example:some-producer")
.repoRoot("stubs://file://location/to/the/contracts")
.stubsMode(StubRunnerProperties.StubsMode.REMOTE)
.withGenerateStubs(true);</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">JUnit 5 Extension</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@RegisterExtension
public StubRunnerExtension stubRunnerExtension = new StubRunnerExtension()
.downloadStub("com.example:some-producer")
.repoRoot("stubs://file://location/to/the/contracts")
.stubsMode(StubRunnerProperties.StubsMode.REMOTE)
.withGenerateStubs(true);</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-stub-runner-fail-on-no-stubs"><a class="anchor" href="#features-stub-runner-fail-on-no-stubs"></a><a class="link" href="#features-stub-runner-fail-on-no-stubs">5.10. Fail On No Stubs</a></h3>
<div class="paragraph">
<p>By default Stub Runner will fail if no stubs were found. In order to change that behaviour, just set to <code>false</code> the <code>failOnNoStubs</code> property in the annotation or call the <code>withFailOnNoStubs(false)</code> method on a JUnit Rule or Extension.</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock primary">
<div class="title">Annotation</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@AutoConfigureStubRunner(
stubsMode = StubRunnerProperties.StubsMode.REMOTE,
repositoryRoot = "stubs://file://location/to/the/contracts",
ids = "com.example:some-producer",
failOnNoStubs = false)</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">JUnit 4 Rule</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Rule
public StubRunnerRule rule = new StubRunnerRule()
.downloadStub("com.example:some-producer")
.repoRoot("stubs://file://location/to/the/contracts")
.stubsMode(StubRunnerProperties.StubsMode.REMOTE)
.withFailOnNoStubs(false);</code></pre>
</div>
</div>
<div class="listingblock secondary">
<div class="title">JUnit 5 Extension</div>
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@RegisterExtension
public StubRunnerExtension stubRunnerExtension = new StubRunnerExtension()
.downloadStub("com.example:some-producer")
.repoRoot("stubs://file://location/to/the/contracts")
.stubsMode(StubRunnerProperties.StubsMode.REMOTE)
.withFailOnNoStubs(false);</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-stub-runner-common"><a class="anchor" href="#features-stub-runner-common"></a><a class="link" href="#features-stub-runner-common">5.11. Common Properties</a></h3>
<div class="paragraph">
<p>This section briefly describes common properties, including:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#features-stub-runner-common-properties-junit-spring">Common Properties for JUnit and Spring</a></p>
</li>
<li>
<p><a href="#features-stub-runner-stub-runner-stub-ids">Stub Runner Stubs IDs</a></p>
</li>
</ul>
</div>
<div class="sect3">
<h4 id="features-stub-runner-common-properties-junit-spring"><a class="anchor" href="#features-stub-runner-common-properties-junit-spring"></a><a class="link" href="#features-stub-runner-common-properties-junit-spring">5.11.1. Common Properties for JUnit and Spring</a></h4>
<div class="paragraph">
<p>You can set repetitive properties by using system properties or Spring configuration
properties. The following table shows their names with their default values:</p>
</div>
<table class="tableblock frame-topbot grid-all stretch">
<colgroup>
<col style="width: 33.3333%;">
<col style="width: 33.3333%;">
<col style="width: 33.3334%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Property name</th>
<th class="tableblock halign-left valign-top">Default value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">stubrunner.minPort</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">10000</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Minimum value of a port for a started WireMock with stubs.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">stubrunner.maxPort</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">15000</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum value of a port for a started WireMock with stubs.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">stubrunner.repositoryRoot</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Maven repo URL. If blank, then call the local Maven repo.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">stubrunner.classifier</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">stubs</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Default classifier for the stub artifacts.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">stubrunner.stubsMode</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">CLASSPATH</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">The way you want to fetch and register the stubs</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">stubrunner.ids</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Array of Ivy notation stubs to download.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">stubrunner.username</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional username to access the tool that stores the JARs with
stubs.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">stubrunner.password</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional password to access the tool that stores the JARs with
stubs.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">stubrunner.stubsPerConsumer</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>false</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Set to <code>true</code> if you want to use different stubs for
each consumer instead of registering all stubs for every consumer.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">stubrunner.consumerName</p></td>
<td class="tableblock halign-left valign-top"></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">If you want to use a stub for each consumer and want to
override the consumer name, change this value.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect3">
<h4 id="features-stub-runner-stub-runner-stub-ids"><a class="anchor" href="#features-stub-runner-stub-runner-stub-ids"></a><a class="link" href="#features-stub-runner-stub-runner-stub-ids">5.11.2. Stub Runner Stubs IDs</a></h4>
<div class="paragraph">
<p>You can set the stubs to download in the <code>stubrunner.ids</code> system property. They
use the following pattern:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">groupId:artifactId:version:classifier:port</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>Note that <code>version</code>, <code>classifier</code>, and <code>port</code> are optional.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>If you do not provide the <code>port</code>, a random one is picked.</p>
</li>
<li>
<p>If you do not provide the <code>classifier</code>, the default is used. (Note that you can
pass an empty classifier this way: <code>groupId:artifactId:version:</code>).</p>
</li>
<li>
<p>If you do not provide the <code>version</code>, then <code>+</code> is passed, and the latest one is
downloaded.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p><code>port</code> means the port of the WireMock server.</p>
</div>
<div class="admonitionblock important">
<table>
<tr>
<td class="icon">
<i class="fa icon-important" title="Important"></i>
</td>
<td class="content">
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
<a href="https://wiki.eclipse.org/Aether/New_and_Noteworthy#Version_Ranges">Aether versioning
ranges here</a>.
</td>
</tr>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="features-wiremock"><a class="anchor" href="#features-wiremock"></a><a class="link" href="#features-wiremock">6. Spring Cloud Contract WireMock</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>The Spring Cloud Contract WireMock modules let you use <a href="https://github.com/tomakehurst/wiremock">WireMock</a> in a
Spring Boot application. Check out the
<a href="https://github.com/spring-cloud/spring-cloud-contract/tree/{branch}/samples">samples</a>
for more details.</p>
</div>
<div class="paragraph">
<p>If you have a Spring Boot application that uses Tomcat as an embedded server (which is
the default with <code>spring-boot-starter-web</code>), you can add
<code>spring-cloud-starter-contract-stub-runner</code> to your classpath and add <code>@AutoConfigureWireMock</code>
to use Wiremock in your tests. Wiremock runs as a stub server, and you
can register stub behavior by using a Java API or by using static JSON declarations as part of
your test. The following code shows an example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@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;
@Before
public void setup() {
this.service.setBase("http://localhost:"
+ this.environment.getProperty("wiremock.server.port"));
}
// 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!");
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>To start the stub server on a different port, use (for example),
<code>@AutoConfigureWireMock(port=9999)</code>. For a random port, use a value of <code>0</code>. The stub
server port can be bound in the test application context with the "wiremock.server.port"
property. Using <code>@AutoConfigureWireMock</code> adds a bean of type <code>WiremockConfiguration</code> to
your test application context, where it is cached between methods and classes
having the same context. The same is true for Spring integration tests. Also, you can
inject a bean of type <code>WireMockServer</code> into your test.</p>
</div>
<div class="sect2">
<h3 id="features-wiremock-registering-stubs"><a class="anchor" href="#features-wiremock-registering-stubs"></a><a class="link" href="#features-wiremock-registering-stubs">6.1. Registering Stubs Automatically</a></h3>
<div class="paragraph">
<p>If you use <code>@AutoConfigureWireMock</code>, it registers WireMock JSON stubs from the file
system or classpath (by default, from <code>file:src/test/resources/mappings</code>). You can
customize the locations byusing the <code>stubs</code> attribute in the annotation, which can be an
Ant-style resource pattern or a directory. In the case of a directory, <code><strong>*/</strong>.json</code> is
appended. The following code shows an example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre>@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!");
}
}</pre>
</div>
</div>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Actually, WireMock always loads mappings from <code>src/test/resources/mappings</code> <strong>as
well as</strong> the custom locations in the <code>stubs</code> attribute. To change this behavior, you can
also specify a files root, as described in the next section of this document.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>If you use Spring Cloud Contract&#8217;s default stub jars, your
stubs are stored in the <code>/META-INF/group-id/artifact-id/versions/mappings/</code> folder.
If you want to register all stubs from that location, from all embedded JARs, you can use
the following syntax:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@AutoConfigureWireMock(port = 0, stubs = "classpath*:/META-INF/**/mappings/**/*.json")</code></pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="features-wiremock-using-files"><a class="anchor" href="#features-wiremock-using-files"></a><a class="link" href="#features-wiremock-using-files">6.2. Using Files to Specify the Stub Bodies</a></h3>
<div class="paragraph">
<p>WireMock can read response bodies from files on the classpath or the file system. In the
case of the file system, you can see in the JSON DSL that the response has a <code>bodyFileName</code> instead of a
(literal) <code>body</code>. The files are resolved relative to a root directory (by default,
<code>src/test/resources/__files</code>). To customize this location, you can set the <code>files</code>
attribute in the <code>@AutoConfigureWireMock</code> annotation to the location of the parent
directory (in other words, <code>__files</code> is a subdirectory). You can use Spring resource
notation to refer to <code>file:&#8230;&#8203;</code> or <code>classpath:&#8230;&#8203;</code> locations. Generic URLs are not
supported. A list of values can be given&#8201;&#8212;&#8201;in which case, WireMock resolves the first file
that exists when it needs to find a response body.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
When you configure the <code>files</code> root, it also affects the
automatic loading of stubs, because they come from the root location
in a subdirectory called <code>mappings</code>. The value of <code>files</code> has no
effect on the stubs loaded explicitly from the <code>stubs</code> attribute.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="features-wiremock-junit-rule"><a class="anchor" href="#features-wiremock-junit-rule"></a><a class="link" href="#features-wiremock-junit-rule">6.3. Alternative: Using JUnit Rules</a></h3>
<div class="paragraph">
<p>For a more conventional WireMock experience, you can use JUnit <code>@Rules</code> to start and stop
the server. To do so, use the <code>WireMockSpring</code> convenience class to obtain an <code>Options</code>
instance, as the following example shows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@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 wiremock's port
@Autowired
private Service service;
@Before
public void setup() {
this.service.setBase("http://localhost:" + wiremock.port());
}
// 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!");
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The <code>@ClassRule</code> means that the server shuts down after all the methods in this class
have been run.</p>
</div>
</div>
<div class="sect2">
<h3 id="features-wiremock-relaxed-ssl"><a class="anchor" href="#features-wiremock-relaxed-ssl"></a><a class="link" href="#features-wiremock-relaxed-ssl">6.4. Relaxed SSL Validation for Rest Template</a></h3>
<div class="paragraph">
<p>WireMock lets you stub a &#8220;secure&#8221; server with an <code>https</code> 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 <code>http</code>. If that is not an
option, you can ask Spring to configure an HTTP client that ignores SSL validation errors
(do so only for tests, of course).</p>
</div>
<div class="paragraph">
<p>To make this work with minimum fuss, you need to use the Spring Boot
<code>RestTemplateBuilder</code> in your application, as the following example shows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@Bean
public RestTemplate restTemplate(RestTemplateBuilder builder) {
return builder.build();
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>You need <code>RestTemplateBuilder</code> 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 use the <code>@AutoConfigureWireMock</code>
annotation or the stub runner. If you use the JUnit <code>@Rule</code> approach, you need to add the
<code>@AutoConfigureHttpClient</code> annotation as well, as the following example shows:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@RunWith(SpringRunner.class)
@SpringBootTest("app.baseUrl=https://localhost:6443")
@AutoConfigureHttpClient
public class WiremockHttpsServerApplicationTests {
@ClassRule
public static WireMockClassRule wiremock = new WireMockClassRule(
WireMockSpring.options().httpsPort(6443));
...
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>If you use <code>spring-boot-starter-test</code>, you have the Apache HTTP client on the
classpath, and it is selected by the <code>RestTemplateBuilder</code> and configured to ignore SSL
errors. If you use the default <code>java.net</code> client, you do not need the annotation (but it
does no harm). There is currently no support for other clients, but it may be added
in future releases.</p>
</div>
<div class="paragraph">
<p>To disable the custom <code>RestTemplateBuilder</code>, set the <code>wiremock.rest-template-ssl-enabled</code>
property to <code>false</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="features-wiremock-spring-mvc-mocks"><a class="anchor" href="#features-wiremock-spring-mvc-mocks"></a><a class="link" href="#features-wiremock-spring-mvc-mocks">6.5. WireMock and Spring MVC Mocks</a></h3>
<div class="paragraph">
<p>Spring Cloud Contract provides a convenience class that can load JSON WireMock stubs into
a Spring <code>MockRestServiceServer</code>. The following code shows an example:</p>
</div>
<div class="exampleblock">
<div class="content">
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@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("https://example.org").stubs("classpath:/stubs/resource.json")
.build();
// We're asserting if WireMock responded properly
assertThat(this.service.go()).isEqualTo("Hello World");
server.verify();
}
}</code></pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>The <code>baseUrl</code> value is prepended to all mock calls, and the <code>stubs()</code> method takes a stub
path resource pattern as an argument. In the preceding example, the stub defined at
<code>/stubs/resource.json</code> is loaded into the mock server. If the <code>RestTemplate</code> is asked to
visit <code><a href="https://example.org/" class="bare">example.org/</a></code>, 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 <code>.json</code>), a fixed filename (as in the preceding example), or an Ant-style
pattern. The JSON format is the normal WireMock format, which you can read about at the
<a href="https://wiremock.org/docs/stubbing/">WireMock website</a>.</p>
</div>
<div class="paragraph">
<p>Currently, the Spring Cloud Contract Verifier supports Tomcat, Jetty, and Undertow as
Spring Boot embedded servers, and Wiremock itself has &#8220;native&#8221; 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).</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="features-build-tools"><a class="anchor" href="#features-build-tools"></a><a class="link" href="#features-build-tools">7. Build Tools Integration</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>You can run test generation and stub execution in various ways. The most common ones are
as follows:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="maven-project.html">Maven</a></p>
</li>
<li>
<p><a href="gradle-project.html">Gradle</a></p>
</li>
<li>
<p><a href="docker-project.html">Docker</a></p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="features-whats-next"><a class="anchor" href="#features-whats-next"></a><a class="link" href="#features-whats-next">8. What to Read Next</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>If you want to learn more about any of the classes discussed in this section, you can browse the
<a href="https://github.com/spring-cloud/spring-cloud-contract/tree/master">source code directly</a>. If you have specific questions, see the
<a href="howto.html#howto">how-to</a> section.</p>
</div>
<div class="paragraph">
<p>If you are comfortable with Spring Cloud Contract&#8217;s core features, you can continue on and read
about
<a href="#advanced.adoc">Spring Cloud Contract&#8217;s advanced features</a>.</p>
</div>
</div>
</div>
</div>
<script type="text/javascript" src="js/tocbot/tocbot.min.js"></script>
<script type="text/javascript" src="js/toc.js"></script>
<link rel="stylesheet" href="js/highlight/styles/atom-one-dark-reasonable.min.css">
<script src="js/highlight/highlight.min.js"></script>
<script>hljs.initHighlighting()</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink