SpringCloud/spring-cloud-contract
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fix readme.

Browse Source
This commit is contained in:
OlgaMaciaszek
2018-10-22 21:31:31 +02:00
parent cf21f18938
commit 53d7827495
2 changed files with 63 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

80
README.adoc
View File

@@ -24,9 +24,6 @@ http://cloud-samples.spring.io/spring-cloud-contract-samples/workshops.html[this
== Spring Cloud Contract Verifier Introduction
TIP: The Accurest project was initially started by Marcin Grzejszczak and Jakub Kubrynski
(http://codearte.io[codearte.io])
Spring Cloud Contract Verifier enables Consumer Driven Contract (CDC) development of
JVM-based applications. It moves TDD to the level of software architecture.
@@ -43,6 +40,14 @@ own integrations.
of the API is compliant with the contract (__server tests__). A full test is generated by
Spring Cloud Contract Verifier.
=== History
Before becoming Spring Cloud Contract, this project was called https://github.com/Codearte/accurest[Accurest].
It was created by https://twitter.com/mgrzejszczak[Marcin Grzejszczak] and https://twitter.com/jkubrynski[Jakub Kubrynski]
from (http://codearte.io[codearte.io].
The `0.1.0` release took place on 26 Jan 2015 and it became stable with `1.0.0` release on 29 Feb 2016.
=== Why a Contract Verifier?
Assume that we have a system consisting of multiple microservices:
@@ -396,10 +401,38 @@ public void validate_shouldMarkClientAsFraud() throws Exception {
----
The preceding example uses Spring's `MockMvc` to run the tests. This is the default test
mode for HTTP contracts. However, JAX-RX client and explicit HTTP invocations can also be
mode for HTTP contracts. However, JAX-RS client and explicit HTTP invocations can also be
used. (To do so, change the `testMode` property of the plugin to `JAX-RS` or `EXPLICIT`,
respectively.)
Since 2.1.0, it is also possible to use `RestAssuredWebTestClient`with Spring's reactive `WebTestClient`
run under the hood. This is particularly recommended while working with Reactive, `Web-Flux`-based applications.
In order to use `WebTestClient` set `testMode` to `WEBTESTCLIENT`.
Here is an example of a test generated in `WEBTESTCLIENT` test mode:
[source,java,indent=0]
----
@Test
public void validate_shouldRejectABeerIfTooYoung() throws Exception {
// given:
WebTestClientRequestSpecification request = given()
.header("Content-Type", "application/json")
.body("{\"age\":10}");
// when:
WebTestClientResponse response = given().spec(request)
.post("/check");
// then:
assertThat(response.statusCode()).isEqualTo(200);
assertThat(response.header("Content-Type")).matches("application/json.*");
// and:
DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
assertThatJson(parsedJson).field("['status']").isEqualTo("NOT_OK");
}
----
Apart from the default JUnit 4, you can instead use JUnit 5 or Spock tests, by setting the plugin
`testFramework` property to either `JUNIT5` or `Spock`.
@@ -1478,15 +1511,17 @@ your test. The following code shows an example:
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@AutoConfigureWireMock(port = 0)
public class WiremockForDocsTests {
// A service that calls out over HTTP
@Autowired private Service service;
@Autowired
private Service service;
// Using the WireMock APIs in the normal way:
@Test
public void contextLoads() throws Exception {
// Stubbing WireMock
stubFor(get(urlEqualTo("/resource"))
.willReturn(aResponse().withHeader("Content-Type", "text/plain").withBody("Hello World!")));
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!");
}
@@ -1564,6 +1599,7 @@ public class WiremockForDocsClassRuleTests {
@ClassRule
public static WireMockClassRule wiremock = new WireMockClassRule(
WireMockSpring.options().dynamicPort());
// A service that calls out over HTTP to localhost:${wiremock.port}
@Autowired
private Service service;
@@ -1572,8 +1608,8 @@ public class WiremockForDocsClassRuleTests {
@Test
public void contextLoads() throws Exception {
// Stubbing WireMock
wiremock.stubFor(get(urlEqualTo("/resource"))
.willReturn(aResponse().withHeader("Content-Type", "text/plain").withBody("Hello World!")));
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!");
}
@@ -1660,6 +1696,7 @@ public class WiremockForDocsMockServerApplicationTests {
assertThat(this.service.go()).isEqualTo("Hello World");
server.verify();
}
}
----
@@ -1685,9 +1722,11 @@ Example:
[source,java,indent=0]
----
@Bean WireMockConfigurationCustomizer optionsCustomizer() {
@Bean
WireMockConfigurationCustomizer optionsCustomizer() {
return new WireMockConfigurationCustomizer() {
@Override public void customize(WireMockConfiguration options) {
@Override
public void customize(WireMockConfiguration options) {
// perform your customization here
}
};
@@ -1698,8 +1737,7 @@ Example:
https://projects.spring.io/spring-restdocs[Spring REST Docs] can be used to generate
documentation (for example in Asciidoctor format) for an HTTP API with Spring MockMvc
or `WebTestClient` or
Rest Assured. At the same time that you generate documentation for your API, you can also
or `WebTestClient` or Rest Assured. At the same time that you generate documentation for your API, you can also
generate WireMock stubs by using Spring Cloud Contract WireMock. To do so, write your
normal REST Docs test cases and use `@AutoConfigureRestDocs` to have stubs be
automatically generated in the REST Docs output directory. The following code shows an
@@ -1866,16 +1904,14 @@ Consider the following test:
[source,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"))
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 >= 20)]")
.andDo(WireMockRestDocs.verify().jsonPath("$[?(@.foo >= 20)]")
.jsonPath("$[?(@.bar in ['baz','bazz','bazzz'])]")
.contentType(MediaType.valueOf("application/json"))
.stub("shouldGrantABeerIfOldEnough"))

10
docs/src/main/asciidoc/verifier_contract.adoc
View File

@@ -21,7 +21,7 @@ The following is a complete example of a Groovy contract definition:
[source,groovy,indent=0]
----
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MockMvcMethodBodyBuilderSpec.groovy[tags=dsl_example,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MethodBodyBuilderSpec.groovy[tags=dsl_example,indent=0]
----
The following is a complete example of a YAML contract definition:
@@ -296,7 +296,7 @@ include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=body,inde
.Groovy DSL
[source,groovy,indent=0]
----
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MockMvcMethodBodyBuilderSpec.groovy[tags=multipartdsl,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MethodBodyBuilderSpec.groovy[tags=multipartdsl,indent=0]
----
.YAML
@@ -449,7 +449,7 @@ the provided regular expression. The following code shows an example:
[source,groovy,indent=0]
----
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MockMvcMethodBodyBuilderSpec.groovy[tags=dsl_one_side_data_generation_example,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MethodBodyBuilderSpec.groovy[tags=dsl_one_side_data_generation_example,indent=0]
----
In the preceding example, the opposite side of the communication has the respective data
@@ -467,7 +467,7 @@ In your contract, you can use it as shown in the following example:
[source,groovy,indent=0]
----
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MockMvcMethodBodyBuilderSpec.groovy[tags=contract_with_regex,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MethodBodyBuilderSpec.groovy[tags=contract_with_regex,indent=0]
----
==== Passing Optional Parameters
@@ -612,7 +612,7 @@ Consider the following contract:
.Groovy DSL
[source,groovy,indent=0]
----
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MockMvcMethodBodyBuilderSpec.groovy[tags=template_contract,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MethodBodyBuilderSpec.groovy[tags=template_contract,indent=0]
----
.YAML