@@ -552,7 +592,7 @@ is why you should use the Groovy Map notation.
-
+
The following sections describe the most common top-level elements:
@@ -576,7 +616,7 @@ is why you should use the Groovy Map notation.
-
+
You can add a description to your contract. The description is arbitrary text. The
following code shows an example:
@@ -652,11 +692,19 @@ response:
command: andMeToo($it)
+
java
+
+
Contract.make(c -> {
+ c.description("Some description");
+}));
+
+
-
+
You can provide a name for your contract. Assume that you provided the following name:
should register a user. If you do so, the name of the autogenerated test is
@@ -697,11 +745,19 @@ override each other.
name: some name
+
java
+
+
Contract.make(c -> {
+ c.name("some name");
+}));
+
+
-
+
If you want to ignore a contract, you can either set a value for ignored contracts in the
plugin configuration or set the ignored property on the contract itself. The following
@@ -723,11 +779,19 @@ example shows how to do so:
ignored: true
+
java
+
+
Contract.make(c -> {
+ c.ignored();
+}));
+
+
-
+
A contract in progress will not generate tests on the producer side, but will allow generation of stubs.
@@ -763,6 +827,14 @@ example shows how to do so:
inProgress: true
+
java
+
+
Contract.make(c -> {
+ c.inProgress();
+}));
+
+
@@ -770,7 +842,7 @@ example shows how to do so:
-
+
Starting with version 1.2.0, you can pass values from files. Assume that you have the
following resources in your project:
@@ -843,6 +915,12 @@ response:
bodyFromFile: response.json
@@ -875,7 +953,7 @@ relative to the folder in which the contract lays.
If you need to pass the contents of a file in binary form,
-you can use the fileAsBytes method in Groovy DSL or a bodyFromFileAsBytes field in YAML.
+you can use the
fileAsBytes method in the coded DSL or a
bodyFromFileAsBytes field in YAML.
The following example shows how to pass the contents of binary files:
@@ -922,6 +1000,42 @@ response:
Content-Type: application/octet-stream
+
+
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<Collection<Contract>> {
+
+ @Override
+ public Collection<Contract> get() {
+ return Collections.singletonList(Contract.make(c -> {
+ c.request(r -> {
+ r.url("/1");
+ r.method(r.PUT());
+ r.body(r.fileAsBytes("request.pdf"));
+ r.headers(h -> {
+ h.contentType(h.applicationOctetStream());
+ });
+ });
+ c.response(r -> {
+ r.status(r.OK());
+ r.body(r.fileAsBytes("response.pdf"));
+ r.headers(h -> {
+ h.contentType(h.applicationOctetStream());
+ });
+ });
+ }));
+ }
+
+}
+// end::class[]
+
+
@@ -1013,6 +1127,34 @@ response:
...
+
+
java
+
+
org.springframework.cloud.contract.spec.Contract.make(c -> {
+ // 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 -> {
+ 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 -> {
+ r.status(200);
+ // ...
+ });
+
+ // Contract priority, which can be used for overriding
+ // contracts (1 is highest). Priority is optional.
+ c.priority(1);
+});
+
+
@@ -1067,6 +1209,25 @@ same information is mandatory in request definition of the contract.
url: /foo
+
+
java
+
+
org.springframework.cloud.contract.spec.Contract.make(c -> {
+ c.request(r -> {
+ // 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 -> {
+ // ...
+ r.status(200);
+ });
+});
+
+
@@ -1104,6 +1265,24 @@ the recommended way, as doing so makes the tests be host-independent.
urlPath: /foo
+
+
java
+
+
org.springframework.cloud.contract.spec.Contract.make(c -> {
+ c.request(r -> {
+ r.method("GET");
+
+ // Specifying `url` and `urlPath` in one contract is illegal.
+ r.url("http://localhost:8888/users");
+ });
+
+ c.response(r -> {
+ // ...
+ r.status(200);
+ });
+});
+
+
@@ -1169,6 +1348,60 @@ queryParameters:
b: c
+
+
java
+
+
org.springframework.cloud.contract.spec.Contract.make(c -> {
+ c.request(r -> {
+ // ...
+ r.method(r.GET());
+
+ r.urlPath("/users", u -> {
+
+ // 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 -> {
+
+ // 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 -> {
+ // ...
+ r.status(200);
+ });
+});
+
+
@@ -1212,6 +1445,32 @@ headers:
fooReq: baz
+
+
java
+
+
org.springframework.cloud.contract.spec.Contract.make(c -> {
+ c.request(r -> {
+ // ...
+ 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 -> {
+ h.header("key", "value");
+ h.contentType(h.applicationJson());
+ });
+
+ // ...
+ });
+
+ c.response(r -> {
+ // ...
+ r.status(200);
+ });
+});
+
+
@@ -1255,6 +1514,32 @@ cookies:
fooReq: baz
+
+
java
+
+
org.springframework.cloud.contract.spec.Contract.make(c -> {
+ c.request(r -> {
+ // ...
+ 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 -> {
+ ck.cookie("key", "value");
+ ck.cookie("another_key", "another_value");
+ });
+
+ // ...
+ });
+
+ c.response(r -> {
+ // ...
+ r.status(200);
+ });
+});
+
+
@@ -1292,6 +1577,27 @@ body:
foo: bar
+
+
java
+
+
org.springframework.cloud.contract.spec.Contract.make(c -> {
+ c.request(r -> {
+ // ...
+ 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 -> {
+ // ...
+ r.status(200);
+ });
+});
+
+
@@ -1383,13 +1689,19 @@ response:
status: 200
+
In the preceding example, we define parameters in either of two ways:
-
Groovy DSL
+
Coded DSL
-
Directly, by using the map notation, where the value can be a dynamic property (such as
@@ -1522,6 +1834,23 @@ following code shows an example:
status: 200
+
java
+
+
org.springframework.cloud.contract.spec.Contract.make(c -> {
+ c.request(r -> {
+ // ...
+ r.method(r.GET());
+ r.url("/foo");
+ });
+ c.response(r -> {
+ // Status code sent by the server
+ // in response to request specified above.
+ r.status(r.OK());
+ });
+});
+
+
@@ -1580,7 +1909,7 @@ See the
-This section is valid only for the Groovy DSL. Check out the
+This section is valid only for the Coded DSL (Groovy, Java etc.). Check out the
Dynamic Properties in the Matchers Sections section for YAML examples of a similar feature.
|
@@ -1648,7 +1977,10 @@ There are several additional known lim
The following example shows how to use regular expressions to write a request:
-
+
+
+
+
groovy
org.springframework.cloud.contract.spec.Contract.make {
request {
@@ -1676,10 +2008,32 @@ There are several additional known lim
}
+
+
java
+
+
org.springframework.cloud.contract.spec.Contract.make(c -> {
+ c.request(r -> {
+ r.method("GET");
+ r.url(r.$(r.consumer(r.regex("\\/[0-9]{2}")), r.producer("/12")));
+ });
+ c.response(r -> {
+ 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 -> {
+ h.header("Content-Type", "text/plain");
+ });
+ });
+});
+
+
+
+
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:
+the provided regular expression. The following code shows an example for Groovy:
@@ -1860,7 +2214,7 @@ public RegexProperty isoTime() {
-
In your contract, you can use it as follows:
+
In your contract, you can use it as follows (example for the Groovy DSL):
@@ -1941,7 +2295,7 @@ T anyOf(String... values);
-
The following example shows how you can reference those methods:
+
The following example shows how you can reference those methods (example for Groovy DSL):
@@ -2042,7 +2396,10 @@ optional parameters only for the following:
The following example shows how to provide optional parameters:
-
+
+
+
+
groovy
org.springframework.cloud.contract.spec.Contract.make {
priority 1
@@ -2070,6 +2427,38 @@ optional parameters only for the following:
}
+
+
java
+
+
org.springframework.cloud.contract.spec.Contract.make(c -> {
+ c.priority(1);
+ c.name("optionals");
+ c.request(r -> {
+ r.method("POST");
+ r.url("/users/password");
+ r.headers(h -> {
+ 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 -> {
+ r.status(404);
+ r.headers(h -> {
+ h.header("Content-Type", "application/json");
+ });
+ r.body(ContractVerifierUtil.map().entry("code", r.value(
+ r.consumer("123123"), r.producer(r.optional("123123")))));
+ });
+});
+
+
+
+
By wrapping a part of the body with the optional() method, you create a regular
expression that must be present 0 or more times.
@@ -2077,7 +2466,10 @@ expression that must be present 0 or more times.
If you use Spock, the following test would be generated from the previous example:
+
+
+
groovy
"""\
package com.example
@@ -2119,6 +2511,8 @@ class FooSpec extends Specification {
"""
+
+
The following stub would also be generated:
@@ -2173,11 +2567,22 @@ This section is valid only for Groovy DSL. Check out the
method can be added to the class defined as
baseClassForTests in the configuration. The
following code shows an example of the contract portion of the test case:
-
+
The following code shows the base class portion of the test case:
@@ -2338,7 +2743,7 @@ matches the JSON Path.
-
If you use the YAML contract definition, you have to use the
+
If you use the YAML contract definition or the Java one, you have to use the
Handlebars {{{ }}} notation with custom Spring Cloud Contract
functions to achieve this. In that case, you can use the following options:
@@ -2492,6 +2897,46 @@ response:
responseBaz2: "Bla bla {{{ jsonpath this '$.foo' }}} bla bla"
+
+
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<Contract> {
+
+ @Override
+ public Contract get() {
+ return Contract.make(c -> {
+ c.request(r -> {
+ r.method("POST");
+ r.url("/stats");
+ r.body(map().entry("name", r.anyAlphaUnicode()));
+ r.headers(h -> {
+ h.contentType(h.applicationJson());
+ });
+ });
+ c.response(r -> {
+ 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 -> {
+ h.contentType(h.applicationJson());
+ });
+ });
+ });
+ }
+
+}
+
+
@@ -2643,7 +3088,7 @@ contract.
following matching possibilities:
-
+
-
@@ -3494,6 +3939,27 @@ provide an
async() method in the response section. The
async: true
+
java
+
+
class contract implements Supplier<Collection<Contract>> {
+
+ @Override
+ public Collection<Contract> get() {
+ return Collections.singletonList(Contract.make(c -> {
+ c.request(r -> {
+ // ...
+ });
+ c.response(r -> {
+ r.async();
+ // ...
+ });
+ }));
+ }
+
+}
+
+
@@ -3525,6 +3991,27 @@ The following example shows how to do so:
fixedDelayMilliseconds: 1000
+
+
java
+
+
class contract implements Supplier<Collection<Contract>> {
+
+ @Override
+ public Collection<Contract> get() {
+ return Collections.singletonList(Contract.make(c -> {
+ c.request(r -> {
+ // ...
+ });
+ c.response(r -> {
+ r.fixedDelayMilliseconds(1000);
+ // ...
+ });
+ }));
+ }
+
+}
+
+
MatchingType as second. All the body matchers a
yml
-
include::/opt/jenkins/data/workspace/spring-cloud-contract-master-releaser/spring-cloud-contract-verifier/src/test/resources/yml/contract_rest_xml.yml
+
include::/opt/jenkins/data/workspace/spring-cloud-contract-master-ci/spring-cloud-contract-verifier/src/test/resources/yml/contract_rest_xml.yml
+
+
+
@@ -3695,6 +4188,28 @@ response:
status: 200
+
+
java
+
+
class contract implements Supplier<Collection<Contract>> {
+
+ @Override
+ public Collection<Contract> get() {
+ return Arrays.asList(
+ Contract.make(c -> {
+ c.name("should post a user");
+ // ...
+ }), Contract.make(c -> {
+ // ...
+ }), Contract.make(c -> {
+ // ...
+ })
+ );
+ }
+
+}
+
+
@@ -3855,12 +4370,9 @@ name of scenario1 and the three following steps:
-
-
Spring Cloud Contract also generates tests with a guaranteed order of execution.
-