Polish documentation
This commit is contained in:
jkubrynski
945
README.adoc
945
README.adoc
File diff suppressed because it is too large
Load Diff
@@ -9,16 +9,16 @@ This project provides support for Consumer Driven Contracts and service schemas
|
||||
range of options for writing tests, publishing them as assets, asserting that a contract is kept by producers
|
||||
and consumers, for HTTP and message-based interactions.
|
||||
|
||||
=== Spring Cloud Contract WireMock
|
||||
|
||||
include::spring-cloud-wiremock.adoc[]
|
||||
|
||||
=== Spring Cloud Contract Verifier
|
||||
|
||||
include::verifier/introduction.adoc[]
|
||||
|
||||
include::verifier/links.adoc[]
|
||||
|
||||
=== Spring Cloud Contract WireMock
|
||||
|
||||
include::spring-cloud-wiremock.adoc[]
|
||||
|
||||
== Documentation
|
||||
|
||||
You can read more about Spring Cloud Contract Verifier by reading the {documentation_url}[docs]
|
||||
|
||||
@@ -16,10 +16,10 @@ This project provides support for Consumer Driven Contracts and service schemas
|
||||
range of options for writing tests, publishing them as assets, asserting that a contract is kept by producers
|
||||
and consumers, for HTTP and message-based interactions.
|
||||
|
||||
== Spring Cloud Contract WireMock
|
||||
|
||||
include::spring-cloud-wiremock.adoc[]
|
||||
|
||||
== Spring Cloud Contract Verifier
|
||||
|
||||
include::verifier/spring-cloud-contract-verifier.adoc[]
|
||||
|
||||
== Spring Cloud Contract WireMock
|
||||
|
||||
include::spring-cloud-wiremock.adoc[]
|
||||
|
||||
@@ -2,8 +2,6 @@
|
||||
|
||||
=== Introduction
|
||||
|
||||
IMPORTANT: http://codearte.github.io/accurest[The documentation to the deprecated Accurest project in version 1.1.0 is available here.]
|
||||
|
||||
TIP: The Accurest project was initially started by Marcin Grzejszczak and Jakub Kubrynski (http://codearte.io[codearte.io])
|
||||
|
||||
Just to make long story short - Spring Cloud Contract Verifier is a tool that enables Consumer Driven Contract (CDC) development of JVM-based applications. It is shipped
|
||||
@@ -17,12 +15,6 @@ Full test is generated by Spring Cloud Contract Verifier.
|
||||
|
||||
Spring Cloud Contract Verifier moves TDD to the level of software architecture.
|
||||
|
||||
==== Spring Cloud Contract video
|
||||
|
||||
You can check out the video from the Warsaw JUG about Spring Cloud Contract:
|
||||
|
||||
video::sAAklvxmPmk[youtube,start=538,width=640,height=480]
|
||||
|
||||
==== Why?
|
||||
|
||||
Let us assume that we have a system comprising of multiple microservices:
|
||||
@@ -66,11 +58,7 @@ Disadvantages:
|
||||
- you can go to production with passing tests and failing production
|
||||
|
||||
To solve the aforementioned issues Spring Cloud Contract Verifier with Stub Runner were created. Their main idea is to give you very fast feedback, without the need
|
||||
to set up the whole world of microservices.
|
||||
|
||||
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/1.0.x/docs/src/main/asciidoc/images/Stubs1.png[Stubbed Services]
|
||||
|
||||
If you work on stubs then the only applications you need are those that your application is using directly.
|
||||
to set up the whole world of microservices. If you work on stubs then the only applications you need are those that your application is using directly.
|
||||
|
||||
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/1.0.x/docs/src/main/asciidoc/images/Stubs2.png[Stubbed Services]
|
||||
|
||||
@@ -91,16 +79,42 @@ Let's assume that we have a business use case of fraud check. If a user can be a
|
||||
we would assume that you would create 2 contracts. One for the positive and one for the negative fraud case.
|
||||
Contract tests are used to test contracts between applications and not to simulate full behaviour.
|
||||
|
||||
==== Client Side
|
||||
==== How
|
||||
|
||||
During the tests you want to have a WireMock instance / Messaging route up and running that simulates the service Y.
|
||||
You would like to feed that instance with a proper stub definition. That stub definition would need
|
||||
to be valid and should also be reusable on the server side.
|
||||
===== Define the contract
|
||||
|
||||
__Summing it up:__ On this side, in the stub definition, you can use patterns for request stubbing and you need exact
|
||||
values for responses.
|
||||
As consumers we need to define what exactly we want to achieve. We need to formulate our expectations. That's why we write the following contract.
|
||||
|
||||
==== Server Side
|
||||
Let’s assume that we’d like to send the request containing the id of the client and the amount he wants to borrow from us. We’d like to send it to the /fraudcheck url via the PUT method.
|
||||
|
||||
[source,groovy,indent=0]
|
||||
----
|
||||
include::{introduction_url}/samples/standalone/dsl/http-server/src/test/resources/contracts/fraud/shouldMarkClientAsFraud.groovy[]
|
||||
----
|
||||
|
||||
===== Client Side
|
||||
|
||||
Spring Cloud Contract will generate stubs, which you can use during client side testing.
|
||||
You will have a WireMock instance / Messaging route up and running that simulates the service Y.
|
||||
You would like to feed that instance with a proper stub definition.
|
||||
|
||||
At some point in time you need to send a request to the Fraud Detection service.
|
||||
|
||||
[source,groovy,indent=0]
|
||||
----
|
||||
include::{introduction_url}/samples/standalone/dsl/http-client/src/main/java/com/example/loan/LoanApplicationService.java[tags=client_call_server,indent=0]
|
||||
----
|
||||
|
||||
Annotate your test class with `@AutoConfigureStubRunner`. In the annotation provide the group id and artifact id for the Stub Runner to download stubs of your collaborators.
|
||||
|
||||
[source,groovy,indent=0]
|
||||
----
|
||||
include::{introduction_url}/samples/standalone/dsl/http-client/src/test/java/com/example/loan/LoanApplicationServiceTests.java[tags=autoconfigure_stubrunner,indent=0]
|
||||
----
|
||||
|
||||
After that, during the tests Spring Cloud Contract will automatically find the stubs (simulating the real service) in Maven repository and expose them on configured (or random) port.
|
||||
|
||||
===== Server Side
|
||||
|
||||
Being a service Y since you are developing your stub, you need to be sure that it's actually resembling your
|
||||
concrete implementation. You can't have a situation where your stub acts in one way and your application on
|
||||
@@ -109,8 +123,30 @@ production behaves in a different way.
|
||||
That's why from the provided stub acceptance tests will be generated that will ensure
|
||||
that your application behaves in the same way as you define in your stub.
|
||||
|
||||
__Summing it up:__ On this side, in the stub definition, you need exact values as request and can use patterns/methods
|
||||
for response verification.
|
||||
The autogenerated test would look like this:
|
||||
|
||||
[source,java,indent=0]
|
||||
----
|
||||
@Test
|
||||
public void validate_shouldMarkClientAsFraud() throws Exception {
|
||||
// given:
|
||||
MockMvcRequestSpecification request = given()
|
||||
.header("Content-Type", "application/vnd.fraud.v1+json")
|
||||
.body("{\"clientPesel\":\"1234567890\",\"loanAmount\":99999}");
|
||||
|
||||
// when:
|
||||
ResponseOptions response = given().spec(request)
|
||||
.put("/fraudcheck");
|
||||
|
||||
// then:
|
||||
assertThat(response.statusCode()).isEqualTo(200);
|
||||
assertThat(response.header("Content-Type")).matches("application/vnd.fraud.v1.json.*");
|
||||
// and:
|
||||
DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
|
||||
assertThatJson(parsedJson).field("fraudCheckStatus").matches("[A-Z]{5}");
|
||||
assertThatJson(parsedJson).field("rejectionReason").isEqualTo("Amount too high");
|
||||
}
|
||||
----
|
||||
|
||||
==== Step by step guide to CDC
|
||||
|
||||
|
||||
@@ -10,3 +10,4 @@ Here you can find interesting links related to Spring Cloud Contract Verifier:
|
||||
- https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract.html/#stub-runner-for-messaging[Spring Cloud Contract Stub Runner Messaging Documentation]
|
||||
- https://gitter.im/spring-cloud/spring-cloud-contract[Spring Cloud Contract Gitter]
|
||||
- https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract-maven-plugin/[Spring Cloud Contract Maven Plugin]
|
||||
- https://www.youtube.com/watch?v=sAAklvxmPmk[Spring Cloud Contract WJUG Presentation by Marcin Grzejszczak]
|
||||
|
||||
@@ -25,15 +25,6 @@ org.springframework.cloud.contract.spec.Contract.make {
|
||||
}
|
||||
|
||||
/*
|
||||
Since we don't want to force on the user to hardcode values of fields that are dynamic
|
||||
(timestamps, database ids etc.), one can parametrize those entries. If you wrap your field's
|
||||
value in a `$(...)` or `value(...)` and provide a dynamic value of a field then
|
||||
the concrete value will be generated for you. If you want to be really explicit about
|
||||
which side gets which value you can do that by using the `value(consumer(...), producer(...))` notation.
|
||||
That way what's present in the `consumer` section will end up in the produced stub. What's
|
||||
there in the `producer` will end up in the autogenerated test. If you provide only the
|
||||
regular expression side without the concrete value then Spring Cloud Contract will generate one for you.
|
||||
|
||||
From the Consumer perspective, when shooting a request in the integration test:
|
||||
|
||||
(1) - If the consumer sends a request
|
||||
|
||||
Reference in New Issue
Block a user