From 53d7827495d6cc728d32fad1b04d1135b9b01d8e Mon Sep 17 00:00:00 2001 From: OlgaMaciaszek Date: Mon, 22 Oct 2018 21:31:31 +0200 Subject: [PATCH] Fix readme. --- README.adoc | 80 ++++++++++++++----- docs/src/main/asciidoc/verifier_contract.adoc | 10 +-- 2 files changed, 63 insertions(+), 27 deletions(-) diff --git a/README.adoc b/README.adoc index ed626744c5..67ffa6352c 100644 --- a/README.adoc +++ b/README.adoc @@ -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")) diff --git a/docs/src/main/asciidoc/verifier_contract.adoc b/docs/src/main/asciidoc/verifier_contract.adoc index cd2ddf4068..5b277afbb2 100644 --- a/docs/src/main/asciidoc/verifier_contract.adoc +++ b/docs/src/main/asciidoc/verifier_contract.adoc @@ -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