Remember that, inside the contract file, you have to provide the fully
qualified name to the Contract class and make static imports, such as
org.springframework.cloud.spec.Contract.make { … }. You can also provide an import to
the Contract class: import org.springframework.cloud.spec.Contract and then call
@@ -52,13 +52,13 @@ Cloud Contract Verifier repository.
The following is a complete exampl
}
}
Note
The preceding example does not contain all the features of the DSL appear. The
remainder of this section describes the other features.
You can compile Contracts to WireMock stubs mapping using standalone maven command:
-mvn org.springframework.cloud:spring-cloud-contract-maven-plugin:convert
8.1 Limitations
Warning
Spring Cloud Contract Verifier does not properly support XML. Please use JSON or
+mvn org.springframework.cloud:spring-cloud-contract-maven-plugin:convert
7.1 Limitations
Warning
Spring Cloud Contract Verifier does not properly support XML. Please use JSON or
help us implement this feature.
Warning
The support for verifying the size of JSON arrays is experimental. If you want
to turn it on, please set the value of the following system property to true:
spring.cloud.contract.verifier.assert.size. By default, this feature is set to false.
You can also provide the assertJsonSize property in the plugin configuration.
Warning
Because JSON structure can have any form, it can be impossible to parse it
properly when using the value(consumer(…), producer(…)) notation in GString. That
-is why you should use the Groovy Map notation.
8.2 Common Top-Level elements
The following sections describe the most common top-level elements:
You can provide a name for your contract. Assume that you provided the following name:
+ }
7.2.2 Name
You can provide a name for your contract. Assume that you provided the following name:
should register a user. If you do so, the name of the autogenerated test is
validate_should_register_a_user. Also, the name of the stub in a WireMock stub is
should_register_a_user.json.
Important
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.
8.2.3 Ignoring Contracts
If you want to ignore a contract, you can either set a value of ignored contracts in the
+override each other.
7.2.3 Ignoring Contracts
If you want to ignore a contract, you can either set a value of ignored contracts in the
plugin configuration or set the ignored property on the contract itself:
When test or stub generation takes place, the contents of the file is passed to the body
of a request or a response. That works because of the file(…) method. The argument of
that method needs to be a file with location relative to the folder in which the contract
-lays.
8.2.5 HTTP Top-Level Elements
The following methods can be called in the top-level closure of a contract definition.
+lays.
7.2.5 HTTP Top-Level Elements
The following methods can be called in the top-level closure of a contract definition.
request and response are mandatory. priority is optional.
org.springframework.cloud.contract.spec.Contract.make {
// Definition of HTTP request part of the contract// (this can be a valid request or invalid depending
@@ -125,7 +125,7 @@ lays.
// Contract priority, which can be used for overriding
// contracts (1 is highest). Priority is optional.
priority 1
-}
8.3 Request
The HTTP protocol requires only method and address to be specified in a request. The
+}
7.3 Request
The HTTP protocol requires only method and address to be specified in a request. The
same information is mandatory in request definition of the Contract.
org.springframework.cloud.contract.spec.Contract.make {
request {
// HTTP request method (GET/POST/PUT/DELETE).
@@ -283,7 +283,7 @@ such as named("fileName", "fileContent"), or via a
"transformers" : ["response-template","foo-transformer"]}}
- '''
8.4 Response
The response must contain an HTTP status code and may contain other information. The
+ '''
7.4 Response
The response must contain an HTTP status code and may contain other information. The
following code shows an example:
org.springframework.cloud.contract.spec.Contract.make {
request {
//...
@@ -294,11 +294,11 @@ following code shows an example:
org.springframew
status 200
}
}
Besides status, the response may contain headers and a body, both of which are
-specified the same way as in the request (see the previous paragraph).
8.5 Dynamic properties
The contract can contain some dynamic properties: timestamps, IDs, and so on. You do not
+specified the same way as in the request (see the previous paragraph).
7.5 Dynamic properties
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. You can provide the dynamic parts in your contracts
in two ways: pass them directly in the body or set them in separate sections called
-testMatchers and stubMatchers.
8.5.1 Dynamic properties inside the body
You can set the properties inside the body either with the value method or, if you use
+testMatchers and stubMatchers.
7.5.1 Dynamic properties inside the body
You can set the properties inside the body either with the value method or, if you use
the Groovy map notation, with $(). The following example shows how to set dynamic
properties with the value method:
The following example shows how to set d
$(c(...), p(...))
$(stub(...), test(...))
$(client(...), server(...))
Both approaches work equally well. stub and client methods are aliases over the consumer
-method. Subsequent sections take a closer look at what you can do with those values.
8.5.2 Regular expressions
You can use regular expressions to write your requests in Contract DSL. Doing so is
+method. Subsequent sections take a closer look at what you can do with those values.
7.5.2 Regular expressions
You can use regular expressions to write your requests in Contract DSL. Doing so is
particularly useful when you want to indicate that a given response should be provided
for requests that follow a given pattern. Also, you can use regular expressions when you
need to use patterns and not exact values both for your test and your server side tests.
The following example shows how to use regular expressions to write a request:
org.springframework.cloud.contract.spec.Contract.make {
@@ -453,7 +453,7 @@ String nonBlank() {
message: "User not found by email = [${value(producer(regex(email())), consumer('not.existing@user.com'))}]"
)
}
-}
8.5.3 Passing Optional Parameters
It is possible to provide optional parameters in your contract. However, you can provide
+}
7.5.3 Passing Optional Parameters
It is possible to provide optional parameters in your contract. However, you can provide
optional parameters only for the following:
STUB side of the Request
TEST side of the Response
The following example shows how to provide optional parameters:
org.springframework.cloud.contract.spec.Contract.make {
priority 1
request {
@@ -518,7 +518,7 @@ expression that must be present 0 or more times.
If you use Spock for, the
},
"priority" : 1
}
-'''
8.5.4 Executing Custom Methods on the Server Side
You can define a method call that executes on the server side during the test. Such a
+'''
7.5.4 Executing Custom Methods on the Server Side
You can define a method call that executes on the server side during the test. Such a
method can be added to the class defined as "baseClassForTests" in the configuration. The
following code shows an example of the contract portion of the test case:
org.springframework.cloud.contract.spec.Contract.make {
request {
@@ -581,7 +581,7 @@ It should resemble the following code:
The best situation is to provide fixed values, but sometimes you need to reference a
+ assertThat(response.statusCode()).isEqualTo(200);
7.5.5 Referencing the Request from the Response
The best situation is to provide fixed values, but sometimes you need to reference a
request in your response. To do so, you can use the fromRequest() method, which lets
you reference a bunch of elements from the HTTP request. You can use the following
options:
fromRequest().url(): Returns the request URL and query parameters.
fromRequest().query(String key): Returns the first query parameter with a given name.
fromRequest().query(String key, int index): Returns the nth query parameter with a
@@ -691,7 +691,7 @@ in sending the following response body:
}
Important
This feature works only with WireMock having a version greater than or equal
to 2.5.1. The Spring Cloud Contract Verifier uses WireMock’s
response-template response transformer. It uses Handlebars to convert the Mustache {{{ }}} templates into
-proper values. Additionally, it registers two helper functions:
escapejsonbody: Escapes the request body in a format that can be embedded in a JSON.
jsonpath: For a given parameter, find an object in the request body.
8.5.6 Registering Your Own WireMock Extension
WireMock lets you register custom extensions. By default, Spring Cloud Contract registers
+proper values. Additionally, it registers two helper functions:
escapejsonbody: Escapes the request body in a format that can be embedded in a JSON.
jsonpath: For a given parameter, find an object in the request body.
7.5.6 Registering Your Own WireMock Extension
WireMock lets you register custom extensions. By default, Spring Cloud Contract registers
the transformer, which lets you reference a request from a response. If you want to
provide your own extensions, you can register an implementation of the
org.springframework.cloud.contract.verifier.dsl.wiremock.WireMockExtensions interface.
@@ -723,7 +723,7 @@ org.springframework.cloud.contract.stubrunner.provider.wiremock.TestWireMockExte
}
}
Important
Remember to override the applyGlobally() method and set it to false if you
-want the transformation to be applied only for a mapping that explicitly requires it.
8.5.7 Dynamic Properties in the Matchers Sections
If you work with Pact, the following discussion may seem familiar.
+want the transformation to be applied only for a mapping that explicitly requires it.
7.5.7 Dynamic Properties in the Matchers Sections
If you work with Pact, the following discussion may seem familiar.
Quite a few users are used to having a separation between the body and setting the
dynamic parts of a contract.
You can use two separate sections:
stubMatchers, which lets you define the dynamic values that should end up in a stub.
You can set it in the request or inputMessage part of your contract.
testMatchers, which is present in the response or outputMessage side of the
@@ -994,7 +994,7 @@ and:
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(".+")
As you can see, the assertion is malformed. Only the first element of the array got
asserted. In order to fix this, you should apply the assertion to the whole $.events
-collection and assert it with the byCommand(…) method.
8.6 JAX-RS Support
The Spring Cloud Contract Verifier supports the JAX-RS 2 Client API. The base class needs
+collection and assert it with the byCommand(…) method.
7.6 JAX-RS Support
The Spring Cloud Contract Verifier supports the JAX-RS 2 Client API. The base class needs
to define protected WebTarget webTarget and server initialization. The only option for
testing JAX-RS API is to start a web server. Also, a request with a body needs to have a
content type set. Otherwise, the default of application/octet-stream gets used.
In order to use JAX-RS mode, use the following settings:
testMode == 'JAXRSCLIENT'
The following example shows a generated test API:
'''
@@ -1019,7 +1019,7 @@ content type set. Otherwise, the default of application/oc
// and:
DocumentContext parsedJson = JsonPath.parse(responseAsString);
assertThatJson(parsedJson).field("['property1']").isEqualTo("a");
-'''
8.7 Async Support
If you’re using asynchronous communication on the server side (your controllers are
+'''
7.7 Async Support
If you’re using asynchronous communication on the server side (your controllers are
returning Callable, DeferredResult, and so on), then, inside your contract, you must
provide a sync() method in the response section. The following code shows an example:
org.springframework.cloud.contract.spec.Contract.make {
request {
@@ -1031,7 +1031,7 @@ provide a sync() method in the 'Passed'
async()
}
-}
8.8 Working with Context Paths
Spring Cloud Contract supports context paths.
Important
The only change needed to fully support context paths is the switch on the
+}
7.8 Working with Context Paths
Spring Cloud Contract supports context paths.
Important
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.
Maven.
@@ -1075,8 +1075,8 @@ socket.
Consider the following contract:
or
}
}
If you do it this way:
All of your requests in the autogenerated tests are sent to the real endpoint with your
context path included (for example, /my-context-path/url).
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 /my-context-path/url).
8.9 Messaging Top-Level Elements
The DSL for messaging looks a little bit different than the one that focuses on HTTP. The
-following sections explain the differences:
The output message can be triggered by calling a method (such as a Scheduler when a was
+that information (for example, in the stubs, you have to call /my-context-path/url).
7.9 Messaging Top-Level Elements
The DSL for messaging looks a little bit different than the one that focuses on HTTP. The
+following sections explain the differences:
The output message can be triggered by calling a method (such as a Scheduler when a was
started and a message was sent), as shown in the following example:
def dsl = Contract.make {
// Human readable description
description 'Some description'
@@ -1101,7 +1101,7 @@ started and a message was sent), as shown in the following example:
In the previous example case, the output message is sent to output if a method called
bookReturnedTriggered is executed. On the message publisher’s side, we generate a
test that calls that method to trigger the message. On the consumer side, you can use
-the some_label to trigger the message.
8.9.2 Output Triggered by a Message
The output message can be triggered by receiving a message, as shown in the following
+the some_label to trigger the message.
7.9.2 Output Triggered by a Message
The output message can be triggered by receiving a message, as shown in the following
example:
def dsl = Contract.make {
received on the input destination. On the message publisher’s side, the engine
generates a test that sends the input message to the defined destination. On the
consumer side, you can either send a message to the input destination or use a label
-(some_label in the example) to trigger the message.
8.9.3 Consumer/Producer
In HTTP, you have a notion of client/stub and `server/test notation. You can also
+(some_label in the example) to trigger the message.
7.9.3 Consumer/Producer
In HTTP, you have a notion of client/stub and `server/test notation. You can also
use those paradigms in messaging. In addition, Spring Cloud Contract Verifier also
provides the consumer and producer methods, as presented in the following example
(note that you can use either $ or value methods to provide consumer and producer
@@ -1152,10 +1152,10 @@ parts):
Contract.make {
bookName: 'foo'
])
}
-}
8.9.4 Common
In the input {} or outputMessage {} section you can call assertThat with the name
+}
7.9.4 Common
In the input {} or outputMessage {} section you can call assertThat with the name
of a method (e.g. assertThatMessageIsOnTheQueue()) that you have defined in the
base class or in a static import. Spring Cloud Pipelines will execute that method
-in the genertaed test.
8.10 Multiple Contracts in One File
You can define multiple contracts in one file. Such a contract might resemble the
+in the genertaed test.
7.10 Multiple Contracts in One File
You can define multiple contracts in one file. Such a contract might resemble the
following example:
import org.springframework.cloud.contract.spec.Contract
[
@@ -1227,4 +1227,4 @@ index of the contract in the list.
The generated stubs is shown in the fol
1_WithList.json
As you can see, the first file got the name parameter from the contract. The second
got the name of the contract file (WithList.groovy) prefixed with the index (in this
case, the contract had an index of 1 in the list of contracts in the file).
Tip
As you can see, it iss much better if you name your contracts because doing so makes
-your tests far more meaningful.
\ No newline at end of file
+your tests far more meaningful.
![[Important]](images/important.png)
![[Note]](images/note.png)
![[Warning]](images/warning.png)
![[Tip]](images/tip.png)