From cf2a012dbc772a3bf98aaa4ad375a7380105f1ef Mon Sep 17 00:00:00 2001 From: Marcin Grzejszczak Date: Mon, 11 Sep 2023 15:18:28 +0200 Subject: [PATCH] Split files --- .../pages/_project-features-contract.adoc | 2026 ----------------- .../common-top-elements.adoc | 305 +++ .../_project-features-contract/dsl-async.adoc | 134 ++ .../dsl-dynamic-properties.adoc | 797 +++++++ .../dsl-http-top-level-elements.adoc | 45 + .../dsl-multiple.adoc | 134 ++ .../dsl-request.adoc | 271 +++ .../dsl-response.adoc | 41 + .../_project-features-contract/dsl-xml.adoc | 121 + .../_project-features-contract/groovy.adoc | 17 + .../_project-features-contract/java.adoc | 33 + .../_project-features-contract/kotlin.adoc | 73 + .../limitations.adoc | 12 + .../stateful-contracts.adoc | 38 + .../pages/_project-features-contract/yml.adoc | 5 + .../ROOT/pages/_project-features-flows.adoc | 1060 --------- .../context-paths.adoc | 62 + .../_project-features-flows/custom-mode.adoc | 104 + .../feature-webflux-explicit.adoc | 46 + .../feature-webflux.adoc | 53 + .../_project-features-flows/graphql.adoc | 185 ++ .../pages/_project-features-flows/grpc.adoc | 277 +++ .../pages/_project-features-flows/jax-rs.adoc | 26 + .../_project-features-flows/rest-docs.adoc | 307 +++ .../pages/_project-features-stubrunner.adoc | 1078 --------- .../stub-runner-boot.adoc | 131 ++ .../stub-runner-cloud.adoc | 63 + .../stub-runner-common.adoc | 60 + .../stub-runner-core.adoc | 304 +++ .../stub-runner-fail-on-no-stubs.adoc | 39 + ...stub-runner-generate-stubs-at-runtime.adoc | 43 + .../stub-runner-junit.adoc | 167 ++ .../stub-runner-publishing-stubs-as-jars.adoc | 32 + .../stub-runner-snapshot-versions.adoc | 20 + .../stub-runner-stubs-per-consumer.adoc | 98 + .../stub-runner-stubs-protocol.adoc | 121 + docs/modules/ROOT/pages/getting-started.adoc | 1411 ------------ .../ROOT/pages/getting-started/cdc.adoc | 588 +++++ .../getting-started/first-application.adoc | 491 ++++ .../introducing-spring-cloud-contract.adoc | 126 + .../getting-started/three-second-tour.adoc | 176 ++ .../pages/getting-started/whats-next.adoc | 30 + docs/modules/ROOT/pages/howto.adoc | 1044 --------- .../pages/howto/contract-dsl-rest-docs.adoc | 40 + .../how-to-common-repo-with-contracts.adoc | 310 +++ .../pages/howto/how-to-debug-wiremock.adoc | 17 + .../ROOT/pages/howto/how-to-debug.adoc | 18 + .../howto/how-to-do-stubs-versioning.adoc | 98 + .../howto/how-to-generate-pact-from-scc.adoc | 67 + .../how-to-generate-stubs-at-runtime.adoc | 5 + .../how-to-mark-contract-in-progress.adoc | 6 + .../how-to-not-write-contracts-in-groovy.adoc | 7 + .../howto/how-to-provide-dynamic-values.adoc | 106 + .../how-to-reference-text-from-file.adoc | 7 + .../howto/how-to-see-registered-stubs.adoc | 7 + .../howto/how-to-use-git-as-storage.adoc | 279 +++ .../how-to-use-stubs-from-a-location.adoc | 5 + .../how-to-use-the-failonnostubs-feature.adoc | 7 + .../howto/how-to-work-with-transitivie.adoc | 49 + .../howto/why-spring-cloud-contract.adoc | 16 + 60 files changed, 6619 insertions(+), 6619 deletions(-) create mode 100644 docs/modules/ROOT/pages/_project-features-contract/common-top-elements.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-contract/dsl-async.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-contract/dsl-dynamic-properties.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-contract/dsl-http-top-level-elements.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-contract/dsl-multiple.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-contract/dsl-request.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-contract/dsl-response.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-contract/dsl-xml.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-contract/groovy.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-contract/java.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-contract/kotlin.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-contract/limitations.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-contract/stateful-contracts.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-contract/yml.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-flows/context-paths.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-flows/custom-mode.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-flows/feature-webflux-explicit.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-flows/feature-webflux.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-flows/graphql.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-flows/grpc.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-flows/jax-rs.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-flows/rest-docs.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-boot.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-cloud.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-common.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-core.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-fail-on-no-stubs.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-generate-stubs-at-runtime.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-junit.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-publishing-stubs-as-jars.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-snapshot-versions.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-stubs-per-consumer.adoc create mode 100644 docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-stubs-protocol.adoc create mode 100644 docs/modules/ROOT/pages/getting-started/cdc.adoc create mode 100644 docs/modules/ROOT/pages/getting-started/first-application.adoc create mode 100644 docs/modules/ROOT/pages/getting-started/introducing-spring-cloud-contract.adoc create mode 100644 docs/modules/ROOT/pages/getting-started/three-second-tour.adoc create mode 100644 docs/modules/ROOT/pages/getting-started/whats-next.adoc create mode 100644 docs/modules/ROOT/pages/howto/contract-dsl-rest-docs.adoc create mode 100644 docs/modules/ROOT/pages/howto/how-to-common-repo-with-contracts.adoc create mode 100644 docs/modules/ROOT/pages/howto/how-to-debug-wiremock.adoc create mode 100644 docs/modules/ROOT/pages/howto/how-to-debug.adoc create mode 100644 docs/modules/ROOT/pages/howto/how-to-do-stubs-versioning.adoc create mode 100644 docs/modules/ROOT/pages/howto/how-to-generate-pact-from-scc.adoc create mode 100644 docs/modules/ROOT/pages/howto/how-to-generate-stubs-at-runtime.adoc create mode 100644 docs/modules/ROOT/pages/howto/how-to-mark-contract-in-progress.adoc create mode 100644 docs/modules/ROOT/pages/howto/how-to-not-write-contracts-in-groovy.adoc create mode 100644 docs/modules/ROOT/pages/howto/how-to-provide-dynamic-values.adoc create mode 100644 docs/modules/ROOT/pages/howto/how-to-reference-text-from-file.adoc create mode 100644 docs/modules/ROOT/pages/howto/how-to-see-registered-stubs.adoc create mode 100644 docs/modules/ROOT/pages/howto/how-to-use-git-as-storage.adoc create mode 100644 docs/modules/ROOT/pages/howto/how-to-use-stubs-from-a-location.adoc create mode 100644 docs/modules/ROOT/pages/howto/how-to-use-the-failonnostubs-feature.adoc create mode 100644 docs/modules/ROOT/pages/howto/how-to-work-with-transitivie.adoc create mode 100644 docs/modules/ROOT/pages/howto/why-spring-cloud-contract.adoc diff --git a/docs/modules/ROOT/pages/_project-features-contract.adoc b/docs/modules/ROOT/pages/_project-features-contract.adoc index 87af992c6a..2a94efd684 100644 --- a/docs/modules/ROOT/pages/_project-features-contract.adoc +++ b/docs/modules/ROOT/pages/_project-features-contract.adoc @@ -49,2029 +49,3 @@ mvn org.springframework.cloud:spring-cloud-contract-maven-plugin:convert ---- ==== -[[contract-groovy]] -== Contract DSL in Groovy - -If you are not familiar with Groovy, do not worry. You can use Java syntax in the -Groovy DSL files as well. - -If you decide to write the contract in Groovy, do not be alarmed if you have not used Groovy -before. Knowledge of the language is not really needed, as the Contract DSL uses only a -tiny subset of it (only literals, method calls, and closures). Also, the DSL is statically -typed, to make it programmer-readable without any knowledge of the DSL itself. - -IMPORTANT: Remember that, inside the Groovy 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 -`Contract.make { ... }`. - -[[contract-java]] -== Contract DSL in Java - -To write a contract definition in Java, you need to create a class that implements either the `Supplier` interface (for a single contract) or `Supplier>` (for multiple contracts). - -You can also write the contract definitions under `src/test/java` (for example, `src/test/java/contracts`) so that you do not have to modify the classpath of your project. In this case, you have to provide a new location of contract definitions to your Spring Cloud Contract plugin. - -The following example (in both Maven and Gradle) has the contract definitions under `src/test/java`: - -==== -[source,xml,indent=0,subs="verbatim,attributes",role="primary"] -.Maven ----- - - org.springframework.cloud - spring-cloud-contract-maven-plugin - ${spring-cloud-contract.version} - true - - src/test/java/contracts - - ----- - -[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] -.Gradle ----- -contracts { - contractsDslDir = new File(project.rootDir, "src/test/java/contracts") -} ----- -==== - -[[contract-kotlin]] -== Contract DSL in Kotlin - -To get started with writing contracts in Kotlin, you need to start with a (newly created) Kotlin Script file (`.kts`). -As with the Java DSL, you can put your contracts in any directory of your choice. -By default, the Maven plugin will look at the `src/test/resources/contracts` directory and Gradle plugin will -look at the `src/contractTest/resources/contracts` directory. - -NOTE: Since 3.0.0, the Gradle plugin will also look at the legacy -directory `src/test/resources/contracts` for migration purposes. When contracts are found in this directory, a warning -will be logged during your build. - -You need to explicitly pass the `spring-cloud-contract-spec-kotlin` dependency to your project plugin setup. -The following example (in both Maven and Gradle) shows how to do so: - -==== -[source,xml,indent=0,subs="verbatim,attributes",role="primary"] -.Maven ----- - - org.springframework.cloud - spring-cloud-contract-maven-plugin - ${spring-cloud-contract.version} - true - - - - - - org.springframework.cloud - spring-cloud-contract-spec-kotlin - ${spring-cloud-contract.version} - - - - - - - - org.springframework.cloud - spring-cloud-contract-spec-kotlin - test - - ----- - -[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] -.Gradle ----- -buildscript { - repositories { - // ... - } - dependencies { - classpath "org.springframework.cloud:spring-cloud-contract-gradle-plugin:${scContractVersion}" - } -} - -dependencies { - // ... - - // Remember to add this for the DSL support in the IDE and on the consumer side - testImplementation "org.springframework.cloud:spring-cloud-contract-spec-kotlin" - // Kotlin versions are very particular down to the patch version. The needs to be the same as you have imported for your project. - testImplementation "org.jetbrains.kotlin:kotlin-scripting-compiler-embeddable:" -} ----- -==== - -IMPORTANT: Remember that, inside the Kotlin Script file, you have to provide the fully qualified name to the `ContractDSL` class. -Generally you would use its contract function as follows: `org.springframework.cloud.contract.spec.ContractDsl.contract { ... }`. -You can also provide an import to the `contract` function (`import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract`) and then call `contract { ... }`. - -[[contract-yml]] -== Contract DSL in YAML - -To see a schema of a YAML contract, visit the {docs-url}/reference/html/yml-schema.html[YML Schema] page. - -[[contract-limitations]] -== Limitations - -WARNING: The support for verifying the size of JSON arrays is experimental. If you want -to turn it on, 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 set 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 Groovy DSL and the `value(consumer(...), producer(...))` notation in `GString`. That -is why you should use the Groovy Map notation. - -[[contract-common-top-elements]] -== Common Top-Level Elements - -The following sections describe the most common top-level elements: - -* <> -* <> -* <> -* <> -* <> -* <> - -[[contract-dsl-description]] -=== Description - -You can add a `description` to your contract. The description is arbitrary text. The -following code shows an example: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{contract_spec_tests_path}/src/test/groovy/org/springframework/cloud/contract/spec/internal/ContractSpec.groovy[tags=description,indent=0] ----- - -[source,yaml,indent=0,role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract_rest.yml[indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[tags=description,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[tags=description,indent=0] ----- -==== - -[[contract-dsl-name]] -=== Name - -You can provide a name for your contract. Assume that you provide 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. - -The following example shows how to add a name to a contract: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{contract_spec_tests_path}/src/test/groovy/org/springframework/cloud/contract/spec/internal/ContractSpec.groovy[tags=name,indent=0] ----- - -[source,yaml,indent=0,role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=name,indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[tags=name,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[tags=name,indent=0] ----- -==== - -[[contract-dsl-ignoring-contracts]] -=== Ignoring Contracts - -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 -example shows how to do so: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{contract_spec_tests_path}/src/test/groovy/org/springframework/cloud/contract/spec/internal/ContractSpec.groovy[tags=ignored,indent=0] ----- - -[source,yaml,indent=0,role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=ignored,indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[tags=ignored,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[tags=ignored,indent=0] ----- -==== - -[[contract-dsl-in-progress]] -=== Contracts in Progress - -A contract in progress does not generate tests on the producer side but does allow generation of stubs. - -IMPORTANT: Use this feature with caution as it may lead to false positives, because you generate stubs for your consumers to use without actually having the implementation in place. - -If you want to set a contract in progress, the following -example shows how to do so: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{contract_spec_tests_path}/src/test/groovy/org/springframework/cloud/contract/spec/internal/ContractSpec.groovy[tags=in_progress,indent=0] ----- - -[source,yaml,indent=0,role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=in_progress,indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[tags=in_progress,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[tags=in_progress,indent=0] ----- -==== - -You can set the value of the `failOnInProgress` Spring Cloud Contract plugin property to ensure that your build breaks when at least one contract in progress remains in your sources. - -[[contract-dsl-passing-values-from-files]] -=== Passing Values from Files - -Starting with version `1.2.0`, you can pass values from files. Assume that you have the -following resources in your project: - -[source,bash,indent=0] ----- -└── src -    └── test -       └── resources -          └── contracts -    ├── readFromFile.groovy -    ├── request.json -    └── response.json ----- - -Further assume that your contract is as follows: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/resources/classpath/readFromFile.groovy[indent=0] ----- - -[source,yaml,indent=0,role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract_from_file.yml[indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_rest_from_file.java[tags=class,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{verifier_core_path}/src/test/resources/kotlin/readFromFile.kts[tags=class,indent=0] ----- -==== - -Further assume that the JSON files are as follows: - -==== -[source,json,indent=0,subs="verbatim,attributes",role="primary"] -.request.json ----- -include::{verifier_core_path}/src/test/resources/classpath/request.json[indent=0] ----- - -[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] -.response.json ----- -include::{verifier_core_path}/src/test/resources/classpath/response.json[indent=0] ----- -==== - -When test or stub generation takes place, the contents of the `request.json` and `response.json` files are passed to the body -of a request or a response. The name of the file needs to be a file in a location -relative to the folder in which the contract resides. - -If you need to pass the contents of a file in binary form, -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: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/resources/body_builder/worksWithPdf.groovy[indent=0] ----- - -[source,yaml,indent=0,role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract_pdf.yml[indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_rest_from_pdf.java[tags=class,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{contract_kotlin_spec_path}/src/test/resources/contracts/shouldWorkWithBinaryPayload.kts[tags=class,indent=0] ----- -==== - -IMPORTANT: You should use this approach whenever you want to work with binary payloads, -both for HTTP and messaging. - -[[contract-dsl-metadata]] -=== Metadata - -You can add `metadata` to your contract. Via the metadata you can pass in configuration to extensions. Below you can find -an example of using the `wiremock` key. Its value is a map whose key is `stubMapping` and value being WireMock's `StubMapping` object. Spring Cloud Contract is able to -patch parts of your generated stub mapping with your custom code. You may want to do that in order to add webhooks, custom -delays or integrate with third party WireMock extensions. - -==== -[source,groovy,indent=0,role="primary"] -.groovy ----- -include::{standalone_samples_path}/http-server/src/test/resources/contracts/fraud/shouldReturnFraudStats.groovy[tags=metadata,indent=0] ----- - -[source,yaml,indent=0,role="secondary"] -.yml ----- -include::{standalone_samples_path}/http-server/src/test/resources/contracts/yml/fraud/shouldReturnFraudStats.yml[tags=metadata,indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[tags=metadata,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.kotlin ----- -include::{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[tags=metadata,indent=0] ----- -==== - -In the following sections you can find examples of the supported metadata entries. - -//// -include::{project-root}/docs/target/metadata.adoc[indent=0] -//// - -[[features-http]] -= Contracts for HTTP - -Spring Cloud Contract lets you verify applications that use REST or HTTP as a -means of communication. Spring Cloud Contract verifies that, for a request that matches the -criteria from the `request` part of the contract, the server provides a response that is in -keeping with the `response` part of the contract. Subsequently, the contracts are used to -generate WireMock stubs that, for any request matching the provided criteria, provide a -suitable response. - -[[contract-dsl-http-top-level-elements]] -== HTTP Top-Level Elements - -You can call the following methods in the top-level closure of a contract definition: - -* `request`: Mandatory -* `response` : Mandatory -* `priority`: Optional - -The following example shows how to define an HTTP request contract: - -==== -[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=http_dsl,indent=0] ----- - -[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=priority,indent=0] -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=request,indent=0] -... -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=response,indent=0] -... ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=http_dsl,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=http_dsl,indent=0] ----- -==== - -IMPORTANT: If you want to make your contract have a higher priority, -you need to pass a lower number to the `priority` tag or method. For example, a `priority` with -a value of `5` has higher priority than a `priority` with a value of `10`. - -[[contract-dsl-request]] -== HTTP Request - -The HTTP protocol requires only the method and the URL to be specified in a request. The -same information is mandatory in request definition of the contract. - -The following example shows a contract for a request: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=request,indent=0] ----- - -[source,yaml,indent=0,role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=request_obligatory,indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=request,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=request,indent=0] ----- -==== - -You can specify an absolute rather than a relative `url`, but using `urlPath` is -the recommended way, as doing so makes the tests be host-independent. - -The following example uses `url`: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=url,indent=0] ----- - -[source,yaml,indent=0,role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract_rest_with_path.yml[tags=url_path,indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=url,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=url,indent=0] ----- -==== - -`request` may contain query parameters, as the following example (which uses `urlPath`) shows: - -==== -[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=urlpath,indent=0] ----- - -[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=request,indent=0] -... -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=query_params,indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=urlpath,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=urlpath,indent=0] ----- -==== - -`request` can contain additional request headers, as the following example shows: - -==== -[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=headers,indent=0] ----- - -[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=request,indent=0] -... -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=headers,indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=headers,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=headers,indent=0] ----- -==== - -`request` may contain additional request cookies, as the following example shows: - -==== -[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=cookies,indent=0] ----- - -[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=request,indent=0] -... -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=cookies,indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=cookies,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=cookies,indent=0] ----- -==== - -`request` may contain a request body, as the following example shows: - -==== -[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=body,indent=0] ----- - -[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=request,indent=0] -... -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=body,indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=body,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=body,indent=0] ----- -==== - -`request` can contain multipart elements. To include multipart elements, use the -`multipart` method/section, as the following examples show: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/SpringTestMethodBodyBuildersSpec.groovy[tags=multipartdsl,indent=0] ----- - -[source,yaml,indent=0,role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract_multipart.yml[indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_multipart.java[tags=class,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{verifier_core_path}/src/test/resources/kotlin/multipart.kts[tags=class,indent=0] ----- -==== - -In the preceding example, we defined parameters in either of two ways: - -.Coded DSL -* Directly, by using the map notation, where the value can be a dynamic property (such as -`formParameter: $(consumer(...), producer(...))`). -* By using the `named(...)` method that lets you set a named parameter. A named parameter -can set a `name` and `content`. You can call it either by using a method with two arguments, -such as `named("fileName", "fileContent")`, or by using a map notation, such as -`named(name: "fileName", content: "fileContent")`. - -.YAML -* The multipart parameters are set in the `multipart.params` section. -* The named parameters (the `fileName` and `fileContent` for a given parameter name) -can be set in the `multipart.named` section. That section contains -the `paramName` (the name of the parameter), `fileName` (the name of the file), -`fileContent` (the content of the file) fields. -* The dynamic bits can be set in the `matchers.multipart` section. -** For parameters, use the `params` section, which can accept -`regex` or a `predefined` regular expression. -** For named parameters, use the `named` section where you first -define the parameter name with `paramName`. Then you can pass the -parametrization of either `fileName` or `fileContent` in a -`regex` or in a `predefined` regular expression. - -IMPORTANT: For the `named(...)` section you always have to add a pair of -`value(producer(...), consumer(...))` calls. Just setting DSL properties such -as just `value(producer(...))` or just `file(...)` will not work. -Check this https://github.com/spring-cloud/spring-cloud-contract/issues/1886[issue] for more information. - -From the contract in the preceding example, the generated test and stub look as follows: - -==== -[source,java,indent=0,subs="verbatim,attributes",role="primary"] -.Test ----- -// given: - MockMvcRequestSpecification request = given() - .header("Content-Type", "multipart/form-data;boundary=AaB03x") - .param("formParameter", "\"formParameterValue\"") - .param("someBooleanParameter", "true") - .multiPart("file", "filename.csv", "file content".getBytes()); - - // when: - ResponseOptions response = given().spec(request) - .put("/multipart"); - - // then: - assertThat(response.statusCode()).isEqualTo(200); ----- - -[source,json,indent=0,subs="verbatim,attributes",role="secondary"] -.Stub ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/dsl/wiremock/WireMockGroovyDslSpec.groovy[tags=multipartwiremock,indent=0] ----- -==== - -[[contract-dsl-response]] -== HTTP Response - -The response must contain an HTTP status code and may contain other information. The -following code shows an example: - -==== -[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=response,indent=0] ----- - -[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=response,indent=0] -... -include::{verifier_core_path}/src/test/resources/yml/contract.yml[tags=response_obligatory,indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=response,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=response,indent=0] ----- -==== - -Besides status, the response may contain headers, cookies, and a body, which are -specified the same way as in the request (see <>). - -TIP: In the Groovy DSL, you can reference the `org.springframework.cloud.contract.spec.internal.HttpStatus` -methods to provide a meaningful status instead of a digit. For example, you can call -`OK()` for a status `200` or `BAD_REQUEST()` for `400`. - -[[contract-dsl-dynamic-properties]] -== 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. - -For the Groovy DSL, you can provide the dynamic parts in your contracts -in two ways: pass them directly in the body or set them in a separate section called -`bodyMatchers`. - -NOTE: Before 2.0.0, these were set by using `testMatchers` and `stubMatchers`. -See the https://github.com/spring-cloud/spring-cloud-contract/wiki/Spring-Cloud-Contract-2.0-Migration-Guide[migration guide] for more information. - -For YAML, you can use only the `matchers` section. - -IMPORTANT: Entries inside the `matchers` must reference existing elements of the payload. For more information, see https://github.com/spring-cloud/spring-cloud-contract/issues/722[this issue]. - -[[contract-dsl-dynamic-properties-in-body]] -=== Dynamic Properties inside the Body - -IMPORTANT: This section is valid only for the Coded DSL (Groovy, Java, and so on). See the -<> section for YAML examples of a similar feature. - -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: - -==== -[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] -.value ----- -value(consumer(...), producer(...)) -value(c(...), p(...)) -value(stub(...), test(...)) -value(client(...), server(...)) ----- - -[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] -.$ ----- -$(consumer(...), producer(...)) -$(c(...), p(...)) -$(stub(...), test(...)) -$(client(...), server(...)) ----- -==== - -Both approaches work equally well. The `stub` and `client` methods are aliases over the `consumer` -method. Subsequent sections take a closer look at what you can do with those values. - -[[contract-dsl-regex]] -=== Regular Expressions - -IMPORTANT: This section is valid only for the Groovy DSL. See the -<> section for YAML examples of a similar feature. - -You can use regular expressions to write your requests in the 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 tests and your server-side tests. - -Make sure that regex matches a whole region of a sequence, as, internally, -https://docs.oracle.com/javase/8/docs/api/java/util/regex/Matcher.html#matches[`Pattern.matches()`] -is called. For instance, `abc` does not match `aabc`, but `.abc` does. -There are several additional <> as well. - -The following example shows how to use regular expressions to write a request: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=regex,indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=regex,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=regex,indent=0] ----- -==== - -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 for Groovy: - -[source,groovy,indent=0] ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/SpringTestMethodBodyBuildersSpec.groovy[tags=dsl_one_side_data_generation_example,indent=0] ----- - -In the preceding example, the opposite side of the communication has the respective data -generated for request and response. - -Spring Cloud Contract comes with a series of predefined regular expressions that you can -use in your contracts, as the following example shows: - -[source,java,indent=0] ----- -include::{contract_spec_path}/src/main/java/org/springframework/cloud/contract/spec/internal/RegexPatterns.java[tags=regexps,indent=0] ----- - -In your contract, you can use it as follows (example for the Groovy DSL): - -[source,groovy,indent=0] ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/SpringTestMethodBodyBuildersSpec.groovy[tags=contract_with_regex,indent=0] ----- - -To make matters even simpler, you can use a set of predefined objects that automatically -assume that you want a regular expression to be passed. -All of those methods start with the `any` prefix, as follows: - -[source,java,indent=0] ----- -include::{contract_spec_path}/src/main/java/org/springframework/cloud/contract/spec/internal/RegexCreatingProperty.java[tags=regex_creating_props,indent=0] ----- - -The following example shows how you can reference those methods: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=regex_creating_props,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=regex_creating_props,indent=0] ----- -==== - -[[contract-dsl-regex-limitations]] -==== Limitations - -CAUTION: Due to certain limitations of the `Xeger` library that generates a string out of -a regex, do not use the `$` and `^` signs in your regex if you rely on automatic -generation. See https://github.com/spring-cloud/spring-cloud-contract/issues/899[Issue 899]. - -CAUTION: Do not use a `LocalDate` instance as a value for `$` (for example, `$(consumer(LocalDate.now()))`). -It causes a `java.lang.StackOverflowError`. Use `$(consumer(LocalDate.now().toString()))` instead. -See https://github.com/spring-cloud/spring-cloud-contract/issues/900[Issue 900]. - -[[contract-dsl-optional-params]] -=== Passing Optional Parameters - -IMPORTANT: This section is valid only for Groovy DSL. See the -<> section for YAML examples of a similar feature. - -You can provide optional parameters in your contract. However, you can provide -optional parameters only for the following: - -* The STUB side of the Request -* The TEST side of the Response - -The following example shows how to provide optional parameters: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=optionals,indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=optionals,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=optionals,indent=0] ----- -==== - -By wrapping a part of the body with the `optional()` method, you create a regular -expression that must be present 0 or more times. - -If you use Spock, the following test would be generated from the previous example: - -==== -[source,groovy,indent=0] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=optionals_test,indent=0] ----- -==== - -The following stub would also be generated: - -[source,groovy,indent=0] ----- -include::{plugins_path}/spring-cloud-contract-converters/src/test/groovy/org/springframework/cloud/contract/verifier/wiremock/DslToWireMockClientConverterSpec.groovy[tags=wiremock,indent=0] ----- - -[[contract-dsl-custom-methods]] -=== Calling Custom Methods on the Server Side - -IMPORTANT: This section is valid only for the Groovy DSL. See the -<> section for YAML examples of a similar feature. - -You can define a method call that runs 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: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=method,indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=method,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=method,indent=0] ----- -==== - -The following code shows the base class portion of the test case: - -[source,groovy,indent=0] ----- -include::{plugins_path}/spring-cloud-contract-gradle-plugin/src/test/resources/functionalTest/bootSimple/src/test/groovy/org/springframework/cloud/contract/verifier/twitter/places/BaseMockMvcSpec.groovy[tags=base_class,indent=0] ----- - -IMPORTANT: You cannot use both a `String` and `execute` to perform concatenation. For -example, calling `header('Authorization', 'Bearer ' + execute('authToken()'))` leads to -improper results. Instead, call `header('Authorization', execute('authToken()'))` and -ensure that the `authToken()` method returns everything you need. - -The type of the object read from the JSON can be one of the following, depending on the -JSON path: - -* `String`: If you point to a `String` value in the JSON. -* `JSONArray`: If you point to a `List` in the JSON. -* `Map`: If you point to a `Map` in the JSON. -* `Number`: If you point to `Integer`, `Double`, and other numeric type in the JSON. -* `Boolean`: If you point to a `Boolean` in the JSON. - -In the request part of the contract, you can specify that the `body` should be taken from -a method. - -IMPORTANT: You must provide both the consumer and the producer side. The `execute` part -is applied for the whole body, not for parts of it. - -The following example shows how to read an object from JSON: - -[source,groovy,indent=0] ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MethodBodyBuilderSpec.groovy[tags=body_execute,indent=0] ----- - -The preceding example results in calling the `hashCode()` method in the request body. -It should resemble the following code: - -[source,java,indent=0] ----- - // given: - MockMvcRequestSpecification request = given() - .body(hashCode()); - - // when: - ResponseOptions response = given().spec(request) - .get("/something"); - - // then: - assertThat(response.statusCode()).isEqualTo(200); ----- - -[[contract-dsl-referencing-request-from-response]] -=== 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. - -If you write contracts in the Groovy DSL, 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 the given name. -* `fromRequest().query(String key, int index)`: Returns the nth query parameter with the -given name. -* `fromRequest().path()`: Returns the full path. -* `fromRequest().path(int index)`: Returns the nth path element. -* `fromRequest().header(String key)`: Returns the first header with the given name. -* `fromRequest().header(String key, int index)`: Returns the nth header with the given name. -* `fromRequest().body()`: Returns the full request body. -* `fromRequest().body(String jsonPath)`: Returns the element from the request that -matches the JSON Path. - -If you use the YAML contract definition or the Java one, you have to use the -https://handlebarsjs.com/[Handlebars] `{{{ }}}` notation with custom Spring Cloud Contract -functions to achieve this. In that case, you can use the following options: - -* `{{{ request.url }}}`: Returns the request URL and query parameters. -* `{{{ request.query.key.[index] }}}`: Returns the nth query parameter with the given name. -For example, for a key of `thing`, the first entry is `{{{ request.query.thing.[0] }}}` -* `{{{ request.path }}}`: Returns the full path. -* `{{{ request.path.[index] }}}`: Returns the nth path element. For example, -the first entry is ```{{{ request.path.[0] }}} -* `{{{ request.headers.key }}}`: Returns the first header with the given name. -* `{{{ request.headers.key.[index] }}}`: Returns the nth header with the given name. -* `{{{ request.body }}}`: Returns the full request body. -* `{{{ jsonpath this 'your.json.path' }}}`: Returns the element from the request that -matches the JSON Path. For example, for a JSON path of `$.here`, use `{{{ jsonpath this '$.here' }}}` - -Consider the following contract: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/SpringTestMethodBodyBuildersSpec.groovy[tags=template_contract,indent=0] ----- - -[source,yaml,indent=0,role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract_reference_request.yml[indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.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 { - - @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()); - }); - }); - }); - } - -} ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -package contracts.beer.rest - -import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract - -contract { - request { - method = method("POST") - url = url("/stats") - body(mapOf( - "name" to anyAlphaUnicode - )) - headers { - contentType = APPLICATION_JSON - } - } - response { - status = OK - body(mapOf( - "text" to "Don't worry ${fromRequest().body("$.name")} thanks for your interested in drinking beer", - "quantity" to v(c(5), p(anyNumber)) - )) - headers { - contentType = fromRequest().header(CONTENT_TYPE) - } - } -} ----- -==== - -Running a JUnit test generation leads to a test that resembles the following example: - -==== -[source,java,indent=0] ----- - // given: - MockMvcRequestSpecification request = given() - .header("Authorization", "secret") - .header("Authorization", "secret2") - .body("{\"foo\":\"bar\",\"baz\":5}"); - - // when: - ResponseOptions response = given().spec(request) - .queryParam("foo","bar") - .queryParam("foo","bar2") - .get("/api/v1/xxxx"); - - // then: - assertThat(response.statusCode()).isEqualTo(200); - assertThat(response.header("Authorization")).isEqualTo("foo secret bar"); - // and: - DocumentContext parsedJson = JsonPath.parse(response.getBody().asString()); - assertThatJson(parsedJson).field("['fullBody']").isEqualTo("{\"foo\":\"bar\",\"baz\":5}"); - assertThatJson(parsedJson).field("['authorization']").isEqualTo("secret"); - assertThatJson(parsedJson).field("['authorization2']").isEqualTo("secret2"); - assertThatJson(parsedJson).field("['path']").isEqualTo("/api/v1/xxxx"); - assertThatJson(parsedJson).field("['param']").isEqualTo("bar"); - assertThatJson(parsedJson).field("['paramIndex']").isEqualTo("bar2"); - assertThatJson(parsedJson).field("['pathIndex']").isEqualTo("v1"); - assertThatJson(parsedJson).field("['responseBaz']").isEqualTo(5); - assertThatJson(parsedJson).field("['responseFoo']").isEqualTo("bar"); - assertThatJson(parsedJson).field("['url']").isEqualTo("/api/v1/xxxx?foo=bar&foo=bar2"); - assertThatJson(parsedJson).field("['responseBaz2']").isEqualTo("Bla bla bar bla bla"); ----- -==== - -As you can see, elements from the request have been properly referenced in the response. - -The generated WireMock stub should resemble the following example: - -==== -[source,json,indent=0] ----- -{ - "request" : { - "urlPath" : "/api/v1/xxxx", - "method" : "POST", - "headers" : { - "Authorization" : { - "equalTo" : "secret2" - } - }, - "queryParameters" : { - "foo" : { - "equalTo" : "bar2" - } - }, - "bodyPatterns" : [ { - "matchesJsonPath" : "$[?(@.['baz'] == 5)]" - }, { - "matchesJsonPath" : "$[?(@.['foo'] == 'bar')]" - } ] - }, - "response" : { - "status" : 200, - "body" : "{\"authorization\":\"{{{request.headers.Authorization.[0]}}}\",\"path\":\"{{{request.path}}}\",\"responseBaz\":{{{jsonpath this '$.baz'}}} ,\"param\":\"{{{request.query.foo.[0]}}}\",\"pathIndex\":\"{{{request.path.[1]}}}\",\"responseBaz2\":\"Bla bla {{{jsonpath this '$.foo'}}} bla bla\",\"responseFoo\":\"{{{jsonpath this '$.foo'}}}\",\"authorization2\":\"{{{request.headers.Authorization.[1]}}}\",\"fullBody\":\"{{{escapejsonbody}}}\",\"url\":\"{{{request.url}}}\",\"paramIndex\":\"{{{request.query.foo.[1]}}}\"}", - "headers" : { - "Authorization" : "{{{request.headers.Authorization.[0]}}};foo" - }, - "transformers" : [ "response-template" ] - } -} ----- -==== - -Sending a request such as the one presented in the `request` part of the contract results -in sending the following response body: - -==== -[source,json,indent=0] ----- -{ - "url" : "/api/v1/xxxx?foo=bar&foo=bar2", - "path" : "/api/v1/xxxx", - "pathIndex" : "v1", - "param" : "bar", - "paramIndex" : "bar2", - "authorization" : "secret", - "authorization2" : "secret2", - "fullBody" : "{\"foo\":\"bar\",\"baz\":5}", - "responseFoo" : "bar", - "responseBaz" : 5, - "responseBaz2" : "Bla bla bar bla bla" -} ----- -==== - -IMPORTANT: This feature works only with WireMock versions 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 JSON. -* `jsonpath`: For a given parameter, finds an object in the request body. - -[[contract-dsl-matchers]] -=== Dynamic Properties in the Matchers Sections - -If you work with https://docs.pact.io/[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 the `bodyMatchers` section for two reasons: - -* Define the dynamic values that should end up in a stub. -You can set it in the `request` part of your contract. -* Verify the result of your test. -This section is present in the `response` or `outputMessage` side of the -contract. - -Currently, Spring Cloud Contract Verifier supports only JSON path-based matchers with the -following matching possibilities: - -[[coded-dsl]] -==== Coded DSL - -For the stubs (in tests on the consumer's side): - -* `byEquality()`: The value taken from the consumer's request in the provided JSON path must be -equal to the value provided in the contract. -* `byRegex(...)`: The value taken from the consumer's request in the provided JSON path must -match the regex. You can also pass the type of the expected matched value (for example, `asString()`, `asLong()`, and so on). -* `byDate()`: The value taken from the consumer's request in the provided JSON path must -match the regex for an ISO Date value. -* `byTimestamp()`: The value taken from the consumer's request in the provided JSON path must -match the regex for an ISO DateTime value. -* `byTime()`: The value taken from the consumer's request in the provided JSON path must -match the regex for an ISO Time value. - -For the verification (in generated tests on the Producer's side): - -* `byEquality()`: The value taken from the producer's response in the provided JSON path must be -equal to the provided value in the contract. -* `byRegex(...)`: The value taken from the producer's response in the provided JSON path must -match the regex. -* `byDate()`: The value taken from the producer's response in the provided JSON path must match -the regex for an ISO Date value. -* `byTimestamp()`: The value taken from the producer's response in the provided JSON path must -match the regex for an ISO DateTime value. -* `byTime()`: The value taken from the producer's response in the provided JSON path must match -the regex for an ISO Time value. -* `byType()`: The value taken from the producer's response in the provided JSON path needs to be -of the same type as the type defined in the body of the response in the contract. -`byType` can take a closure, in which you can set `minOccurrence` and `maxOccurrence`. For the -request side, you should use the closure to assert size of the collection. -That way, you can assert the size of the flattened collection. To check the size of an -unflattened collection, use a custom method with the `byCommand(...)` `testMatcher`. -* `byCommand(...)`: The value taken from the producer's response in the provided JSON path is -passed as an input to the custom method that you provide. For example, -`byCommand('thing($it)')` results in calling a `thing` method to which the value matching the -JSON Path gets passed. The type of the object read from the JSON can be one of the -following, depending on the JSON path: -** `String`: If you point to a `String` value. -** `JSONArray`: If you point to a `List`. -** `Map`: If you point to a `Map`. -** `Number`: If you point to `Integer`, `Double`, or another kind of number. -** `Boolean`: If you point to a `Boolean`. -* `byNull()`: The value taken from the response in the provided JSON path must be null. - -[[yaml]] -==== YAML - -NOTE: See the Groovy section for a detailed explanation of -what the types mean. - -For YAML, the structure of a matcher resembles the following example: - -[source,yml,indent=0] ----- -- path: $.thing1 - type: by_regex - value: thing2 - regexType: as_string ----- - -Alternatively, if you want to use one of the predefined regular expressions -`[only_alpha_unicode, number, any_boolean, ip_address, hostname, -email, url, uuid, iso_date, iso_date_time, iso_time, iso_8601_with_offset, non_empty, -non_blank]`, you can use something similar to the following example: - -[source,yml,indent=0] ----- -- path: $.thing1 - type: by_regex - predefined: only_alpha_unicode ----- - -The following list shows the allowed list of `type` values: - -* For `stubMatchers`: -** `by_equality` -** `by_regex` -** `by_date` -** `by_timestamp` -** `by_time` -** `by_type` -*** Two additional fields (`minOccurrence` and `maxOccurrence`) are accepted. -* For `testMatchers`: -** `by_equality` -** `by_regex` -** `by_date` -** `by_timestamp` -** `by_time` -** `by_type` -*** Two additional fields (`minOccurrence` and `maxOccurrence`) are accepted. -** `by_command` -** `by_null` - -You can also define which type the regular expression corresponds to in the `regexType` -field. The following list shows the allowed regular expression types: - -* `as_integer` -* `as_double` -* `as_float` -* `as_long` -* `as_short` -* `as_boolean` -* `as_string` - -Consider the following example: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MockMvcMethodBodyBuilderWithMatchersSpec.groovy[tags=matchers,indent=0] ----- - -[source,yaml,indent=0,role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract_matchers.yml[indent=0] ----- -==== - -In the preceding example, you can see the dynamic portions of the contract in the -`matchers` sections. For the request part, you can see that, for all fields but -`valueWithoutAMatcher`, the values of the regular expressions that the stub should -contain are explicitly set. For `valueWithoutAMatcher`, the verification takes place -in the same way as without the use of matchers. In that case, the test performs an -equality check. - -For the response side in the `bodyMatchers` section, we define the dynamic parts in a -similar manner. The only difference is that the `byType` matchers are also present. The -verifier engine checks four fields to verify whether the response from the test -has a value for which the JSON path matches the given field, is of the same type as the one -defined in the response body, and passes the following check (based on the method being called): - -* For `$.valueWithTypeMatch`, the engine checks whether the type is the same. -* For `$.valueWithMin`, the engine checks the type and asserts whether the size is greater -than or equal to the minimum occurrence. -* For `$.valueWithMax`, the engine checks the type and asserts whether the size is -smaller than or equal to the maximum occurrence. -* For `$.valueWithMinMax`, the engine checks the type and asserts whether the size is -between the minimum and maximum occurrence. - -The resulting test resembles the following example (note that an `and` section -separates the autogenerated assertions and the assertion from matchers): - -[source,java,indent=0] ----- - // given: - MockMvcRequestSpecification request = given() - .header("Content-Type", "application/json") - .body("{\"duck\":123,\"alpha\":\"abc\",\"number\":123,\"aBoolean\":true,\"date\":\"2017-01-01\",\"dateTime\":\"2017-01-01T01:23:45\",\"time\":\"01:02:34\",\"valueWithoutAMatcher\":\"foo\",\"valueWithTypeMatch\":\"string\",\"key\":{\"complex.key\":\"foo\"}}"); - - // when: - ResponseOptions response = given().spec(request) - .get("/get"); - - // 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("['valueWithoutAMatcher']").isEqualTo("foo"); - // and: - assertThat(parsedJson.read("$.duck", String.class)).matches("[0-9]{3}"); - assertThat(parsedJson.read("$.duck", Integer.class)).isEqualTo(123); - assertThat(parsedJson.read("$.alpha", String.class)).matches("[\\p{L}]*"); - assertThat(parsedJson.read("$.alpha", String.class)).isEqualTo("abc"); - assertThat(parsedJson.read("$.number", String.class)).matches("-?(\\d*\\.\\d+|\\d+)"); - assertThat(parsedJson.read("$.aBoolean", String.class)).matches("(true|false)"); - assertThat(parsedJson.read("$.date", String.class)).matches("(\\d\\d\\d\\d)-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])"); - assertThat(parsedJson.read("$.dateTime", String.class)).matches("([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])"); - assertThat(parsedJson.read("$.time", String.class)).matches("(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])"); - assertThat((Object) parsedJson.read("$.valueWithTypeMatch")).isInstanceOf(java.lang.String.class); - assertThat((Object) parsedJson.read("$.valueWithMin")).isInstanceOf(java.util.List.class); - assertThat((java.lang.Iterable) parsedJson.read("$.valueWithMin", java.util.Collection.class)).as("$.valueWithMin").hasSizeGreaterThanOrEqualTo(1); - assertThat((Object) parsedJson.read("$.valueWithMax")).isInstanceOf(java.util.List.class); - assertThat((java.lang.Iterable) parsedJson.read("$.valueWithMax", java.util.Collection.class)).as("$.valueWithMax").hasSizeLessThanOrEqualTo(3); - assertThat((Object) parsedJson.read("$.valueWithMinMax")).isInstanceOf(java.util.List.class); - assertThat((java.lang.Iterable) parsedJson.read("$.valueWithMinMax", java.util.Collection.class)).as("$.valueWithMinMax").hasSizeBetween(1, 3); - assertThat((Object) parsedJson.read("$.valueWithMinEmpty")).isInstanceOf(java.util.List.class); - assertThat((java.lang.Iterable) parsedJson.read("$.valueWithMinEmpty", java.util.Collection.class)).as("$.valueWithMinEmpty").hasSizeGreaterThanOrEqualTo(0); - assertThat((Object) parsedJson.read("$.valueWithMaxEmpty")).isInstanceOf(java.util.List.class); - assertThat((java.lang.Iterable) parsedJson.read("$.valueWithMaxEmpty", java.util.Collection.class)).as("$.valueWithMaxEmpty").hasSizeLessThanOrEqualTo(0); - assertThatValueIsANumber(parsedJson.read("$.duck")); - assertThat(parsedJson.read("$.['key'].['complex.key']", String.class)).isEqualTo("foo"); ----- - -IMPORTANT: Notice that, for the `byCommand` method, the example calls the -`assertThatValueIsANumber`. This method must be defined in the test base class or be -statically imported to your tests. Notice that the `byCommand` call was converted to -`assertThatValueIsANumber(parsedJson.read("$.duck"));`. That means that the engine took -the method name and passed the proper JSON path as a parameter to it. - -The resulting WireMock stub is in the following example: - -[source,json,indent=0] ----- -include::{plugins_path}/spring-cloud-contract-converters/src/test/groovy/org/springframework/cloud/contract/verifier/wiremock/DslToWireMockClientConverterSpec.groovy[tags=matchers,indent=0] ----- - -IMPORTANT: If you use a `matcher`, the part of the request and response that the -`matcher` addresses with the JSON Path gets removed from the assertion. In the case of -verifying a collection, you must create matchers for *all* the elements of the -collection. - -Consider the following example: - -==== -[source,groovy,indent=0] ----- -Contract.make { - request { - method 'GET' - url("/foo") - } - response { - status OK() - body(events: [[ - operation : 'EXPORT', - eventId : '16f1ed75-0bcc-4f0d-a04d-3121798faf99', - status : 'OK' - ], [ - operation : 'INPUT_PROCESSING', - eventId : '3bb4ac82-6652-462f-b6d1-75e424a0024a', - status : 'OK' - ] - ] - ) - bodyMatchers { - jsonPath('$.events[0].operation', byRegex('.+')) - jsonPath('$.events[0].eventId', byRegex('^([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})$')) - jsonPath('$.events[0].status', byRegex('.+')) - } - } -} ----- -==== - -The preceding code leads to creating the following test (the code block shows only the assertion section): - -==== -[source,java,indent=0] ----- - and: - DocumentContext parsedJson = JsonPath.parse(response.body.asString()) - assertThatJson(parsedJson).array("['events']").contains("['eventId']").isEqualTo("16f1ed75-0bcc-4f0d-a04d-3121798faf99") - assertThatJson(parsedJson).array("['events']").contains("['operation']").isEqualTo("EXPORT") - assertThatJson(parsedJson).array("['events']").contains("['operation']").isEqualTo("INPUT_PROCESSING") - assertThatJson(parsedJson).array("['events']").contains("['eventId']").isEqualTo("3bb4ac82-6652-462f-b6d1-75e424a0024a") - assertThatJson(parsedJson).array("['events']").contains("['status']").isEqualTo("OK") - and: - assertThat(parsedJson.read("\$.events[0].operation", String.class)).matches(".+") - 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(".+") ----- -==== - -Note that the assertion is malformed. Only the first element of the array got -asserted. To fix this, apply the assertion to the whole `$.events` -collection and assert it with the `byCommand(...)` method. - -[[contract-dsl-async]] -== Asynchronous Support - -If you use asynchronous communication on the server side (your controllers are -returning `Callable`, `DeferredResult`, and so on), then, inside your contract, you must -provide an `async()` method in the `response` section. The following code shows an example: - -==== -[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] -.Groovy ----- -org.springframework.cloud.contract.spec.Contract.make { - request { - method GET() - url '/get' - } - response { - status OK() - body 'Passed' - async() - } -} ----- - -[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] -.YAML ----- -response: - async: true ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -class contract implements Supplier> { - - @Override - public Collection get() { - return Collections.singletonList(Contract.make(c -> { - c.request(r -> { - // ... - }); - c.response(r -> { - r.async(); - // ... - }); - })); - } - -} ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract - -contract { - request { - // ... - } - response { - async = true - // ... - } -} ----- -==== - -You can also use the `fixedDelayMilliseconds` method or property to add delay to your stubs. -The following example shows how to do so: - -==== -[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] -.Groovy ----- -org.springframework.cloud.contract.spec.Contract.make { - request { - method GET() - url '/get' - } - response { - status 200 - body 'Passed' - fixedDelayMilliseconds 1000 - } -} ----- - -[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] -.YAML ----- -response: - fixedDelayMilliseconds: 1000 ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -class contract implements Supplier> { - - @Override - public Collection get() { - return Collections.singletonList(Contract.make(c -> { - c.request(r -> { - // ... - }); - c.response(r -> { - r.fixedDelayMilliseconds(1000); - // ... - }); - })); - } - -} ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract - -contract { - request { - // ... - } - response { - delay = fixedMilliseconds(1000) - // ... - } -} ----- -==== - -[[contract-dsl-xml]] -== XML Support for HTTP - -For HTTP contracts, we also support using XML in the request and response body. -The XML body has to be passed within the `body` element -as a `String` or `GString`. Also, body matchers can be provided for -both the request and the response. In place of the `jsonPath(...)` method, the `org.springframework.cloud.contract.spec.internal.BodyMatchers.xPath` -method should be used, with the desired `xPath` provided as the first argument -and the appropriate `MatchingType` as the second argument. All the body matchers apart from `byType()` are supported. - -The following example shows a Groovy DSL contract with XML in the response body: - -==== -[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] -.Groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/XmlMethodBodyBuilderSpec.groovy[tags=xmlgroovy] ----- - -[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/contract_rest_xml.yml[indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -include::{verifier_core_path}/src/test/resources/contractsToCompile/contract_xml.java[tags=class,indent=0] ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -include::{verifier_core_path}/src/test/resources/kotlin/contract_xml.kts[tags=class,indent=0] ----- -==== - -The following example shows an automatically generated test for XML in the response body: - -==== -[source,java,indent=0] ----- -@Test -public void validate_xmlMatches() throws Exception { - // given: - MockMvcRequestSpecification request = given() - .header("Content-Type", "application/xml"); - - // when: - ResponseOptions response = given().spec(request).get("/get"); - - // then: - assertThat(response.statusCode()).isEqualTo(200); - // and: - DocumentBuilder documentBuilder = DocumentBuilderFactory.newInstance() - .newDocumentBuilder(); - Document parsedXml = documentBuilder.parse(new InputSource( - new StringReader(response.getBody().asString()))); - // and: - assertThat(valueFromXPath(parsedXml, "/test/list/elem/text()")).isEqualTo("abc"); - assertThat(valueFromXPath(parsedXml,"/test/list/elem[2]/text()")).isEqualTo("def"); - assertThat(valueFromXPath(parsedXml, "/test/duck/text()")).matches("[0-9]{3}"); - assertThat(nodeFromXPath(parsedXml, "/test/duck/xxx")).isNull(); - assertThat(valueFromXPath(parsedXml, "/test/alpha/text()")).matches("[\\p{L}]*"); - assertThat(valueFromXPath(parsedXml, "/test/*/complex/text()")).isEqualTo("foo"); - assertThat(valueFromXPath(parsedXml, "/test/duck/@type")).isEqualTo("xtype"); - } ----- -==== - -[[xml-support-for-namespaces]] -=== XML Support for Namespaces -Namespaced XML is supported. However, any XPath expresssions used to select namespaced content must be updated. - -Consider the following explicitly namespaced XML document: - -[source,xml,indent=0] ----- - - customer@test.com - ----- -The XPath expression to select the email address is: `/ns1:customer/email/text()`. - -WARNING: Beware as the unqualified expression (`/customer/email/text()`) results in `""`. - -For content that uses an unqualified namespace, the expression is more verbose. Consider the following XML document that -uses an unqualified namespace: - -[source,xml,indent=0] ----- - - customer@test.com - ----- -The XPath expression to select the email address is -``` -*/[local-name()='customer' and namespace-uri()='http://demo.com/customer']/*[local-name()='email']/text() -``` -WARNING: Beware, as the unqualified expressions (`/customer/email/text()` or `*/[local-name()='customer' and namespace-uri()='http://demo.com/customer']/email/text()`) -result in `""`. Even the child elements have to be referenced with the `local-name` syntax. - -[[general-namespaced-node-expression-syntax]] -==== General Namespaced Node Expression Syntax -- Node using qualified namespace: -``` -/ -``` -- Node using and defining an unqualified namespace: -``` -/*[local-name=()='' and namespace-uri=()=''] -``` -NOTE: In some cases, you can omit the `namespace_uri` portion, but doing so may lead to ambiguity. - -- Node using an unqualified namespace (one of its ancestor's defines the xmlns attribute): -``` -/*[local-name=()=''] -``` - - -[[contract-dsl-multiple]] -== Multiple Contracts in One File - -You can define multiple contracts in one file. Such a contract might resemble the -following example: - -==== -[source,groovy,indent=0,role="primary"] -.Groovy ----- -include::{plugins_path}/spring-cloud-contract-maven-plugin/src/test/projects/multiple-contracts/src/test/resources/contracts/com/hello/v1/WithList.groovy[lines=18..-1,indent=0] ----- - -[source,yaml,indent=0,role="secondary"] -.YAML ----- -include::{verifier_core_path}/src/test/resources/yml/multiple_contracts.yml[indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Java ----- -class contract implements Supplier> { - - @Override - public Collection get() { - return Arrays.asList( - Contract.make(c -> { - c.name("should post a user"); - // ... - }), Contract.make(c -> { - // ... - }), Contract.make(c -> { - // ... - }) - ); - } - -} ----- - -[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] -.Kotlin ----- -import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract - -arrayOf( - contract { - name("should post a user") - // ... - }, - contract { - // ... - }, - contract { - // ... - } -} ----- -==== - -In the preceding example, one contract has the `name` field and the other does not. This -leads to generation of two tests that look like the following: - -==== -[source,java,indent=0] ----- -package org.springframework.cloud.contract.verifier.tests.com.hello; - -import com.example.TestBase; -import com.jayway.jsonpath.DocumentContext; -import com.jayway.jsonpath.JsonPath; -import com.jayway.restassured.module.mockmvc.specification.MockMvcRequestSpecification; -import com.jayway.restassured.response.ResponseOptions; -import org.junit.Test; - -import static com.jayway.restassured.module.mockmvc.RestAssuredMockMvc.*; -import static com.toomuchcoding.jsonassert.JsonAssertion.assertThatJson; -import static org.assertj.core.api.Assertions.assertThat; - -public class V1Test extends TestBase { - - @Test - public void validate_should_post_a_user() throws Exception { - // given: - MockMvcRequestSpecification request = given(); - - // when: - ResponseOptions response = given().spec(request) - .post("/users/1"); - - // then: - assertThat(response.statusCode()).isEqualTo(200); - } - - @Test - public void validate_withList_1() throws Exception { - // given: - MockMvcRequestSpecification request = given(); - - // when: - ResponseOptions response = given().spec(request) - .post("/users/2"); - - // then: - assertThat(response.statusCode()).isEqualTo(200); - } - -} ----- -==== - -Notice that, for the contract that has the `name` field, the generated test method is named -`validate_should_post_a_user`. The one that does not have the `name` field is called -`validate_withList_1`. It corresponds to the name of the file `WithList.groovy` and the -index of the contract in the list. - -The generated stubs are shown in the following example: - -==== -[source] ----- -should post a user.json -1_WithList.json ----- -==== - -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: It is much better to name your contracts, because doing so makes -your tests far more meaningful. - -[[contract-stateful-contracts]] -== Stateful Contracts - -Stateful contracts (also known as scenarios) are contract definitions that should be read -in order. This might be useful in the following situations: - -* You want to invoke the contract in a precisely defined order, since you use Spring -Cloud Contract to test your stateful application. - -TIP: We really discourage you from doing that, since contract tests should be stateless. - -* You want the same endpoint to return different results for the same request. - -To create stateful contracts (or scenarios), you need to -use the proper naming convention while creating your contracts. The convention -requires including an order number followed by an underscore. This works regardless -of whether you work with YAML or Groovy. The following listing shows an example: - -==== -[source,indent=0] ----- -my_contracts_dir\ - scenario1\ - 1_login.groovy - 2_showCart.groovy - 3_logout.groovy ----- -==== - -Such a tree causes Spring Cloud Contract Verifier to generate WireMock's scenario with a -name of `scenario1` and the three following steps: - -. `login`, marked as `Started` pointing to... -. `showCart`, marked as `Step1` pointing to... -. `logout`, marked as `Step2` (which closes the scenario). - -You can find more details about WireMock scenarios at -https://wiremock.org/docs/stateful-behaviour/[https://wiremock.org/docs/stateful-behaviour/]. diff --git a/docs/modules/ROOT/pages/_project-features-contract/common-top-elements.adoc b/docs/modules/ROOT/pages/_project-features-contract/common-top-elements.adoc new file mode 100644 index 0000000000..7175d17dc0 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-contract/common-top-elements.adoc @@ -0,0 +1,305 @@ +[[contract-common-top-elements]] += Common Top-Level Elements + +The following sections describe the most common top-level elements: + +* <> +* <> +* <> +* <> +* <> +* <> + +[[contract-dsl-description]] +== Description + +You can add a `description` to your contract. The description is arbitrary text. The +following code shows an example: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{contract_spec_tests_path}/src/test/groovy/org/springframework/cloud/contract/spec/internal/ContractSpec.groovy[tags=description,indent=0] +---- + +[source,yaml,indent=0,role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract_rest.yml[indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[tags=description,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[tags=description,indent=0] +---- +==== + +[[contract-dsl-name]] +== Name + +You can provide a name for your contract. Assume that you provide 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. + +The following example shows how to add a name to a contract: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{contract_spec_tests_path}/src/test/groovy/org/springframework/cloud/contract/spec/internal/ContractSpec.groovy[tags=name,indent=0] +---- + +[source,yaml,indent=0,role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=name,indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[tags=name,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[tags=name,indent=0] +---- +==== + +[[contract-dsl-ignoring-contracts]] +== Ignoring Contracts + +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 +example shows how to do so: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{contract_spec_tests_path}/src/test/groovy/org/springframework/cloud/contract/spec/internal/ContractSpec.groovy[tags=ignored,indent=0] +---- + +[source,yaml,indent=0,role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=ignored,indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[tags=ignored,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[tags=ignored,indent=0] +---- +==== + +[[contract-dsl-in-progress]] +== Contracts in Progress + +A contract in progress does not generate tests on the producer side but does allow generation of stubs. + +IMPORTANT: Use this feature with caution as it may lead to false positives, because you generate stubs for your consumers to use without actually having the implementation in place. + +If you want to set a contract in progress, the following +example shows how to do so: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{contract_spec_tests_path}/src/test/groovy/org/springframework/cloud/contract/spec/internal/ContractSpec.groovy[tags=in_progress,indent=0] +---- + +[source,yaml,indent=0,role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=in_progress,indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[tags=in_progress,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[tags=in_progress,indent=0] +---- +==== + +You can set the value of the `failOnInProgress` Spring Cloud Contract plugin property to ensure that your build breaks when at least one contract in progress remains in your sources. + +[[contract-dsl-passing-values-from-files]] +== Passing Values from Files + +Starting with version `1.2.0`, you can pass values from files. Assume that you have the +following resources in your project: + +[source,bash,indent=0] +---- +└── src +    └── test +       └── resources +          └── contracts +    ├── readFromFile.groovy +    ├── request.json +    └── response.json +---- + +Further assume that your contract is as follows: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/resources/classpath/readFromFile.groovy[indent=0] +---- + +[source,yaml,indent=0,role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract_from_file.yml[indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_rest_from_file.java[tags=class,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{verifier_core_path}/src/test/resources/kotlin/readFromFile.kts[tags=class,indent=0] +---- +==== + +Further assume that the JSON files are as follows: + +==== +[source,json,indent=0,subs="verbatim,attributes",role="primary"] +.request.json +---- +include:../:{verifier_core_path}/src/test/resources/classpath/request.json[indent=0] +---- + +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.response.json +---- +include:../:{verifier_core_path}/src/test/resources/classpath/response.json[indent=0] +---- +==== + +When test or stub generation takes place, the contents of the `request.json` and `response.json` files are passed to the body +of a request or a response. The name of the file needs to be a file in a location +relative to the folder in which the contract resides. + +If you need to pass the contents of a file in binary form, +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: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/resources/body_builder/worksWithPdf.groovy[indent=0] +---- + +[source,yaml,indent=0,role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract_pdf.yml[indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_rest_from_pdf.java[tags=class,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{contract_kotlin_spec_path}/src/test/resources/contracts/shouldWorkWithBinaryPayload.kts[tags=class,indent=0] +---- +==== + +IMPORTANT: You should use this approach whenever you want to work with binary payloads, +both for HTTP and messaging. + +[[contract-dsl-metadata]] +== Metadata + +You can add `metadata` to your contract. Via the metadata you can pass in configuration to extensions. Below you can find +an example of using the `wiremock` key. Its value is a map whose key is `stubMapping` and value being WireMock's `StubMapping` object. Spring Cloud Contract is able to +patch parts of your generated stub mapping with your custom code. You may want to do that in order to add webhooks, custom +delays or integrate with third party WireMock extensions. + +==== +[source,groovy,indent=0,role="primary"] +.groovy +---- +include:../:{standalone_samples_path}/http-server/src/test/resources/contracts/fraud/shouldReturnFraudStats.groovy[tags=metadata,indent=0] +---- + +[source,yaml,indent=0,role="secondary"] +.yml +---- +include:../:{standalone_samples_path}/http-server/src/test/resources/contracts/yml/fraud/shouldReturnFraudStats.yml[tags=metadata,indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_rest_with_tags.java[tags=metadata,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.kotlin +---- +include:../:{contract_kotlin_spec_path}/src/test/kotlin/org/springframework/cloud/contract/spec/ContractTests.kt[tags=metadata,indent=0] +---- +==== + +In the following sections you can find examples of the supported metadata entries. + +//// +include:../:{project-root}/docs/target/metadata.adoc[indent=0] +//// + +[[features-http]] += Contracts for HTTP + +Spring Cloud Contract lets you verify applications that use REST or HTTP as a +means of communication. Spring Cloud Contract verifies that, for a request that matches the +criteria from the `request` part of the contract, the server provides a response that is in +keeping with the `response` part of the contract. Subsequently, the contracts are used to +generate WireMock stubs that, for any request matching the provided criteria, provide a +suitable response. + diff --git a/docs/modules/ROOT/pages/_project-features-contract/dsl-async.adoc b/docs/modules/ROOT/pages/_project-features-contract/dsl-async.adoc new file mode 100644 index 0000000000..c1763f0314 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-contract/dsl-async.adoc @@ -0,0 +1,134 @@ +[[contract-dsl-async]] += Asynchronous Support + +If you use asynchronous communication on the server side (your controllers are +returning `Callable`, `DeferredResult`, and so on), then, inside your contract, you must +provide an `async()` method in the `response` section. The following code shows an example: + +==== +[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] +.Groovy +---- +org.springframework.cloud.contract.spec.Contract.make { + request { + method GET() + url '/get' + } + response { + status OK() + body 'Passed' + async() + } +} +---- + +[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] +.YAML +---- +response: + async: true +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +class contract implements Supplier> { + + @Override + public Collection get() { + return Collections.singletonList(Contract.make(c -> { + c.request(r -> { + // ... + }); + c.response(r -> { + r.async(); + // ... + }); + })); + } + +} +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract + +contract { + request { + // ... + } + response { + async = true + // ... + } +} +---- +==== + +You can also use the `fixedDelayMilliseconds` method or property to add delay to your stubs. +The following example shows how to do so: + +==== +[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] +.Groovy +---- +org.springframework.cloud.contract.spec.Contract.make { + request { + method GET() + url '/get' + } + response { + status 200 + body 'Passed' + fixedDelayMilliseconds 1000 + } +} +---- + +[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] +.YAML +---- +response: + fixedDelayMilliseconds: 1000 +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +class contract implements Supplier> { + + @Override + public Collection get() { + return Collections.singletonList(Contract.make(c -> { + c.request(r -> { + // ... + }); + c.response(r -> { + r.fixedDelayMilliseconds(1000); + // ... + }); + })); + } + +} +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract + +contract { + request { + // ... + } + response { + delay = fixedMilliseconds(1000) + // ... + } +} +---- +==== + diff --git a/docs/modules/ROOT/pages/_project-features-contract/dsl-dynamic-properties.adoc b/docs/modules/ROOT/pages/_project-features-contract/dsl-dynamic-properties.adoc new file mode 100644 index 0000000000..23335500cd --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-contract/dsl-dynamic-properties.adoc @@ -0,0 +1,797 @@ +[[contract-dsl-dynamic-properties]] += 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. + +For the Groovy DSL, you can provide the dynamic parts in your contracts +in two ways: pass them directly in the body or set them in a separate section called +`bodyMatchers`. + +NOTE: Before 2.0.0, these were set by using `testMatchers` and `stubMatchers`. +See the https://github.com/spring-cloud/spring-cloud-contract/wiki/Spring-Cloud-Contract-2.0-Migration-Guide[migration guide] for more information. + +For YAML, you can use only the `matchers` section. + +IMPORTANT: Entries inside the `matchers` must reference existing elements of the payload. For more information, see https://github.com/spring-cloud/spring-cloud-contract/issues/722[this issue]. + +[[contract-dsl-dynamic-properties-in-body]] +== Dynamic Properties inside the Body + +IMPORTANT: This section is valid only for the Coded DSL (Groovy, Java, and so on). See the +<> section for YAML examples of a similar feature. + +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: + +==== +[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] +.value +---- +value(consumer(...), producer(...)) +value(c(...), p(...)) +value(stub(...), test(...)) +value(client(...), server(...)) +---- + +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.$ +---- +$(consumer(...), producer(...)) +$(c(...), p(...)) +$(stub(...), test(...)) +$(client(...), server(...)) +---- +==== + +Both approaches work equally well. The `stub` and `client` methods are aliases over the `consumer` +method. Subsequent sections take a closer look at what you can do with those values. + +[[contract-dsl-regex]] +== Regular Expressions + +IMPORTANT: This section is valid only for the Groovy DSL. See the +<> section for YAML examples of a similar feature. + +You can use regular expressions to write your requests in the 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 tests and your server-side tests. + +Make sure that regex matches a whole region of a sequence, as, internally, +https://docs.oracle.com/javase/8/docs/api/java/util/regex/Matcher.html#matches[`Pattern.matches()`] +is called. For instance, `abc` does not match `aabc`, but `.abc` does. +There are several additional <> as well. + +The following example shows how to use regular expressions to write a request: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=regex,indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=regex,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=regex,indent=0] +---- +==== + +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 for Groovy: + +[source,groovy,indent=0] +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/SpringTestMethodBodyBuildersSpec.groovy[tags=dsl_one_side_data_generation_example,indent=0] +---- + +In the preceding example, the opposite side of the communication has the respective data +generated for request and response. + +Spring Cloud Contract comes with a series of predefined regular expressions that you can +use in your contracts, as the following example shows: + +[source,java,indent=0] +---- +include:../:{contract_spec_path}/src/main/java/org/springframework/cloud/contract/spec/internal/RegexPatterns.java[tags=regexps,indent=0] +---- + +In your contract, you can use it as follows (example for the Groovy DSL): + +[source,groovy,indent=0] +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/SpringTestMethodBodyBuildersSpec.groovy[tags=contract_with_regex,indent=0] +---- + +To make matters even simpler, you can use a set of predefined objects that automatically +assume that you want a regular expression to be passed. +All of those methods start with the `any` prefix, as follows: + +[source,java,indent=0] +---- +include:../:{contract_spec_path}/src/main/java/org/springframework/cloud/contract/spec/internal/RegexCreatingProperty.java[tags=regex_creating_props,indent=0] +---- + +The following example shows how you can reference those methods: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=regex_creating_props,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=regex_creating_props,indent=0] +---- +==== + +[[contract-dsl-regex-limitations]] +=== Limitations + +CAUTION: Due to certain limitations of the `Xeger` library that generates a string out of +a regex, do not use the `$` and `^` signs in your regex if you rely on automatic +generation. See https://github.com/spring-cloud/spring-cloud-contract/issues/899[Issue 899]. + +CAUTION: Do not use a `LocalDate` instance as a value for `$` (for example, `$(consumer(LocalDate.now()))`). +It causes a `java.lang.StackOverflowError`. Use `$(consumer(LocalDate.now().toString()))` instead. +See https://github.com/spring-cloud/spring-cloud-contract/issues/900[Issue 900]. + +[[contract-dsl-optional-params]] +== Passing Optional Parameters + +IMPORTANT: This section is valid only for Groovy DSL. See the +<> section for YAML examples of a similar feature. + +You can provide optional parameters in your contract. However, you can provide +optional parameters only for the following: + +* The STUB side of the Request +* The TEST side of the Response + +The following example shows how to provide optional parameters: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=optionals,indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=optionals,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=optionals,indent=0] +---- +==== + +By wrapping a part of the body with the `optional()` method, you create a regular +expression that must be present 0 or more times. + +If you use Spock, the following test would be generated from the previous example: + +==== +[source,groovy,indent=0] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=optionals_test,indent=0] +---- +==== + +The following stub would also be generated: + +[source,groovy,indent=0] +---- +include:../:{plugins_path}/spring-cloud-contract-converters/src/test/groovy/org/springframework/cloud/contract/verifier/wiremock/DslToWireMockClientConverterSpec.groovy[tags=wiremock,indent=0] +---- + +[[contract-dsl-custom-methods]] +== Calling Custom Methods on the Server Side + +IMPORTANT: This section is valid only for the Groovy DSL. See the +<> section for YAML examples of a similar feature. + +You can define a method call that runs 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: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=method,indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=method,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=method,indent=0] +---- +==== + +The following code shows the base class portion of the test case: + +[source,groovy,indent=0] +---- +include:../:{plugins_path}/spring-cloud-contract-gradle-plugin/src/test/resources/functionalTest/bootSimple/src/test/groovy/org/springframework/cloud/contract/verifier/twitter/places/BaseMockMvcSpec.groovy[tags=base_class,indent=0] +---- + +IMPORTANT: You cannot use both a `String` and `execute` to perform concatenation. For +example, calling `header('Authorization', 'Bearer ' + execute('authToken()'))` leads to +improper results. Instead, call `header('Authorization', execute('authToken()'))` and +ensure that the `authToken()` method returns everything you need. + +The type of the object read from the JSON can be one of the following, depending on the +JSON path: + +* `String`: If you point to a `String` value in the JSON. +* `JSONArray`: If you point to a `List` in the JSON. +* `Map`: If you point to a `Map` in the JSON. +* `Number`: If you point to `Integer`, `Double`, and other numeric type in the JSON. +* `Boolean`: If you point to a `Boolean` in the JSON. + +In the request part of the contract, you can specify that the `body` should be taken from +a method. + +IMPORTANT: You must provide both the consumer and the producer side. The `execute` part +is applied for the whole body, not for parts of it. + +The following example shows how to read an object from JSON: + +[source,groovy,indent=0] +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MethodBodyBuilderSpec.groovy[tags=body_execute,indent=0] +---- + +The preceding example results in calling the `hashCode()` method in the request body. +It should resemble the following code: + +[source,java,indent=0] +---- + // given: + MockMvcRequestSpecification request = given() + .body(hashCode()); + + // when: + ResponseOptions response = given().spec(request) + .get("/something"); + + // then: + assertThat(response.statusCode()).isEqualTo(200); +---- + +[[contract-dsl-referencing-request-from-response]] +== 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. + +If you write contracts in the Groovy DSL, 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 the given name. +* `fromRequest().query(String key, int index)`: Returns the nth query parameter with the +given name. +* `fromRequest().path()`: Returns the full path. +* `fromRequest().path(int index)`: Returns the nth path element. +* `fromRequest().header(String key)`: Returns the first header with the given name. +* `fromRequest().header(String key, int index)`: Returns the nth header with the given name. +* `fromRequest().body()`: Returns the full request body. +* `fromRequest().body(String jsonPath)`: Returns the element from the request that +matches the JSON Path. + +If you use the YAML contract definition or the Java one, you have to use the +https://handlebarsjs.com/[Handlebars] `{{{ }}}` notation with custom Spring Cloud Contract +functions to achieve this. In that case, you can use the following options: + +* `{{{ request.url }}}`: Returns the request URL and query parameters. +* `{{{ request.query.key.[index] }}}`: Returns the nth query parameter with the given name. +For example, for a key of `thing`, the first entry is `{{{ request.query.thing.[0] }}}` +* `{{{ request.path }}}`: Returns the full path. +* `{{{ request.path.[index] }}}`: Returns the nth path element. For example, +the first entry is ```{{{ request.path.[0] }}} +* `{{{ request.headers.key }}}`: Returns the first header with the given name. +* `{{{ request.headers.key.[index] }}}`: Returns the nth header with the given name. +* `{{{ request.body }}}`: Returns the full request body. +* `{{{ jsonpath this 'your.json.path' }}}`: Returns the element from the request that +matches the JSON Path. For example, for a JSON path of `$.here`, use `{{{ jsonpath this '$.here' }}}` + +Consider the following contract: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/SpringTestMethodBodyBuildersSpec.groovy[tags=template_contract,indent=0] +---- + +[source,yaml,indent=0,role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract_reference_request.yml[indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.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 { + + @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()); + }); + }); + }); + } + +} +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +package contracts.beer.rest + +import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract + +contract { + request { + method = method("POST") + url = url("/stats") + body(mapOf( + "name" to anyAlphaUnicode + )) + headers { + contentType = APPLICATION_JSON + } + } + response { + status = OK + body(mapOf( + "text" to "Don't worry ${fromRequest().body("$.name")} thanks for your interested in drinking beer", + "quantity" to v(c(5), p(anyNumber)) + )) + headers { + contentType = fromRequest().header(CONTENT_TYPE) + } + } +} +---- +==== + +Running a JUnit test generation leads to a test that resembles the following example: + +==== +[source,java,indent=0] +---- + // given: + MockMvcRequestSpecification request = given() + .header("Authorization", "secret") + .header("Authorization", "secret2") + .body("{\"foo\":\"bar\",\"baz\":5}"); + + // when: + ResponseOptions response = given().spec(request) + .queryParam("foo","bar") + .queryParam("foo","bar2") + .get("/api/v1/xxxx"); + + // then: + assertThat(response.statusCode()).isEqualTo(200); + assertThat(response.header("Authorization")).isEqualTo("foo secret bar"); + // and: + DocumentContext parsedJson = JsonPath.parse(response.getBody().asString()); + assertThatJson(parsedJson).field("['fullBody']").isEqualTo("{\"foo\":\"bar\",\"baz\":5}"); + assertThatJson(parsedJson).field("['authorization']").isEqualTo("secret"); + assertThatJson(parsedJson).field("['authorization2']").isEqualTo("secret2"); + assertThatJson(parsedJson).field("['path']").isEqualTo("/api/v1/xxxx"); + assertThatJson(parsedJson).field("['param']").isEqualTo("bar"); + assertThatJson(parsedJson).field("['paramIndex']").isEqualTo("bar2"); + assertThatJson(parsedJson).field("['pathIndex']").isEqualTo("v1"); + assertThatJson(parsedJson).field("['responseBaz']").isEqualTo(5); + assertThatJson(parsedJson).field("['responseFoo']").isEqualTo("bar"); + assertThatJson(parsedJson).field("['url']").isEqualTo("/api/v1/xxxx?foo=bar&foo=bar2"); + assertThatJson(parsedJson).field("['responseBaz2']").isEqualTo("Bla bla bar bla bla"); +---- +==== + +As you can see, elements from the request have been properly referenced in the response. + +The generated WireMock stub should resemble the following example: + +==== +[source,json,indent=0] +---- +{ + "request" : { + "urlPath" : "/api/v1/xxxx", + "method" : "POST", + "headers" : { + "Authorization" : { + "equalTo" : "secret2" + } + }, + "queryParameters" : { + "foo" : { + "equalTo" : "bar2" + } + }, + "bodyPatterns" : [ { + "matchesJsonPath" : "$[?(@.['baz'] == 5)]" + }, { + "matchesJsonPath" : "$[?(@.['foo'] == 'bar')]" + } ] + }, + "response" : { + "status" : 200, + "body" : "{\"authorization\":\"{{{request.headers.Authorization.[0]}}}\",\"path\":\"{{{request.path}}}\",\"responseBaz\":{{{jsonpath this '$.baz'}}} ,\"param\":\"{{{request.query.foo.[0]}}}\",\"pathIndex\":\"{{{request.path.[1]}}}\",\"responseBaz2\":\"Bla bla {{{jsonpath this '$.foo'}}} bla bla\",\"responseFoo\":\"{{{jsonpath this '$.foo'}}}\",\"authorization2\":\"{{{request.headers.Authorization.[1]}}}\",\"fullBody\":\"{{{escapejsonbody}}}\",\"url\":\"{{{request.url}}}\",\"paramIndex\":\"{{{request.query.foo.[1]}}}\"}", + "headers" : { + "Authorization" : "{{{request.headers.Authorization.[0]}}};foo" + }, + "transformers" : [ "response-template" ] + } +} +---- +==== + +Sending a request such as the one presented in the `request` part of the contract results +in sending the following response body: + +==== +[source,json,indent=0] +---- +{ + "url" : "/api/v1/xxxx?foo=bar&foo=bar2", + "path" : "/api/v1/xxxx", + "pathIndex" : "v1", + "param" : "bar", + "paramIndex" : "bar2", + "authorization" : "secret", + "authorization2" : "secret2", + "fullBody" : "{\"foo\":\"bar\",\"baz\":5}", + "responseFoo" : "bar", + "responseBaz" : 5, + "responseBaz2" : "Bla bla bar bla bla" +} +---- +==== + +IMPORTANT: This feature works only with WireMock versions 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 JSON. +* `jsonpath`: For a given parameter, finds an object in the request body. + +[[contract-dsl-matchers]] +== Dynamic Properties in the Matchers Sections + +If you work with https://docs.pact.io/[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 the `bodyMatchers` section for two reasons: + +* Define the dynamic values that should end up in a stub. +You can set it in the `request` part of your contract. +* Verify the result of your test. +This section is present in the `response` or `outputMessage` side of the +contract. + +Currently, Spring Cloud Contract Verifier supports only JSON path-based matchers with the +following matching possibilities: + +[[coded-dsl]] +=== Coded DSL + +For the stubs (in tests on the consumer's side): + +* `byEquality()`: The value taken from the consumer's request in the provided JSON path must be +equal to the value provided in the contract. +* `byRegex(...)`: The value taken from the consumer's request in the provided JSON path must +match the regex. You can also pass the type of the expected matched value (for example, `asString()`, `asLong()`, and so on). +* `byDate()`: The value taken from the consumer's request in the provided JSON path must +match the regex for an ISO Date value. +* `byTimestamp()`: The value taken from the consumer's request in the provided JSON path must +match the regex for an ISO DateTime value. +* `byTime()`: The value taken from the consumer's request in the provided JSON path must +match the regex for an ISO Time value. + +For the verification (in generated tests on the Producer's side): + +* `byEquality()`: The value taken from the producer's response in the provided JSON path must be +equal to the provided value in the contract. +* `byRegex(...)`: The value taken from the producer's response in the provided JSON path must +match the regex. +* `byDate()`: The value taken from the producer's response in the provided JSON path must match +the regex for an ISO Date value. +* `byTimestamp()`: The value taken from the producer's response in the provided JSON path must +match the regex for an ISO DateTime value. +* `byTime()`: The value taken from the producer's response in the provided JSON path must match +the regex for an ISO Time value. +* `byType()`: The value taken from the producer's response in the provided JSON path needs to be +of the same type as the type defined in the body of the response in the contract. +`byType` can take a closure, in which you can set `minOccurrence` and `maxOccurrence`. For the +request side, you should use the closure to assert size of the collection. +That way, you can assert the size of the flattened collection. To check the size of an +unflattened collection, use a custom method with the `byCommand(...)` `testMatcher`. +* `byCommand(...)`: The value taken from the producer's response in the provided JSON path is +passed as an input to the custom method that you provide. For example, +`byCommand('thing($it)')` results in calling a `thing` method to which the value matching the +JSON Path gets passed. The type of the object read from the JSON can be one of the +following, depending on the JSON path: +** `String`: If you point to a `String` value. +** `JSONArray`: If you point to a `List`. +** `Map`: If you point to a `Map`. +** `Number`: If you point to `Integer`, `Double`, or another kind of number. +** `Boolean`: If you point to a `Boolean`. +* `byNull()`: The value taken from the response in the provided JSON path must be null. + +[[yaml]] +=== YAML + +NOTE: See the Groovy section for a detailed explanation of +what the types mean. + +For YAML, the structure of a matcher resembles the following example: + +[source,yml,indent=0] +---- +- path: $.thing1 + type: by_regex + value: thing2 + regexType: as_string +---- + +Alternatively, if you want to use one of the predefined regular expressions +`[only_alpha_unicode, number, any_boolean, ip_address, hostname, +email, url, uuid, iso_date, iso_date_time, iso_time, iso_8601_with_offset, non_empty, +non_blank]`, you can use something similar to the following example: + +[source,yml,indent=0] +---- +- path: $.thing1 + type: by_regex + predefined: only_alpha_unicode +---- + +The following list shows the allowed list of `type` values: + +* For `stubMatchers`: +** `by_equality` +** `by_regex` +** `by_date` +** `by_timestamp` +** `by_time` +** `by_type` +*** Two additional fields (`minOccurrence` and `maxOccurrence`) are accepted. +* For `testMatchers`: +** `by_equality` +** `by_regex` +** `by_date` +** `by_timestamp` +** `by_time` +** `by_type` +*** Two additional fields (`minOccurrence` and `maxOccurrence`) are accepted. +** `by_command` +** `by_null` + +You can also define which type the regular expression corresponds to in the `regexType` +field. The following list shows the allowed regular expression types: + +* `as_integer` +* `as_double` +* `as_float` +* `as_long` +* `as_short` +* `as_boolean` +* `as_string` + +Consider the following example: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MockMvcMethodBodyBuilderWithMatchersSpec.groovy[tags=matchers,indent=0] +---- + +[source,yaml,indent=0,role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract_matchers.yml[indent=0] +---- +==== + +In the preceding example, you can see the dynamic portions of the contract in the +`matchers` sections. For the request part, you can see that, for all fields but +`valueWithoutAMatcher`, the values of the regular expressions that the stub should +contain are explicitly set. For `valueWithoutAMatcher`, the verification takes place +in the same way as without the use of matchers. In that case, the test performs an +equality check. + +For the response side in the `bodyMatchers` section, we define the dynamic parts in a +similar manner. The only difference is that the `byType` matchers are also present. The +verifier engine checks four fields to verify whether the response from the test +has a value for which the JSON path matches the given field, is of the same type as the one +defined in the response body, and passes the following check (based on the method being called): + +* For `$.valueWithTypeMatch`, the engine checks whether the type is the same. +* For `$.valueWithMin`, the engine checks the type and asserts whether the size is greater +than or equal to the minimum occurrence. +* For `$.valueWithMax`, the engine checks the type and asserts whether the size is +smaller than or equal to the maximum occurrence. +* For `$.valueWithMinMax`, the engine checks the type and asserts whether the size is +between the minimum and maximum occurrence. + +The resulting test resembles the following example (note that an `and` section +separates the autogenerated assertions and the assertion from matchers): + +[source,java,indent=0] +---- + // given: + MockMvcRequestSpecification request = given() + .header("Content-Type", "application/json") + .body("{\"duck\":123,\"alpha\":\"abc\",\"number\":123,\"aBoolean\":true,\"date\":\"2017-01-01\",\"dateTime\":\"2017-01-01T01:23:45\",\"time\":\"01:02:34\",\"valueWithoutAMatcher\":\"foo\",\"valueWithTypeMatch\":\"string\",\"key\":{\"complex.key\":\"foo\"}}"); + + // when: + ResponseOptions response = given().spec(request) + .get("/get"); + + // 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("['valueWithoutAMatcher']").isEqualTo("foo"); + // and: + assertThat(parsedJson.read("$.duck", String.class)).matches("[0-9]{3}"); + assertThat(parsedJson.read("$.duck", Integer.class)).isEqualTo(123); + assertThat(parsedJson.read("$.alpha", String.class)).matches("[\\p{L}]*"); + assertThat(parsedJson.read("$.alpha", String.class)).isEqualTo("abc"); + assertThat(parsedJson.read("$.number", String.class)).matches("-?(\\d*\\.\\d+|\\d+)"); + assertThat(parsedJson.read("$.aBoolean", String.class)).matches("(true|false)"); + assertThat(parsedJson.read("$.date", String.class)).matches("(\\d\\d\\d\\d)-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])"); + assertThat(parsedJson.read("$.dateTime", String.class)).matches("([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])"); + assertThat(parsedJson.read("$.time", String.class)).matches("(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])"); + assertThat((Object) parsedJson.read("$.valueWithTypeMatch")).isInstanceOf(java.lang.String.class); + assertThat((Object) parsedJson.read("$.valueWithMin")).isInstanceOf(java.util.List.class); + assertThat((java.lang.Iterable) parsedJson.read("$.valueWithMin", java.util.Collection.class)).as("$.valueWithMin").hasSizeGreaterThanOrEqualTo(1); + assertThat((Object) parsedJson.read("$.valueWithMax")).isInstanceOf(java.util.List.class); + assertThat((java.lang.Iterable) parsedJson.read("$.valueWithMax", java.util.Collection.class)).as("$.valueWithMax").hasSizeLessThanOrEqualTo(3); + assertThat((Object) parsedJson.read("$.valueWithMinMax")).isInstanceOf(java.util.List.class); + assertThat((java.lang.Iterable) parsedJson.read("$.valueWithMinMax", java.util.Collection.class)).as("$.valueWithMinMax").hasSizeBetween(1, 3); + assertThat((Object) parsedJson.read("$.valueWithMinEmpty")).isInstanceOf(java.util.List.class); + assertThat((java.lang.Iterable) parsedJson.read("$.valueWithMinEmpty", java.util.Collection.class)).as("$.valueWithMinEmpty").hasSizeGreaterThanOrEqualTo(0); + assertThat((Object) parsedJson.read("$.valueWithMaxEmpty")).isInstanceOf(java.util.List.class); + assertThat((java.lang.Iterable) parsedJson.read("$.valueWithMaxEmpty", java.util.Collection.class)).as("$.valueWithMaxEmpty").hasSizeLessThanOrEqualTo(0); + assertThatValueIsANumber(parsedJson.read("$.duck")); + assertThat(parsedJson.read("$.['key'].['complex.key']", String.class)).isEqualTo("foo"); +---- + +IMPORTANT: Notice that, for the `byCommand` method, the example calls the +`assertThatValueIsANumber`. This method must be defined in the test base class or be +statically imported to your tests. Notice that the `byCommand` call was converted to +`assertThatValueIsANumber(parsedJson.read("$.duck"));`. That means that the engine took +the method name and passed the proper JSON path as a parameter to it. + +The resulting WireMock stub is in the following example: + +[source,json,indent=0] +---- +include:../:{plugins_path}/spring-cloud-contract-converters/src/test/groovy/org/springframework/cloud/contract/verifier/wiremock/DslToWireMockClientConverterSpec.groovy[tags=matchers,indent=0] +---- + +IMPORTANT: If you use a `matcher`, the part of the request and response that the +`matcher` addresses with the JSON Path gets removed from the assertion. In the case of +verifying a collection, you must create matchers for *all* the elements of the +collection. + +Consider the following example: + +==== +[source,groovy,indent=0] +---- +Contract.make { + request { + method 'GET' + url("/foo") + } + response { + status OK() + body(events: [[ + operation : 'EXPORT', + eventId : '16f1ed75-0bcc-4f0d-a04d-3121798faf99', + status : 'OK' + ], [ + operation : 'INPUT_PROCESSING', + eventId : '3bb4ac82-6652-462f-b6d1-75e424a0024a', + status : 'OK' + ] + ] + ) + bodyMatchers { + jsonPath('$.events[0].operation', byRegex('.+')) + jsonPath('$.events[0].eventId', byRegex('^([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})$')) + jsonPath('$.events[0].status', byRegex('.+')) + } + } +} +---- +==== + +The preceding code leads to creating the following test (the code block shows only the assertion section): + +==== +[source,java,indent=0] +---- + and: + DocumentContext parsedJson = JsonPath.parse(response.body.asString()) + assertThatJson(parsedJson).array("['events']").contains("['eventId']").isEqualTo("16f1ed75-0bcc-4f0d-a04d-3121798faf99") + assertThatJson(parsedJson).array("['events']").contains("['operation']").isEqualTo("EXPORT") + assertThatJson(parsedJson).array("['events']").contains("['operation']").isEqualTo("INPUT_PROCESSING") + assertThatJson(parsedJson).array("['events']").contains("['eventId']").isEqualTo("3bb4ac82-6652-462f-b6d1-75e424a0024a") + assertThatJson(parsedJson).array("['events']").contains("['status']").isEqualTo("OK") + and: + assertThat(parsedJson.read("\$.events[0].operation", String.class)).matches(".+") + 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(".+") +---- +==== + +Note that the assertion is malformed. Only the first element of the array got +asserted. To fix this, apply the assertion to the whole `$.events` +collection and assert it with the `byCommand(...)` method. + diff --git a/docs/modules/ROOT/pages/_project-features-contract/dsl-http-top-level-elements.adoc b/docs/modules/ROOT/pages/_project-features-contract/dsl-http-top-level-elements.adoc new file mode 100644 index 0000000000..557f079f78 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-contract/dsl-http-top-level-elements.adoc @@ -0,0 +1,45 @@ +[[contract-dsl-http-top-level-elements]] += HTTP Top-Level Elements + +You can call the following methods in the top-level closure of a contract definition: + +* `request`: Mandatory +* `response` : Mandatory +* `priority`: Optional + +The following example shows how to define an HTTP request contract: + +==== +[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=http_dsl,indent=0] +---- + +[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=priority,indent=0] +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=request,indent=0] +... +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=response,indent=0] +... +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=http_dsl,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=http_dsl,indent=0] +---- +==== + +IMPORTANT: If you want to make your contract have a higher priority, +you need to pass a lower number to the `priority` tag or method. For example, a `priority` with +a value of `5` has higher priority than a `priority` with a value of `10`. + diff --git a/docs/modules/ROOT/pages/_project-features-contract/dsl-multiple.adoc b/docs/modules/ROOT/pages/_project-features-contract/dsl-multiple.adoc new file mode 100644 index 0000000000..e3d3f70ce2 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-contract/dsl-multiple.adoc @@ -0,0 +1,134 @@ +[[contract-dsl-multiple]] += Multiple Contracts in One File + +You can define multiple contracts in one file. Such a contract might resemble the +following example: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{plugins_path}/spring-cloud-contract-maven-plugin/src/test/projects/multiple-contracts/src/test/resources/contracts/com/hello/v1/WithList.groovy[lines=18..-1,indent=0] +---- + +[source,yaml,indent=0,role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/multiple_contracts.yml[indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +class contract implements Supplier> { + + @Override + public Collection get() { + return Arrays.asList( + Contract.make(c -> { + c.name("should post a user"); + // ... + }), Contract.make(c -> { + // ... + }), Contract.make(c -> { + // ... + }) + ); + } + +} +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract + +arrayOf( + contract { + name("should post a user") + // ... + }, + contract { + // ... + }, + contract { + // ... + } +} +---- +==== + +In the preceding example, one contract has the `name` field and the other does not. This +leads to generation of two tests that look like the following: + +==== +[source,java,indent=0] +---- +package org.springframework.cloud.contract.verifier.tests.com.hello; + +import com.example.TestBase; +import com.jayway.jsonpath.DocumentContext; +import com.jayway.jsonpath.JsonPath; +import com.jayway.restassured.module.mockmvc.specification.MockMvcRequestSpecification; +import com.jayway.restassured.response.ResponseOptions; +import org.junit.Test; + +import static com.jayway.restassured.module.mockmvc.RestAssuredMockMvc.*; +import static com.toomuchcoding.jsonassert.JsonAssertion.assertThatJson; +import static org.assertj.core.api.Assertions.assertThat; + +public class V1Test extends TestBase { + + @Test + public void validate_should_post_a_user() throws Exception { + // given: + MockMvcRequestSpecification request = given(); + + // when: + ResponseOptions response = given().spec(request) + .post("/users/1"); + + // then: + assertThat(response.statusCode()).isEqualTo(200); + } + + @Test + public void validate_withList_1() throws Exception { + // given: + MockMvcRequestSpecification request = given(); + + // when: + ResponseOptions response = given().spec(request) + .post("/users/2"); + + // then: + assertThat(response.statusCode()).isEqualTo(200); + } + +} +---- +==== + +Notice that, for the contract that has the `name` field, the generated test method is named +`validate_should_post_a_user`. The one that does not have the `name` field is called +`validate_withList_1`. It corresponds to the name of the file `WithList.groovy` and the +index of the contract in the list. + +The generated stubs are shown in the following example: + +==== +[source] +---- +should post a user.json +1_WithList.json +---- +==== + +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: It is much better to name your contracts, because doing so makes +your tests far more meaningful. + diff --git a/docs/modules/ROOT/pages/_project-features-contract/dsl-request.adoc b/docs/modules/ROOT/pages/_project-features-contract/dsl-request.adoc new file mode 100644 index 0000000000..906600ca8b --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-contract/dsl-request.adoc @@ -0,0 +1,271 @@ +[[contract-dsl-request]] += HTTP Request + +The HTTP protocol requires only the method and the URL to be specified in a request. The +same information is mandatory in request definition of the contract. + +The following example shows a contract for a request: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=request,indent=0] +---- + +[source,yaml,indent=0,role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=request_obligatory,indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=request,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=request,indent=0] +---- +==== + +You can specify an absolute rather than a relative `url`, but using `urlPath` is +the recommended way, as doing so makes the tests be host-independent. + +The following example uses `url`: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=url,indent=0] +---- + +[source,yaml,indent=0,role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract_rest_with_path.yml[tags=url_path,indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=url,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=url,indent=0] +---- +==== + +`request` may contain query parameters, as the following example (which uses `urlPath`) shows: + +==== +[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=urlpath,indent=0] +---- + +[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=request,indent=0] +... +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=query_params,indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=urlpath,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=urlpath,indent=0] +---- +==== + +`request` can contain additional request headers, as the following example shows: + +==== +[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=headers,indent=0] +---- + +[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=request,indent=0] +... +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=headers,indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=headers,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=headers,indent=0] +---- +==== + +`request` may contain additional request cookies, as the following example shows: + +==== +[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=cookies,indent=0] +---- + +[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=request,indent=0] +... +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=cookies,indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=cookies,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=cookies,indent=0] +---- +==== + +`request` may contain a request body, as the following example shows: + +==== +[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=body,indent=0] +---- + +[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=request,indent=0] +... +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=body,indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=body,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=body,indent=0] +---- +==== + +`request` can contain multipart elements. To include multipart elements, use the +`multipart` method/section, as the following examples show: + +==== +[source,groovy,indent=0,role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/SpringTestMethodBodyBuildersSpec.groovy[tags=multipartdsl,indent=0] +---- + +[source,yaml,indent=0,role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract_multipart.yml[indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_multipart.java[tags=class,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{verifier_core_path}/src/test/resources/kotlin/multipart.kts[tags=class,indent=0] +---- +==== + +In the preceding example, we defined parameters in either of two ways: + +.Coded DSL +* Directly, by using the map notation, where the value can be a dynamic property (such as +`formParameter: $(consumer(...), producer(...))`). +* By using the `named(...)` method that lets you set a named parameter. A named parameter +can set a `name` and `content`. You can call it either by using a method with two arguments, +such as `named("fileName", "fileContent")`, or by using a map notation, such as +`named(name: "fileName", content: "fileContent")`. + +.YAML +* The multipart parameters are set in the `multipart.params` section. +* The named parameters (the `fileName` and `fileContent` for a given parameter name) +can be set in the `multipart.named` section. That section contains +the `paramName` (the name of the parameter), `fileName` (the name of the file), +`fileContent` (the content of the file) fields. +* The dynamic bits can be set in the `matchers.multipart` section. +** For parameters, use the `params` section, which can accept +`regex` or a `predefined` regular expression. +** For named parameters, use the `named` section where you first +define the parameter name with `paramName`. Then you can pass the +parametrization of either `fileName` or `fileContent` in a +`regex` or in a `predefined` regular expression. + +IMPORTANT: For the `named(...)` section you always have to add a pair of +`value(producer(...), consumer(...))` calls. Just setting DSL properties such +as just `value(producer(...))` or just `file(...)` will not work. +Check this https://github.com/spring-cloud/spring-cloud-contract/issues/1886[issue] for more information. + +From the contract in the preceding example, the generated test and stub look as follows: + +==== +[source,java,indent=0,subs="verbatim,attributes",role="primary"] +.Test +---- +// given: + MockMvcRequestSpecification request = given() + .header("Content-Type", "multipart/form-data;boundary=AaB03x") + .param("formParameter", "\"formParameterValue\"") + .param("someBooleanParameter", "true") + .multiPart("file", "filename.csv", "file content".getBytes()); + + // when: + ResponseOptions response = given().spec(request) + .put("/multipart"); + + // then: + assertThat(response.statusCode()).isEqualTo(200); +---- + +[source,json,indent=0,subs="verbatim,attributes",role="secondary"] +.Stub +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/dsl/wiremock/WireMockGroovyDslSpec.groovy[tags=multipartwiremock,indent=0] +---- +==== + diff --git a/docs/modules/ROOT/pages/_project-features-contract/dsl-response.adoc b/docs/modules/ROOT/pages/_project-features-contract/dsl-response.adoc new file mode 100644 index 0000000000..ba72bfdc43 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-contract/dsl-response.adoc @@ -0,0 +1,41 @@ +[[contract-dsl-response]] += HTTP Response + +The response must contain an HTTP status code and may contain other information. The +following code shows an example: + +==== +[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=response,indent=0] +---- + +[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=response,indent=0] +... +include:../:{verifier_core_path}/src/test/resources/yml/contract.yml[tags=response_obligatory,indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_docs_examples.java[tags=response,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{verifier_core_path}/src/test/resources/kotlin/contract_docs_examples.kts[tags=response,indent=0] +---- +==== + +Besides status, the response may contain headers, cookies, and a body, which are +specified the same way as in the request (see <>). + +TIP: In the Groovy DSL, you can reference the `org.springframework.cloud.contract.spec.internal.HttpStatus` +methods to provide a meaningful status instead of a digit. For example, you can call +`OK()` for a status `200` or `BAD_REQUEST()` for `400`. + diff --git a/docs/modules/ROOT/pages/_project-features-contract/dsl-xml.adoc b/docs/modules/ROOT/pages/_project-features-contract/dsl-xml.adoc new file mode 100644 index 0000000000..4d8166088c --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-contract/dsl-xml.adoc @@ -0,0 +1,121 @@ +[[contract-dsl-xml]] += XML Support for HTTP + +For HTTP contracts, we also support using XML in the request and response body. +The XML body has to be passed within the `body` element +as a `String` or `GString`. Also, body matchers can be provided for +both the request and the response. In place of the `jsonPath(...)` method, the `org.springframework.cloud.contract.spec.internal.BodyMatchers.xPath` +method should be used, with the desired `xPath` provided as the first argument +and the appropriate `MatchingType` as the second argument. All the body matchers apart from `byType()` are supported. + +The following example shows a Groovy DSL contract with XML in the response body: + +==== +[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] +.Groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/XmlMethodBodyBuilderSpec.groovy[tags=xmlgroovy] +---- + +[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] +.YAML +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract_rest_xml.yml[indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Java +---- +include:../:{verifier_core_path}/src/test/resources/contractsToCompile/contract_xml.java[tags=class,indent=0] +---- + +[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"] +.Kotlin +---- +include:../:{verifier_core_path}/src/test/resources/kotlin/contract_xml.kts[tags=class,indent=0] +---- +==== + +The following example shows an automatically generated test for XML in the response body: + +==== +[source,java,indent=0] +---- +@Test +public void validate_xmlMatches() throws Exception { + // given: + MockMvcRequestSpecification request = given() + .header("Content-Type", "application/xml"); + + // when: + ResponseOptions response = given().spec(request).get("/get"); + + // then: + assertThat(response.statusCode()).isEqualTo(200); + // and: + DocumentBuilder documentBuilder = DocumentBuilderFactory.newInstance() + .newDocumentBuilder(); + Document parsedXml = documentBuilder.parse(new InputSource( + new StringReader(response.getBody().asString()))); + // and: + assertThat(valueFromXPath(parsedXml, "/test/list/elem/text()")).isEqualTo("abc"); + assertThat(valueFromXPath(parsedXml,"/test/list/elem[2]/text()")).isEqualTo("def"); + assertThat(valueFromXPath(parsedXml, "/test/duck/text()")).matches("[0-9]{3}"); + assertThat(nodeFromXPath(parsedXml, "/test/duck/xxx")).isNull(); + assertThat(valueFromXPath(parsedXml, "/test/alpha/text()")).matches("[\\p{L}]*"); + assertThat(valueFromXPath(parsedXml, "/test/*/complex/text()")).isEqualTo("foo"); + assertThat(valueFromXPath(parsedXml, "/test/duck/@type")).isEqualTo("xtype"); + } +---- +==== + +[[xml-support-for-namespaces]] +== XML Support for Namespaces +Namespaced XML is supported. However, any XPath expresssions used to select namespaced content must be updated. + +Consider the following explicitly namespaced XML document: + +[source,xml,indent=0] +---- + + customer@test.com + +---- +The XPath expression to select the email address is: `/ns1:customer/email/text()`. + +WARNING: Beware as the unqualified expression (`/customer/email/text()`) results in `""`. + +For content that uses an unqualified namespace, the expression is more verbose. Consider the following XML document that +uses an unqualified namespace: + +[source,xml,indent=0] +---- + + customer@test.com + +---- +The XPath expression to select the email address is +``` +*/[local-name()='customer' and namespace-uri()='http://demo.com/customer']/*[local-name()='email']/text() +``` +WARNING: Beware, as the unqualified expressions (`/customer/email/text()` or `*/[local-name()='customer' and namespace-uri()='http://demo.com/customer']/email/text()`) +result in `""`. Even the child elements have to be referenced with the `local-name` syntax. + +[[general-namespaced-node-expression-syntax]] +=== General Namespaced Node Expression Syntax +- Node using qualified namespace: +``` +/ +``` +- Node using and defining an unqualified namespace: +``` +/*[local-name=()='' and namespace-uri=()=''] +``` +NOTE: In some cases, you can omit the `namespace_uri` portion, but doing so may lead to ambiguity. + +- Node using an unqualified namespace (one of its ancestor's defines the xmlns attribute): +``` +/*[local-name=()=''] +``` + + diff --git a/docs/modules/ROOT/pages/_project-features-contract/groovy.adoc b/docs/modules/ROOT/pages/_project-features-contract/groovy.adoc new file mode 100644 index 0000000000..f68322470b --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-contract/groovy.adoc @@ -0,0 +1,17 @@ +[[contract-groovy]] += Contract DSL in Groovy + +If you are not familiar with Groovy, do not worry. You can use Java syntax in the +Groovy DSL files as well. + +If you decide to write the contract in Groovy, do not be alarmed if you have not used Groovy +before. Knowledge of the language is not really needed, as the Contract DSL uses only a +tiny subset of it (only literals, method calls, and closures). Also, the DSL is statically +typed, to make it programmer-readable without any knowledge of the DSL itself. + +IMPORTANT: Remember that, inside the Groovy 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 +`Contract.make { ... }`. + diff --git a/docs/modules/ROOT/pages/_project-features-contract/java.adoc b/docs/modules/ROOT/pages/_project-features-contract/java.adoc new file mode 100644 index 0000000000..fba47a5c12 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-contract/java.adoc @@ -0,0 +1,33 @@ +[[contract-java]] += Contract DSL in Java + +To write a contract definition in Java, you need to create a class that implements either the `Supplier` interface (for a single contract) or `Supplier>` (for multiple contracts). + +You can also write the contract definitions under `src/test/java` (for example, `src/test/java/contracts`) so that you do not have to modify the classpath of your project. In this case, you have to provide a new location of contract definitions to your Spring Cloud Contract plugin. + +The following example (in both Maven and Gradle) has the contract definitions under `src/test/java`: + +==== +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven +---- + + org.springframework.cloud + spring-cloud-contract-maven-plugin + ${spring-cloud-contract.version} + true + + src/test/java/contracts + + +---- + +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle +---- +contracts { + contractsDslDir = new File(project.rootDir, "src/test/java/contracts") +} +---- +==== + diff --git a/docs/modules/ROOT/pages/_project-features-contract/kotlin.adoc b/docs/modules/ROOT/pages/_project-features-contract/kotlin.adoc new file mode 100644 index 0000000000..5621cb7d0e --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-contract/kotlin.adoc @@ -0,0 +1,73 @@ +[[contract-kotlin]] += Contract DSL in Kotlin + +To get started with writing contracts in Kotlin, you need to start with a (newly created) Kotlin Script file (`.kts`). +As with the Java DSL, you can put your contracts in any directory of your choice. +By default, the Maven plugin will look at the `src/test/resources/contracts` directory and Gradle plugin will +look at the `src/contractTest/resources/contracts` directory. + +NOTE: Since 3.0.0, the Gradle plugin will also look at the legacy +directory `src/test/resources/contracts` for migration purposes. When contracts are found in this directory, a warning +will be logged during your build. + +You need to explicitly pass the `spring-cloud-contract-spec-kotlin` dependency to your project plugin setup. +The following example (in both Maven and Gradle) shows how to do so: + +==== +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven +---- + + org.springframework.cloud + spring-cloud-contract-maven-plugin + ${spring-cloud-contract.version} + true + + + + + + org.springframework.cloud + spring-cloud-contract-spec-kotlin + ${spring-cloud-contract.version} + + + + + + + + org.springframework.cloud + spring-cloud-contract-spec-kotlin + test + + +---- + +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle +---- +buildscript { + repositories { + // ... + } + dependencies { + classpath "org.springframework.cloud:spring-cloud-contract-gradle-plugin:${scContractVersion}" + } +} + +dependencies { + // ... + + // Remember to add this for the DSL support in the IDE and on the consumer side + testImplementation "org.springframework.cloud:spring-cloud-contract-spec-kotlin" + // Kotlin versions are very particular down to the patch version. The needs to be the same as you have imported for your project. + testImplementation "org.jetbrains.kotlin:kotlin-scripting-compiler-embeddable:" +} +---- +==== + +IMPORTANT: Remember that, inside the Kotlin Script file, you have to provide the fully qualified name to the `ContractDSL` class. +Generally you would use its contract function as follows: `org.springframework.cloud.contract.spec.ContractDsl.contract { ... }`. +You can also provide an import to the `contract` function (`import org.springframework.cloud.contract.spec.ContractDsl.Companion.contract`) and then call `contract { ... }`. + diff --git a/docs/modules/ROOT/pages/_project-features-contract/limitations.adoc b/docs/modules/ROOT/pages/_project-features-contract/limitations.adoc new file mode 100644 index 0000000000..947f1b6686 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-contract/limitations.adoc @@ -0,0 +1,12 @@ +[[contract-limitations]] += Limitations + +WARNING: The support for verifying the size of JSON arrays is experimental. If you want +to turn it on, 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 set 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 Groovy DSL and the `value(consumer(...), producer(...))` notation in `GString`. That +is why you should use the Groovy Map notation. + diff --git a/docs/modules/ROOT/pages/_project-features-contract/stateful-contracts.adoc b/docs/modules/ROOT/pages/_project-features-contract/stateful-contracts.adoc new file mode 100644 index 0000000000..c141a8b00b --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-contract/stateful-contracts.adoc @@ -0,0 +1,38 @@ +[[contract-stateful-contracts]] += Stateful Contracts + +Stateful contracts (also known as scenarios) are contract definitions that should be read +in order. This might be useful in the following situations: + +* You want to invoke the contract in a precisely defined order, since you use Spring +Cloud Contract to test your stateful application. + +TIP: We really discourage you from doing that, since contract tests should be stateless. + +* You want the same endpoint to return different results for the same request. + +To create stateful contracts (or scenarios), you need to +use the proper naming convention while creating your contracts. The convention +requires including an order number followed by an underscore. This works regardless +of whether you work with YAML or Groovy. The following listing shows an example: + +==== +[source,indent=0] +---- +my_contracts_dir\ + scenario1\ + 1_login.groovy + 2_showCart.groovy + 3_logout.groovy +---- +==== + +Such a tree causes Spring Cloud Contract Verifier to generate WireMock's scenario with a +name of `scenario1` and the three following steps: + +. `login`, marked as `Started` pointing to... +. `showCart`, marked as `Step1` pointing to... +. `logout`, marked as `Step2` (which closes the scenario). + +You can find more details about WireMock scenarios at +https://wiremock.org/docs/stateful-behaviour/[https://wiremock.org/docs/stateful-behaviour/]. diff --git a/docs/modules/ROOT/pages/_project-features-contract/yml.adoc b/docs/modules/ROOT/pages/_project-features-contract/yml.adoc new file mode 100644 index 0000000000..64e8309622 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-contract/yml.adoc @@ -0,0 +1,5 @@ +[[contract-yml]] += Contract DSL in YAML + +To see a schema of a YAML contract, visit the {docs-url}/reference/html/yml-schema.html[YML Schema] page. + diff --git a/docs/modules/ROOT/pages/_project-features-flows.adoc b/docs/modules/ROOT/pages/_project-features-flows.adoc index 43ff0cda60..0c95a05328 100644 --- a/docs/modules/ROOT/pages/_project-features-flows.adoc +++ b/docs/modules/ROOT/pages/_project-features-flows.adoc @@ -3,1063 +3,3 @@ include::_attributes.adoc[] -[[features-jax-rs]] -== JAX-RS - -The Spring Cloud Contract 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 be set. Otherwise, the default of `application/octet-stream` gets used. - -To use JAX-RS mode, use the following setting: - -==== -[source,groovy,indent=0] ----- -testMode = 'JAXRSCLIENT' ----- -==== - -The following example shows a generated test API: - -==== -[source,groovy,indent=0] ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/JaxRsClientMethodBuilderSpec.groovy[tags=jaxrs,indent=0] ----- -==== - -[[feature-webflux]] -== WebFlux with WebTestClient - -You can work with WebFlux by using WebTestClient. The following listing shows how to -configure WebTestClient as the test mode: - -==== -[source,xml,indent=0,subs="verbatim,attributes",role="primary"] -.Maven ----- - - org.springframework.cloud - spring-cloud-contract-maven-plugin - ${spring-cloud-contract.version} - true - - WEBTESTCLIENT - - ----- - -[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] -.Gradle ----- -contracts { - testMode = 'WEBTESTCLIENT' -} ----- -==== - -The following example shows how to set up a WebTestClient base class and RestAssured -for WebFlux: - -==== -[source,groovy,indent=0] ----- -import io.restassured.module.webtestclient.RestAssuredWebTestClient; -import org.junit.Before; - -public abstract class BeerRestBase { - - @Before - public void setup() { - RestAssuredWebTestClient.standaloneSetup( - new ProducerController(personToCheck -> personToCheck.age >= 20)); - } -} -} ----- -==== - -TIP: The `WebTestClient` mode is faster than the `EXPLICIT` mode. - -[[feature-webflux-explicit]] -== WebFlux with Explicit Mode - -You can also use WebFlux with the explicit mode in your generated tests -to work with WebFlux. The following example shows how to configure using explicit mode: - -==== -[source,xml,indent=0,subs="verbatim,attributes",role="primary"] -.Maven ----- - - org.springframework.cloud - spring-cloud-contract-maven-plugin - ${spring-cloud-contract.version} - true - - EXPLICIT - - ----- - -[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] -.Gradle ----- -contracts { - testMode = 'EXPLICIT' -} ----- -==== - -The following example shows how to set up a base class and RestAssured for Web Flux: - -==== -[source,groovy,indent=0] ----- -include::{samples_url}/producer_webflux/src/test/java/com/example/BeerRestBase.java[tags=annotations,indent=0] - - // your tests go here - - // in this config class you define all controllers and mocked services -include::{samples_url}/producer_webflux/src/test/java/com/example/BeerRestBase.java[tags=config,indent=0] - -} ----- -==== - -[[features-custom-mode]] -== Custom Mode - -IMPORTANT: This mode is experimental and can change in the future. - -The Spring Cloud Contract lets you provide your own, custom, implementation of the -`org.springframework.cloud.contract.verifier.http.HttpVerifier`. That way, you can use any client you want to send and receive a request. The default implementation in Spring Cloud Contract is `OkHttpHttpVerifier` and it uses OkHttp3 http client. - -To get started, set `testMode` to `CUSTOM`: - -==== -[source,groovy,indent=0] ----- -testMode = 'CUSTOM' ----- -==== - -The following example shows a generated test: - -==== -[source,java,indent=0] ----- -package com.example.beer; - -import com.example.BeerRestBase; -import javax.inject.Inject; -import org.springframework.cloud.contract.verifier.http.HttpVerifier; -import org.springframework.cloud.contract.verifier.http.Request; -import org.springframework.cloud.contract.verifier.http.Response; -import org.junit.jupiter.api.Test; -import org.junit.jupiter.api.extension.ExtendWith; - -import static org.springframework.cloud.contract.verifier.assertion.SpringCloudContractAssertions.assertThat; -import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.*; -import static org.springframework.cloud.contract.verifier.http.Request.given; - -@SuppressWarnings("rawtypes") -public class RestTest extends BeerRestBase { - @Inject HttpVerifier httpVerifier; - - @Test - public void validate_shouldGrantABeerIfOldEnough() throws Exception { - // given: - Request request = given() - .post("/beer.BeerService/check") - .scheme("HTTP") - .protocol("h2_prior_knowledge") - .header("Content-Type", "application/grpc") - .header("te", "trailers") - .body(fileToBytes(this, "shouldGrantABeerIfOldEnough_request_PersonToCheck_old_enough.bin")) - .build(); - - - // when: - Response response = httpVerifier.exchange(request); - - - // then: - assertThat(response.statusCode()).isEqualTo(200); - assertThat(response.header("Content-Type")).matches("application/grpc.*"); - assertThat(response.header("grpc-encoding")).isEqualTo("identity"); - assertThat(response.header("grpc-accept-encoding")).isEqualTo("gzip"); - - // and: - assertThat(response.getBody().asByteArray()).isEqualTo(fileToBytes(this, "shouldGrantABeerIfOldEnough_response_Response_old_enough.bin")); - } - -} ----- -==== - -The following example shows a corresponding base class: - -==== -[source,java,indent=0] ----- -@SpringBootTest(classes = BeerRestBase.Config.class, - webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) -public abstract class BeerRestBase { - - @Configuration - @EnableAutoConfiguration - static class Config { - - @Bean - ProducerController producerController(PersonCheckingService personCheckingService) { - return new ProducerController(personCheckingService); - } - - @Bean - PersonCheckingService testPersonCheckingService() { - return argument -> argument.getAge() >= 20; - } - - @Bean - HttpVerifier httpOkVerifier(@LocalServerPort int port) { - return new OkHttpHttpVerifier("localhost:" + port); - } - - } -} ----- -==== - -[[features-context-paths]] -== 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. The following example shows how to set the test mode to `EXPLICIT`: - -==== -[source,xml,indent=0,subs="verbatim,attributes",role="primary"] -.Maven ----- - - org.springframework.cloud - spring-cloud-contract-maven-plugin - ${spring-cloud-contract.version} - true - - EXPLICIT - - ----- - -[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] -.Gradle ----- -contracts { - testMode = 'EXPLICIT' -} ----- -==== -===== - -That way, you generate a test that does not use MockMvc. It means that you generate -real requests and you need to set up your generated test's base class to work on a real -socket. - -Consider the following contract: - -[source,groovy,indent=0] ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/SingleTestGeneratorSpec.groovy[tags=context_path_contract,indent=0] ----- - -The following example shows how to set up a base class and RestAssured: - -[source,groovy,indent=0] ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/SingleTestGeneratorSpec.groovy[tags=context_path_baseclass,indent=0] ----- - -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`). - -[[features-rest-docs]] -== Working with REST Docs - -You can use https://projects.spring.io/spring-restdocs[Spring REST Docs] to generate -documentation (for example, in Asciidoc format) for an HTTP API with Spring MockMvc, -WebTestClient, or RestAssured. 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 UML diagram shows -the REST Docs flow: - -[plantuml, rest-docs, png] ----- -"API Producer"->"API Producer": Add Spring Cloud Contract (SCC) \nStub Runner dependency -"API Producer"->"API Producer": Set up stub jar assembly -"API Producer"->"API Producer": Write and set up REST Docs tests -"API Producer"->"Build": Run build -"Build"->"REST Docs": Generate API \ndocumentation -"REST Docs"->"SCC": Generate stubs from the \nREST Docs tests -"REST Docs"->"SCC": Generate contracts from the \nREST Docs tests -"Build"->"Build": Assemble stubs jar with \nstubs and contracts -"Build"->"Nexus / Artifactory": Upload contracts \nand stubs and the project arifact -"Build"->"API Producer": Build successful -"API Consumer"->"API Consumer": Add SCC Stub Runner \ndependency -"API Consumer"->"API Consumer": Write a SCC Stub Runner \nbased contract test -"SCC Stub Runner"->"Nexus / Artifactory": Test asks for [API Producer] stubs -"Nexus / Artifactory"->"SCC Stub Runner": Fetch the [API Producer] stubs -"SCC Stub Runner"->"SCC Stub Runner": Run in memory\n HTTP server stubs -"API Consumer"->"SCC Stub Runner": Send a request \nto the HTTP server stub -"SCC Stub Runner"->"API Consumer": Communication is correct ----- - -The following example uses `MockMvc`: - -==== -[source,java,indent=0] ----- -@RunWith(SpringRunner.class) -@SpringBootTest -@AutoConfigureRestDocs(outputDir = "target/snippets") -@AutoConfigureMockMvc -public class ApplicationTests { - - @Autowired - private MockMvc mockMvc; - - @Test - public void contextLoads() throws Exception { - mockMvc.perform(get("/resource")) - .andExpect(content().string("Hello World")) - .andDo(document("resource")); - } -} ----- -==== - -This test generates a WireMock stub at `target/snippets/stubs/resource.json`. It matches -all `GET` requests to the `/resource` path. The same example with WebTestClient (used -for testing Spring WebFlux applications) would be as follows: - -==== -[source,java,indent=0] ----- -@RunWith(SpringRunner.class) -@SpringBootTest -@AutoConfigureRestDocs(outputDir = "target/snippets") -@AutoConfigureWebTestClient -public class ApplicationTests { - - @Autowired - private WebTestClient client; - - @Test - public void contextLoads() throws Exception { - client.get().uri("/resource").exchange() - .expectBody(String.class).isEqualTo("Hello World") - .consumeWith(document("resource")); - } -} ----- -==== - -Without any additional configuration, these tests create a stub with a request matcher -for the HTTP method and all headers except `host` and `content-length`. To match the -request more precisely (for example, to match the body of a POST or PUT), we need to -explicitly create a request matcher. Doing so has two effects: - -* Creating a stub that matches only in the way you specify. -* Asserting that the request in the test case also matches the same conditions. - -The main entry point for this feature is `WireMockRestDocs.verify()`, which can be used -as a substitute for the `document()` convenience method, as the following -example shows: - -==== -[source,java,indent=0] ----- -import static org.springframework.cloud.contract.wiremock.restdocs.WireMockRestDocs.verify; - -@RunWith(SpringRunner.class) -@SpringBootTest -@AutoConfigureRestDocs(outputDir = "target/snippets") -@AutoConfigureMockMvc -public class ApplicationTests { - - @Autowired - private MockMvc mockMvc; - - @Test - public void contextLoads() throws Exception { - mockMvc.perform(post("/resource") - .content("{\"id\":\"123456\",\"message\":\"Hello World\"}")) - .andExpect(status().isOk()) - .andDo(verify().jsonPath("$.id")) - .andDo(document("resource")); - } -} ----- -==== - -The preceding contract specifies that any valid POST with an `id` field receives the response -defined in this test. You can chain together calls to `.jsonPath()` to add additional -matchers. If JSON Path is unfamiliar, the https://github.com/jayway/JsonPath[JayWay -documentation] can help you get up to speed. The WebTestClient version of this test -has a similar `verify()` static helper that you insert in the same place. - -Instead of the `jsonPath` and `contentType` convenience methods, you can also use the -WireMock APIs to verify that the request matches the created stub, as the -following example shows: - -==== -[source,java,indent=0] ----- - @Test - public void contextLoads() throws Exception { - mockMvc.perform(post("/resource") - .content("{\"id\":\"123456\",\"message\":\"Hello World\"}")) - .andExpect(status().isOk()) - .andDo(verify() - .wiremock(WireMock.post(urlPathEquals("/resource")) - .withRequestBody(matchingJsonPath("$.id")) - .andDo(document("post-resource")))); - } ----- -==== - -The WireMock API is rich. You can match headers, query parameters, and the request body by -regex as well as by JSON path. You can use these features to create stubs with a wider -range of parameters. The preceding example generates a stub resembling the following example: - -==== -.post-resource.json -[source,json] ----- -{ - "request" : { - "url" : "/resource", - "method" : "POST", - "bodyPatterns" : [ { - "matchesJsonPath" : "$.id" - }] - }, - "response" : { - "status" : 200, - "body" : "Hello World", - "headers" : { - "X-Application-Context" : "application:-1", - "Content-Type" : "text/plain" - } - } -} ----- -==== - -NOTE: You can use either the `wiremock()` method or the `jsonPath()` and `contentType()` -methods to create request matchers, but you cannot use both approaches. - -On the consumer side, you can make the `resource.json` generated earlier in this section -available on the classpath (by -<>, for example). After that, you can create a stub that uses WireMock in a -number of different ways, including by using -`@AutoConfigureWireMock(stubs="classpath:resource.json")`, as described earlier in this -document. - -[[features-rest-docs-contracts]] -=== Generating Contracts with REST Docs - -You can also generate Spring Cloud Contract DSL files and documentation with Spring REST -Docs. If you do so in combination with Spring Cloud WireMock, you get both the contracts -and the stubs. - -Why would you want to use this feature? Some people in the community asked questions -about a situation in which they would like to move to DSL-based contract definition, -but they already have a lot of Spring MVC tests. Using this feature lets you generate -the contract files that you can later modify and move to folders (defined in your -configuration) so that the plugin finds them. - -NOTE: You might wonder why this functionality is in the WireMock module. The functionality -is there because it makes sense to generate both the contracts and the stubs. - -Consider the following test: - -==== -[source,java] ----- -include::{wiremock_tests}/src/test/java/org/springframework/cloud/contract/wiremock/restdocs/ContractDslSnippetTests.java[tags=contract_snippet] ----- -==== - -The preceding test creates the stub presented in the previous section, generating both -the contract and a documentation file. - -The contract is called `index.groovy` and might resemble the following example: - -==== -[source,groovy] ----- -import org.springframework.cloud.contract.spec.Contract - -Contract.make { - request { - method 'POST' - url '/foo' - body(''' - {"foo": 23 } - ''') - headers { - header('''Accept''', '''application/json''') - header('''Content-Type''', '''application/json''') - } - } - response { - status OK() - body(''' - bar - ''') - headers { - header('''Content-Type''', '''application/json;charset=UTF-8''') - header('''Content-Length''', '''3''') - } - bodyMatchers { - jsonPath('$[?(@.foo >= 20)]', byType()) - } - } -} ----- -==== - -The generated document (formatted in Asciidoc in this case) contains a formatted -contract. The location of this file would be `index/dsl-contract.adoc`. - -[[features-restdocs-priority-attribute]] -=== Specifying the priority attribute - -The method `SpringCloudContractRestDocs.dslContract()` takes an optional Map parameter that allows you to specify additional attributes in the template. - -One of these attributes is the <> field that you may specify as follows: - -[source,java,indent=0] ----- -SpringCloudContractRestDocs.dslContract(Map.of("priority", 1)) ----- - -[[features-restdocs-override]] -=== Overriding the DSL contract template - -By default, the output of the contract is based on a file named `default-dsl-contract-only.snippet`. - -You may provide a custom template file instead by overriding the getTemplate() method as follows: - -[source,java,indent=0] ----- -new ContractDslSnippet(){ - @Override - protected String getTemplate() { - return "custom-dsl-contract"; - } -})); ----- - -so the example above showing this line -[source,java,indent=0] ----- -.andDo(document("index", SpringCloudContractRestDocs.dslContract())); ----- - -should be changed to: -[source,java,indent=0] ----- -.andDo(document("index", new ContractDslSnippet(){ - @Override - protected String getTemplate() { - return "custom-dsl-template"; - } - })); ----- - -Templates are resolved by looking for resources on the classpath. The following locations are checked in order: - -* `org/springframework/restdocs/templates/${templateFormatId}/${name}.snippet` -* `org/springframework/restdocs/templates/${name}.snippet` -* `org/springframework/restdocs/templates/${templateFormatId}/default-${name}.snippet` - -Therefore in the example above you should place a file named custom-dsl-template.snippet in `src/test/resources/org/springframework/restdocs/templates/custom-dsl-template.snippet` - - - -[[features-graphql]] -== GraphQL - -Since https://graphql.org/[GraphQL] is essentially HTTP you can write a contract for it by creating a standard HTTP contract with an additional `metadata` entry with key `verifier` and a mapping `tool=graphql`. - -==== -[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] -.Groovy ----- -import org.springframework.cloud.contract.spec.Contract - -Contract.make { - - request { - method(POST()) - url("/graphql") - headers { - contentType("application/json") - } - body(''' -{ - "query":"query queryName($personName: String!) {\\n personToCheck(name: $personName) {\\n name\\n age\\n }\\n}\\n\\n\\n\\n", - "variables":{"personName":"Old Enough"}, - "operationName":"queryName" -} -''') - } - - response { - status(200) - headers { - contentType("application/json") - } - body('''\ -{ - "data": { - "personToCheck": { - "name": "Old Enough", - "age": "40" - } - } -} -''') - } - metadata(verifier: [ - tool: "graphql" - ]) -} ----- - -[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] -.YAML ----- ---- -request: - method: "POST" - url: "/graphql" - headers: - Content-Type: "application/json" - body: - query: "query queryName($personName: String!) { personToCheck(name: $personName) - { name age } }" - variables: - personName: "Old Enough" - operationName: "queryName" - matchers: - headers: - - key: "Content-Type" - regex: "application/json.*" - regexType: "as_string" -response: - status: 200 - headers: - Content-Type: "application/json" - body: - data: - personToCheck: - name: "Old Enough" - age: "40" - matchers: - headers: - - key: "Content-Type" - regex: "application/json.*" - regexType: "as_string" -name: "shouldRetrieveOldEnoughPerson" -metadata: - verifier: - tool: "graphql" ----- -==== - -Adding the metadata section will change the way the default, WireMock stub is built. It will now use the Spring Cloud Contract request matcher, so that e.g. the `query` part of the GraphQL request gets compared against the real request by ignoring whitespaces. - -[[features-graphql-producer]] -=== Producer Side Setup - -On the producer side your configuration can look as follows. - -==== -[source,xml,indent=0,subs="verbatim,attributes",role="primary"] -.Maven ----- - - org.springframework.cloud - spring-cloud-contract-maven-plugin - ${spring-cloud-contract.version} - true - - EXPLICIT - com.example.BaseClass - - ----- - -[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] -.Gradle ----- -contracts { - testMode = "EXPLICIT" - baseClassForTests = "com.example.BaseClass" -} ----- -==== - -The base class would set up the application running on a random port. - -==== -[source,java,indent=0,subs="verbatim,attributes"] -.Base Class ----- -@SpringBootTest(classes = ProducerApplication.class, - properties = "graphql.servlet.websocket.enabled=false", - webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) -public abstract class BaseClass { - - @LocalServerPort int port; - - @BeforeEach - public void setup() { - RestAssured.baseURI = "http://localhost:" + port; - } -} - ----- -==== - -[[features-graphql-consumer]] -=== Consumer Side Setup - -Example of a consumer side test of the GraphQL API. - -==== -[source,java,indent=0,subs="verbatim,attributes"] -.Consumer Side Test ----- -@SpringBootTest(webEnvironment = WebEnvironment.NONE) -public class BeerControllerGraphQLTest { - - @RegisterExtension - static StubRunnerExtension rule = new StubRunnerExtension() - .downloadStub("com.example","beer-api-producer-graphql") - .stubsMode(StubRunnerProperties.StubsMode.LOCAL); - - private static final String REQUEST_BODY = "{\n" - + "\"query\":\"query queryName($personName: String!) {\\n personToCheck(name: $personName) {\\n name\\n age\\n }\\n}\"," - + "\"variables\":{\"personName\":\"Old Enough\"},\n" - + "\"operationName\":\"queryName\"\n" - + "}"; - - @Test - public void should_send_a_graphql_request() { - ResponseEntity responseEntity = new RestTemplate() - .exchange(RequestEntity - .post(URI.create("http://localhost:" + rule.findStubUrl("beer-api-producer-graphql").getPort() + "/graphql")) - .contentType(MediaType.APPLICATION_JSON) - .body(REQUEST_BODY), String.class); - - BDDAssertions.then(responseEntity.getStatusCodeValue()).isEqualTo(200); - - } -} - ----- -==== - -[[features-grpc]] -== GRPC - -https://grpc.io/[GRPC] is an RPC framework built on top of HTTP/2 for which Spring Cloud Contract has basic support. - -IMPORTANT: Spring Cloud Contract has an experimental support for basic use cases of GRPC. Unfortunately, due to GRPC's tweaking of the HTTP/2 Header frames, it's impossible to assert the `grpc-status` header. - -Let's look at the following contract. - -==== -[source,groovy,indent=0,subs="verbatim,attributes"] -.Groovy contract ----- -package contracts.beer.rest - - -import org.springframework.cloud.contract.spec.Contract -import org.springframework.cloud.contract.verifier.http.ContractVerifierHttpMetaData - -Contract.make { - description(""" -Represents a successful scenario of getting a beer - -``` -given: - client is old enough -when: - he applies for a beer -then: - we'll grant him the beer -``` - -""") - request { - method 'POST' - url '/beer.BeerService/check' - body(fileAsBytes("PersonToCheck_old_enough.bin")) - headers { - contentType("application/grpc") - header("te", "trailers") - } - } - response { - status 200 - body(fileAsBytes("Response_old_enough.bin")) - headers { - contentType("application/grpc") - header("grpc-encoding", "identity") - header("grpc-accept-encoding", "gzip") - } - } - metadata([ - "verifierHttp": [ - "protocol": ContractVerifierHttpMetaData.Protocol.H2_PRIOR_KNOWLEDGE.toString() - ] - ]) -} ----- -==== - -[[features-grpc-producer]] -=== Producer Side Setup - -In order to leverage the HTTP/2 support you must set the `CUSTOM` test mode as follow. - -==== -[source,xml,indent=0,subs="verbatim,attributes",role="primary"] -.Maven ----- - - org.springframework.cloud - spring-cloud-contract-maven-plugin - ${spring-cloud-contract.version} - true - - CUSTOM - com.example - - ----- - -[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] -.Gradle ----- -contracts { - packageWithBaseClasses = 'com.example' - testMode = "CUSTOM" -} ----- -==== - -The base class would set up the application running on a random port. It will also set the `HttpVerifier` implementation to one that can use the HTTP/2 protocol. Spring Cloud Contract comes with the `OkHttpHttpVerifier` implementation. - -==== -[source,java,indent=0,subs="verbatim,attributes"] -.Base Class ----- -@SpringBootTest(classes = BeerRestBase.Config.class, - webEnvironment = SpringBootTest.WebEnvironment.NONE, - properties = { - "grpc.server.port=0" - }) -public abstract class BeerRestBase { - - @Autowired - GrpcServerProperties properties; - - @Configuration - @EnableAutoConfiguration - static class Config { - - @Bean - ProducerController producerController(PersonCheckingService personCheckingService) { - return new ProducerController(personCheckingService); - } - - @Bean - PersonCheckingService testPersonCheckingService() { - return argument -> argument.getAge() >= 20; - } - - @Bean - HttpVerifier httpOkVerifier(GrpcServerProperties properties) { - return new OkHttpHttpVerifier("localhost:" + properties.getPort()); - } - - } -} ----- -==== - -[[features-grpc-consumer]] -=== Consumer Side Setup - -Example of GRPC consumer side test. Due to the unusual behaviour of the GRPC server side, the stub is unable to return the `grpc-status` header in the proper moment. This is why we need to manually set the return status. - -==== -[source,java,indent=0,subs="verbatim,attributes"] -.Consumer Side Test ----- -@SpringBootTest(webEnvironment = WebEnvironment.NONE, classes = GrpcTests.TestConfiguration.class, properties = { - "grpc.client.beerService.address=static://localhost:5432", "grpc.client.beerService.negotiationType=TLS" -}) -public class GrpcTests { - - @GrpcClient(value = "beerService", interceptorNames = "fixedStatusSendingClientInterceptor") - BeerServiceGrpc.BeerServiceBlockingStub beerServiceBlockingStub; - - int port; - - @RegisterExtension - static StubRunnerExtension rule = new StubRunnerExtension() - .downloadStub("com.example", "beer-api-producer-grpc") - // With WireMock PlainText mode you can just set an HTTP port -// .withPort(5432) - .stubsMode(StubRunnerProperties.StubsMode.LOCAL) - .withHttpServerStubConfigurer(MyWireMockConfigurer.class); - - @BeforeEach - public void setupPort() { - this.port = rule.findStubUrl("beer-api-producer-grpc").getPort(); - } - - @Test - public void should_give_me_a_beer_when_im_old_enough() throws Exception { - Response response = beerServiceBlockingStub.check(PersonToCheck.newBuilder().setAge(23).build()); - - BDDAssertions.then(response.getStatus()).isEqualTo(Response.BeerCheckStatus.OK); - } - - @Test - public void should_reject_a_beer_when_im_too_young() throws Exception { - Response response = beerServiceBlockingStub.check(PersonToCheck.newBuilder().setAge(17).build()); - response = response == null ? Response.newBuilder().build() : response; - - BDDAssertions.then(response.getStatus()).isEqualTo(Response.BeerCheckStatus.NOT_OK); - } - - // Not necessary with WireMock PlainText mode - static class MyWireMockConfigurer extends WireMockHttpServerStubConfigurer { - @Override - public WireMockConfiguration configure(WireMockConfiguration httpStubConfiguration, HttpServerStubConfiguration httpServerStubConfiguration) { - return httpStubConfiguration - .httpsPort(5432); - } - } - - @Configuration - @ImportAutoConfiguration(GrpcClientAutoConfiguration.class) - static class TestConfiguration { - - // Not necessary with WireMock PlainText mode - @Bean - public GrpcChannelConfigurer keepAliveClientConfigurer() { - return (channelBuilder, name) -> { - if (channelBuilder instanceof NettyChannelBuilder) { - try { - ((NettyChannelBuilder) channelBuilder) - .sslContext(GrpcSslContexts.forClient() - .trustManager(InsecureTrustManagerFactory.INSTANCE) - .build()); - } - catch (SSLException e) { - throw new IllegalStateException(e); - } - } - }; - } - - /** - * GRPC client interceptor that sets the returned status always to OK. - * You might want to change the return status depending on the received stub payload. - * - * Hopefully in the future this will be unnecessary and will be removed. - */ - @Bean - ClientInterceptor fixedStatusSendingClientInterceptor() { - return new ClientInterceptor() { - @Override - public ClientCall interceptCall(MethodDescriptor method, CallOptions callOptions, Channel next) { - ClientCall call = next.newCall(method, callOptions); - return new ClientCall() { - @Override - public void start(Listener responseListener, Metadata headers) { - Listener listener = new Listener() { - @Override - public void onHeaders(Metadata headers) { - responseListener.onHeaders(headers); - } - - @Override - public void onMessage(RespT message) { - responseListener.onMessage(message); - } - - @Override - public void onClose(Status status, Metadata trailers) { - // TODO: This must be fixed somehow either in Jetty (WireMock) or somewhere else - responseListener.onClose(Status.OK, trailers); - } - - @Override - public void onReady() { - responseListener.onReady(); - } - }; - call.start(listener, headers); - } - - @Override - public void request(int numMessages) { - call.request(numMessages); - } - - @Override - public void cancel(@Nullable String message, @Nullable Throwable cause) { - call.cancel(message, cause); - } - - @Override - public void halfClose() { - call.halfClose(); - } - - @Override - public void sendMessage(ReqT message) { - call.sendMessage(message); - } - }; - } - }; - } - } -} - ----- -==== diff --git a/docs/modules/ROOT/pages/_project-features-flows/context-paths.adoc b/docs/modules/ROOT/pages/_project-features-flows/context-paths.adoc new file mode 100644 index 0000000000..8f806362d6 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-flows/context-paths.adoc @@ -0,0 +1,62 @@ +[[features-context-paths]] += 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. The following example shows how to set the test mode to `EXPLICIT`: + +==== +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven +---- + + org.springframework.cloud + spring-cloud-contract-maven-plugin + ${spring-cloud-contract.version} + true + + EXPLICIT + + +---- + +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle +---- +contracts { + testMode = 'EXPLICIT' +} +---- +==== +===== + +That way, you generate a test that does not use MockMvc. It means that you generate +real requests and you need to set up your generated test's base class to work on a real +socket. + +Consider the following contract: + +[source,groovy,indent=0] +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/SingleTestGeneratorSpec.groovy[tags=context_path_contract,indent=0] +---- + +The following example shows how to set up a base class and RestAssured: + +[source,groovy,indent=0] +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/SingleTestGeneratorSpec.groovy[tags=context_path_baseclass,indent=0] +---- + +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`). + diff --git a/docs/modules/ROOT/pages/_project-features-flows/custom-mode.adoc b/docs/modules/ROOT/pages/_project-features-flows/custom-mode.adoc new file mode 100644 index 0000000000..5258dd6741 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-flows/custom-mode.adoc @@ -0,0 +1,104 @@ +[[features-custom-mode]] += Custom Mode + +IMPORTANT: This mode is experimental and can change in the future. + +The Spring Cloud Contract lets you provide your own, custom, implementation of the +`org.springframework.cloud.contract.verifier.http.HttpVerifier`. That way, you can use any client you want to send and receive a request. The default implementation in Spring Cloud Contract is `OkHttpHttpVerifier` and it uses OkHttp3 http client. + +To get started, set `testMode` to `CUSTOM`: + +==== +[source,groovy,indent=0] +---- +testMode = 'CUSTOM' +---- +==== + +The following example shows a generated test: + +==== +[source,java,indent=0] +---- +package com.example.beer; + +import com.example.BeerRestBase; +import javax.inject.Inject; +import org.springframework.cloud.contract.verifier.http.HttpVerifier; +import org.springframework.cloud.contract.verifier.http.Request; +import org.springframework.cloud.contract.verifier.http.Response; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; + +import static org.springframework.cloud.contract.verifier.assertion.SpringCloudContractAssertions.assertThat; +import static org.springframework.cloud.contract.verifier.util.ContractVerifierUtil.*; +import static org.springframework.cloud.contract.verifier.http.Request.given; + +@SuppressWarnings("rawtypes") +public class RestTest extends BeerRestBase { + @Inject HttpVerifier httpVerifier; + + @Test + public void validate_shouldGrantABeerIfOldEnough() throws Exception { + // given: + Request request = given() + .post("/beer.BeerService/check") + .scheme("HTTP") + .protocol("h2_prior_knowledge") + .header("Content-Type", "application/grpc") + .header("te", "trailers") + .body(fileToBytes(this, "shouldGrantABeerIfOldEnough_request_PersonToCheck_old_enough.bin")) + .build(); + + + // when: + Response response = httpVerifier.exchange(request); + + + // then: + assertThat(response.statusCode()).isEqualTo(200); + assertThat(response.header("Content-Type")).matches("application/grpc.*"); + assertThat(response.header("grpc-encoding")).isEqualTo("identity"); + assertThat(response.header("grpc-accept-encoding")).isEqualTo("gzip"); + + // and: + assertThat(response.getBody().asByteArray()).isEqualTo(fileToBytes(this, "shouldGrantABeerIfOldEnough_response_Response_old_enough.bin")); + } + +} +---- +==== + +The following example shows a corresponding base class: + +==== +[source,java,indent=0] +---- +@SpringBootTest(classes = BeerRestBase.Config.class, + webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) +public abstract class BeerRestBase { + + @Configuration + @EnableAutoConfiguration + static class Config { + + @Bean + ProducerController producerController(PersonCheckingService personCheckingService) { + return new ProducerController(personCheckingService); + } + + @Bean + PersonCheckingService testPersonCheckingService() { + return argument -> argument.getAge() >= 20; + } + + @Bean + HttpVerifier httpOkVerifier(@LocalServerPort int port) { + return new OkHttpHttpVerifier("localhost:" + port); + } + + } +} +---- +==== + diff --git a/docs/modules/ROOT/pages/_project-features-flows/feature-webflux-explicit.adoc b/docs/modules/ROOT/pages/_project-features-flows/feature-webflux-explicit.adoc new file mode 100644 index 0000000000..d33bf0da45 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-flows/feature-webflux-explicit.adoc @@ -0,0 +1,46 @@ +[[feature-webflux-explicit]] += WebFlux with Explicit Mode + +You can also use WebFlux with the explicit mode in your generated tests +to work with WebFlux. The following example shows how to configure using explicit mode: + +==== +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven +---- + + org.springframework.cloud + spring-cloud-contract-maven-plugin + ${spring-cloud-contract.version} + true + + EXPLICIT + + +---- + +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle +---- +contracts { + testMode = 'EXPLICIT' +} +---- +==== + +The following example shows how to set up a base class and RestAssured for Web Flux: + +==== +[source,groovy,indent=0] +---- +include:../:{samples_url}/producer_webflux/src/test/java/com/example/BeerRestBase.java[tags=annotations,indent=0] + + // your tests go here + + // in this config class you define all controllers and mocked services +include:../:{samples_url}/producer_webflux/src/test/java/com/example/BeerRestBase.java[tags=config,indent=0] + +} +---- +==== + diff --git a/docs/modules/ROOT/pages/_project-features-flows/feature-webflux.adoc b/docs/modules/ROOT/pages/_project-features-flows/feature-webflux.adoc new file mode 100644 index 0000000000..016113e6d0 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-flows/feature-webflux.adoc @@ -0,0 +1,53 @@ +[[feature-webflux]] += WebFlux with WebTestClient + +You can work with WebFlux by using WebTestClient. The following listing shows how to +configure WebTestClient as the test mode: + +==== +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven +---- + + org.springframework.cloud + spring-cloud-contract-maven-plugin + ${spring-cloud-contract.version} + true + + WEBTESTCLIENT + + +---- + +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle +---- +contracts { + testMode = 'WEBTESTCLIENT' +} +---- +==== + +The following example shows how to set up a WebTestClient base class and RestAssured +for WebFlux: + +==== +[source,groovy,indent=0] +---- +import io.restassured.module.webtestclient.RestAssuredWebTestClient; +import org.junit.Before; + +public abstract class BeerRestBase { + + @Before + public void setup() { + RestAssuredWebTestClient.standaloneSetup( + new ProducerController(personToCheck -> personToCheck.age >= 20)); + } +} +} +---- +==== + +TIP: The `WebTestClient` mode is faster than the `EXPLICIT` mode. + diff --git a/docs/modules/ROOT/pages/_project-features-flows/graphql.adoc b/docs/modules/ROOT/pages/_project-features-flows/graphql.adoc new file mode 100644 index 0000000000..f4c67cbca3 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-flows/graphql.adoc @@ -0,0 +1,185 @@ +[[features-graphql]] += GraphQL + +Since https://graphql.org/[GraphQL] is essentially HTTP you can write a contract for it by creating a standard HTTP contract with an additional `metadata` entry with key `verifier` and a mapping `tool=graphql`. + +==== +[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] +.Groovy +---- +import org.springframework.cloud.contract.spec.Contract + +Contract.make { + + request { + method(POST()) + url("/graphql") + headers { + contentType("application/json") + } + body(''' +{ + "query":"query queryName($personName: String!) {\\n personToCheck(name: $personName) {\\n name\\n age\\n }\\n}\\n\\n\\n\\n", + "variables":{"personName":"Old Enough"}, + "operationName":"queryName" +} +''') + } + + response { + status(200) + headers { + contentType("application/json") + } + body('''\ +{ + "data": { + "personToCheck": { + "name": "Old Enough", + "age": "40" + } + } +} +''') + } + metadata(verifier: [ + tool: "graphql" + ]) +} +---- + +[source,yml,indent=0,subs="verbatim,attributes",role="secondary"] +.YAML +---- +--- +request: + method: "POST" + url: "/graphql" + headers: + Content-Type: "application/json" + body: + query: "query queryName($personName: String!) { personToCheck(name: $personName) + { name age } }" + variables: + personName: "Old Enough" + operationName: "queryName" + matchers: + headers: + - key: "Content-Type" + regex: "application/json.*" + regexType: "as_string" +response: + status: 200 + headers: + Content-Type: "application/json" + body: + data: + personToCheck: + name: "Old Enough" + age: "40" + matchers: + headers: + - key: "Content-Type" + regex: "application/json.*" + regexType: "as_string" +name: "shouldRetrieveOldEnoughPerson" +metadata: + verifier: + tool: "graphql" +---- +==== + +Adding the metadata section will change the way the default, WireMock stub is built. It will now use the Spring Cloud Contract request matcher, so that e.g. the `query` part of the GraphQL request gets compared against the real request by ignoring whitespaces. + +[[features-graphql-producer]] +== Producer Side Setup + +On the producer side your configuration can look as follows. + +==== +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven +---- + + org.springframework.cloud + spring-cloud-contract-maven-plugin + ${spring-cloud-contract.version} + true + + EXPLICIT + com.example.BaseClass + + +---- + +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle +---- +contracts { + testMode = "EXPLICIT" + baseClassForTests = "com.example.BaseClass" +} +---- +==== + +The base class would set up the application running on a random port. + +==== +[source,java,indent=0,subs="verbatim,attributes"] +.Base Class +---- +@SpringBootTest(classes = ProducerApplication.class, + properties = "graphql.servlet.websocket.enabled=false", + webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) +public abstract class BaseClass { + + @LocalServerPort int port; + + @BeforeEach + public void setup() { + RestAssured.baseURI = "http://localhost:" + port; + } +} + +---- +==== + +[[features-graphql-consumer]] +== Consumer Side Setup + +Example of a consumer side test of the GraphQL API. + +==== +[source,java,indent=0,subs="verbatim,attributes"] +.Consumer Side Test +---- +@SpringBootTest(webEnvironment = WebEnvironment.NONE) +public class BeerControllerGraphQLTest { + + @RegisterExtension + static StubRunnerExtension rule = new StubRunnerExtension() + .downloadStub("com.example","beer-api-producer-graphql") + .stubsMode(StubRunnerProperties.StubsMode.LOCAL); + + private static final String REQUEST_BODY = "{\n" + + "\"query\":\"query queryName($personName: String!) {\\n personToCheck(name: $personName) {\\n name\\n age\\n }\\n}\"," + + "\"variables\":{\"personName\":\"Old Enough\"},\n" + + "\"operationName\":\"queryName\"\n" + + "}"; + + @Test + public void should_send_a_graphql_request() { + ResponseEntity responseEntity = new RestTemplate() + .exchange(RequestEntity + .post(URI.create("http://localhost:" + rule.findStubUrl("beer-api-producer-graphql").getPort() + "/graphql")) + .contentType(MediaType.APPLICATION_JSON) + .body(REQUEST_BODY), String.class); + + BDDAssertions.then(responseEntity.getStatusCodeValue()).isEqualTo(200); + + } +} + +---- +==== + diff --git a/docs/modules/ROOT/pages/_project-features-flows/grpc.adoc b/docs/modules/ROOT/pages/_project-features-flows/grpc.adoc new file mode 100644 index 0000000000..d8c5d7d75b --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-flows/grpc.adoc @@ -0,0 +1,277 @@ +[[features-grpc]] += GRPC + +https://grpc.io/[GRPC] is an RPC framework built on top of HTTP/2 for which Spring Cloud Contract has basic support. + +IMPORTANT: Spring Cloud Contract has an experimental support for basic use cases of GRPC. Unfortunately, due to GRPC's tweaking of the HTTP/2 Header frames, it's impossible to assert the `grpc-status` header. + +Let's look at the following contract. + +==== +[source,groovy,indent=0,subs="verbatim,attributes"] +.Groovy contract +---- +package contracts.beer.rest + + +import org.springframework.cloud.contract.spec.Contract +import org.springframework.cloud.contract.verifier.http.ContractVerifierHttpMetaData + +Contract.make { + description(""" +Represents a successful scenario of getting a beer + +``` +given: + client is old enough +when: + he applies for a beer +then: + we'll grant him the beer +``` + +""") + request { + method 'POST' + url '/beer.BeerService/check' + body(fileAsBytes("PersonToCheck_old_enough.bin")) + headers { + contentType("application/grpc") + header("te", "trailers") + } + } + response { + status 200 + body(fileAsBytes("Response_old_enough.bin")) + headers { + contentType("application/grpc") + header("grpc-encoding", "identity") + header("grpc-accept-encoding", "gzip") + } + } + metadata([ + "verifierHttp": [ + "protocol": ContractVerifierHttpMetaData.Protocol.H2_PRIOR_KNOWLEDGE.toString() + ] + ]) +} +---- +==== + +[[features-grpc-producer]] +== Producer Side Setup + +In order to leverage the HTTP/2 support you must set the `CUSTOM` test mode as follow. + +==== +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven +---- + + org.springframework.cloud + spring-cloud-contract-maven-plugin + ${spring-cloud-contract.version} + true + + CUSTOM + com.example + + +---- + +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle +---- +contracts { + packageWithBaseClasses = 'com.example' + testMode = "CUSTOM" +} +---- +==== + +The base class would set up the application running on a random port. It will also set the `HttpVerifier` implementation to one that can use the HTTP/2 protocol. Spring Cloud Contract comes with the `OkHttpHttpVerifier` implementation. + +==== +[source,java,indent=0,subs="verbatim,attributes"] +.Base Class +---- +@SpringBootTest(classes = BeerRestBase.Config.class, + webEnvironment = SpringBootTest.WebEnvironment.NONE, + properties = { + "grpc.server.port=0" + }) +public abstract class BeerRestBase { + + @Autowired + GrpcServerProperties properties; + + @Configuration + @EnableAutoConfiguration + static class Config { + + @Bean + ProducerController producerController(PersonCheckingService personCheckingService) { + return new ProducerController(personCheckingService); + } + + @Bean + PersonCheckingService testPersonCheckingService() { + return argument -> argument.getAge() >= 20; + } + + @Bean + HttpVerifier httpOkVerifier(GrpcServerProperties properties) { + return new OkHttpHttpVerifier("localhost:" + properties.getPort()); + } + + } +} +---- +==== + +[[features-grpc-consumer]] +== Consumer Side Setup + +Example of GRPC consumer side test. Due to the unusual behaviour of the GRPC server side, the stub is unable to return the `grpc-status` header in the proper moment. This is why we need to manually set the return status. + +==== +[source,java,indent=0,subs="verbatim,attributes"] +.Consumer Side Test +---- +@SpringBootTest(webEnvironment = WebEnvironment.NONE, classes = GrpcTests.TestConfiguration.class, properties = { + "grpc.client.beerService.address=static://localhost:5432", "grpc.client.beerService.negotiationType=TLS" +}) +public class GrpcTests { + + @GrpcClient(value = "beerService", interceptorNames = "fixedStatusSendingClientInterceptor") + BeerServiceGrpc.BeerServiceBlockingStub beerServiceBlockingStub; + + int port; + + @RegisterExtension + static StubRunnerExtension rule = new StubRunnerExtension() + .downloadStub("com.example", "beer-api-producer-grpc") + // With WireMock PlainText mode you can just set an HTTP port +// .withPort(5432) + .stubsMode(StubRunnerProperties.StubsMode.LOCAL) + .withHttpServerStubConfigurer(MyWireMockConfigurer.class); + + @BeforeEach + public void setupPort() { + this.port = rule.findStubUrl("beer-api-producer-grpc").getPort(); + } + + @Test + public void should_give_me_a_beer_when_im_old_enough() throws Exception { + Response response = beerServiceBlockingStub.check(PersonToCheck.newBuilder().setAge(23).build()); + + BDDAssertions.then(response.getStatus()).isEqualTo(Response.BeerCheckStatus.OK); + } + + @Test + public void should_reject_a_beer_when_im_too_young() throws Exception { + Response response = beerServiceBlockingStub.check(PersonToCheck.newBuilder().setAge(17).build()); + response = response == null ? Response.newBuilder().build() : response; + + BDDAssertions.then(response.getStatus()).isEqualTo(Response.BeerCheckStatus.NOT_OK); + } + + // Not necessary with WireMock PlainText mode + static class MyWireMockConfigurer extends WireMockHttpServerStubConfigurer { + @Override + public WireMockConfiguration configure(WireMockConfiguration httpStubConfiguration, HttpServerStubConfiguration httpServerStubConfiguration) { + return httpStubConfiguration + .httpsPort(5432); + } + } + + @Configuration + @ImportAutoConfiguration(GrpcClientAutoConfiguration.class) + static class TestConfiguration { + + // Not necessary with WireMock PlainText mode + @Bean + public GrpcChannelConfigurer keepAliveClientConfigurer() { + return (channelBuilder, name) -> { + if (channelBuilder instanceof NettyChannelBuilder) { + try { + ((NettyChannelBuilder) channelBuilder) + .sslContext(GrpcSslContexts.forClient() + .trustManager(InsecureTrustManagerFactory.INSTANCE) + .build()); + } + catch (SSLException e) { + throw new IllegalStateException(e); + } + } + }; + } + + /** + * GRPC client interceptor that sets the returned status always to OK. + * You might want to change the return status depending on the received stub payload. + * + * Hopefully in the future this will be unnecessary and will be removed. + */ + @Bean + ClientInterceptor fixedStatusSendingClientInterceptor() { + return new ClientInterceptor() { + @Override + public ClientCall interceptCall(MethodDescriptor method, CallOptions callOptions, Channel next) { + ClientCall call = next.newCall(method, callOptions); + return new ClientCall() { + @Override + public void start(Listener responseListener, Metadata headers) { + Listener listener = new Listener() { + @Override + public void onHeaders(Metadata headers) { + responseListener.onHeaders(headers); + } + + @Override + public void onMessage(RespT message) { + responseListener.onMessage(message); + } + + @Override + public void onClose(Status status, Metadata trailers) { + // TODO: This must be fixed somehow either in Jetty (WireMock) or somewhere else + responseListener.onClose(Status.OK, trailers); + } + + @Override + public void onReady() { + responseListener.onReady(); + } + }; + call.start(listener, headers); + } + + @Override + public void request(int numMessages) { + call.request(numMessages); + } + + @Override + public void cancel(@Nullable String message, @Nullable Throwable cause) { + call.cancel(message, cause); + } + + @Override + public void halfClose() { + call.halfClose(); + } + + @Override + public void sendMessage(ReqT message) { + call.sendMessage(message); + } + }; + } + }; + } + } +} + +---- +==== diff --git a/docs/modules/ROOT/pages/_project-features-flows/jax-rs.adoc b/docs/modules/ROOT/pages/_project-features-flows/jax-rs.adoc new file mode 100644 index 0000000000..9f951c19fb --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-flows/jax-rs.adoc @@ -0,0 +1,26 @@ +[[features-jax-rs]] += JAX-RS + +The Spring Cloud Contract 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 be set. Otherwise, the default of `application/octet-stream` gets used. + +To use JAX-RS mode, use the following setting: + +==== +[source,groovy,indent=0] +---- +testMode = 'JAXRSCLIENT' +---- +==== + +The following example shows a generated test API: + +==== +[source,groovy,indent=0] +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/JaxRsClientMethodBuilderSpec.groovy[tags=jaxrs,indent=0] +---- +==== + diff --git a/docs/modules/ROOT/pages/_project-features-flows/rest-docs.adoc b/docs/modules/ROOT/pages/_project-features-flows/rest-docs.adoc new file mode 100644 index 0000000000..90d535e0d1 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-flows/rest-docs.adoc @@ -0,0 +1,307 @@ +[[features-rest-docs]] += Working with REST Docs + +You can use https://projects.spring.io/spring-restdocs[Spring REST Docs] to generate +documentation (for example, in Asciidoc format) for an HTTP API with Spring MockMvc, +WebTestClient, or RestAssured. 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 UML diagram shows +the REST Docs flow: + +[plantuml, rest-docs, png] +---- +"API Producer"->"API Producer": Add Spring Cloud Contract (SCC) \nStub Runner dependency +"API Producer"->"API Producer": Set up stub jar assembly +"API Producer"->"API Producer": Write and set up REST Docs tests +"API Producer"->"Build": Run build +"Build"->"REST Docs": Generate API \ndocumentation +"REST Docs"->"SCC": Generate stubs from the \nREST Docs tests +"REST Docs"->"SCC": Generate contracts from the \nREST Docs tests +"Build"->"Build": Assemble stubs jar with \nstubs and contracts +"Build"->"Nexus / Artifactory": Upload contracts \nand stubs and the project arifact +"Build"->"API Producer": Build successful +"API Consumer"->"API Consumer": Add SCC Stub Runner \ndependency +"API Consumer"->"API Consumer": Write a SCC Stub Runner \nbased contract test +"SCC Stub Runner"->"Nexus / Artifactory": Test asks for [API Producer] stubs +"Nexus / Artifactory"->"SCC Stub Runner": Fetch the [API Producer] stubs +"SCC Stub Runner"->"SCC Stub Runner": Run in memory\n HTTP server stubs +"API Consumer"->"SCC Stub Runner": Send a request \nto the HTTP server stub +"SCC Stub Runner"->"API Consumer": Communication is correct +---- + +The following example uses `MockMvc`: + +==== +[source,java,indent=0] +---- +@RunWith(SpringRunner.class) +@SpringBootTest +@AutoConfigureRestDocs(outputDir = "target/snippets") +@AutoConfigureMockMvc +public class ApplicationTests { + + @Autowired + private MockMvc mockMvc; + + @Test + public void contextLoads() throws Exception { + mockMvc.perform(get("/resource")) + .andExpect(content().string("Hello World")) + .andDo(document("resource")); + } +} +---- +==== + +This test generates a WireMock stub at `target/snippets/stubs/resource.json`. It matches +all `GET` requests to the `/resource` path. The same example with WebTestClient (used +for testing Spring WebFlux applications) would be as follows: + +==== +[source,java,indent=0] +---- +@RunWith(SpringRunner.class) +@SpringBootTest +@AutoConfigureRestDocs(outputDir = "target/snippets") +@AutoConfigureWebTestClient +public class ApplicationTests { + + @Autowired + private WebTestClient client; + + @Test + public void contextLoads() throws Exception { + client.get().uri("/resource").exchange() + .expectBody(String.class).isEqualTo("Hello World") + .consumeWith(document("resource")); + } +} +---- +==== + +Without any additional configuration, these tests create a stub with a request matcher +for the HTTP method and all headers except `host` and `content-length`. To match the +request more precisely (for example, to match the body of a POST or PUT), we need to +explicitly create a request matcher. Doing so has two effects: + +* Creating a stub that matches only in the way you specify. +* Asserting that the request in the test case also matches the same conditions. + +The main entry point for this feature is `WireMockRestDocs.verify()`, which can be used +as a substitute for the `document()` convenience method, as the following +example shows: + +==== +[source,java,indent=0] +---- +import static org.springframework.cloud.contract.wiremock.restdocs.WireMockRestDocs.verify; + +@RunWith(SpringRunner.class) +@SpringBootTest +@AutoConfigureRestDocs(outputDir = "target/snippets") +@AutoConfigureMockMvc +public class ApplicationTests { + + @Autowired + private MockMvc mockMvc; + + @Test + public void contextLoads() throws Exception { + mockMvc.perform(post("/resource") + .content("{\"id\":\"123456\",\"message\":\"Hello World\"}")) + .andExpect(status().isOk()) + .andDo(verify().jsonPath("$.id")) + .andDo(document("resource")); + } +} +---- +==== + +The preceding contract specifies that any valid POST with an `id` field receives the response +defined in this test. You can chain together calls to `.jsonPath()` to add additional +matchers. If JSON Path is unfamiliar, the https://github.com/jayway/JsonPath[JayWay +documentation] can help you get up to speed. The WebTestClient version of this test +has a similar `verify()` static helper that you insert in the same place. + +Instead of the `jsonPath` and `contentType` convenience methods, you can also use the +WireMock APIs to verify that the request matches the created stub, as the +following example shows: + +==== +[source,java,indent=0] +---- + @Test + public void contextLoads() throws Exception { + mockMvc.perform(post("/resource") + .content("{\"id\":\"123456\",\"message\":\"Hello World\"}")) + .andExpect(status().isOk()) + .andDo(verify() + .wiremock(WireMock.post(urlPathEquals("/resource")) + .withRequestBody(matchingJsonPath("$.id")) + .andDo(document("post-resource")))); + } +---- +==== + +The WireMock API is rich. You can match headers, query parameters, and the request body by +regex as well as by JSON path. You can use these features to create stubs with a wider +range of parameters. The preceding example generates a stub resembling the following example: + +==== +.post-resource.json +[source,json] +---- +{ + "request" : { + "url" : "/resource", + "method" : "POST", + "bodyPatterns" : [ { + "matchesJsonPath" : "$.id" + }] + }, + "response" : { + "status" : 200, + "body" : "Hello World", + "headers" : { + "X-Application-Context" : "application:-1", + "Content-Type" : "text/plain" + } + } +} +---- +==== + +NOTE: You can use either the `wiremock()` method or the `jsonPath()` and `contentType()` +methods to create request matchers, but you cannot use both approaches. + +On the consumer side, you can make the `resource.json` generated earlier in this section +available on the classpath (by +<>, for example). After that, you can create a stub that uses WireMock in a +number of different ways, including by using +`@AutoConfigureWireMock(stubs="classpath:resource.json")`, as described earlier in this +document. + +[[features-rest-docs-contracts]] +== Generating Contracts with REST Docs + +You can also generate Spring Cloud Contract DSL files and documentation with Spring REST +Docs. If you do so in combination with Spring Cloud WireMock, you get both the contracts +and the stubs. + +Why would you want to use this feature? Some people in the community asked questions +about a situation in which they would like to move to DSL-based contract definition, +but they already have a lot of Spring MVC tests. Using this feature lets you generate +the contract files that you can later modify and move to folders (defined in your +configuration) so that the plugin finds them. + +NOTE: You might wonder why this functionality is in the WireMock module. The functionality +is there because it makes sense to generate both the contracts and the stubs. + +Consider the following test: + +==== +[source,java] +---- +include:../:{wiremock_tests}/src/test/java/org/springframework/cloud/contract/wiremock/restdocs/ContractDslSnippetTests.java[tags=contract_snippet] +---- +==== + +The preceding test creates the stub presented in the previous section, generating both +the contract and a documentation file. + +The contract is called `index.groovy` and might resemble the following example: + +==== +[source,groovy] +---- +import org.springframework.cloud.contract.spec.Contract + +Contract.make { + request { + method 'POST' + url '/foo' + body(''' + {"foo": 23 } + ''') + headers { + header('''Accept''', '''application/json''') + header('''Content-Type''', '''application/json''') + } + } + response { + status OK() + body(''' + bar + ''') + headers { + header('''Content-Type''', '''application/json;charset=UTF-8''') + header('''Content-Length''', '''3''') + } + bodyMatchers { + jsonPath('$[?(@.foo >= 20)]', byType()) + } + } +} +---- +==== + +The generated document (formatted in Asciidoc in this case) contains a formatted +contract. The location of this file would be `index/dsl-contract.adoc`. + +[[features-restdocs-priority-attribute]] +== Specifying the priority attribute + +The method `SpringCloudContractRestDocs.dslContract()` takes an optional Map parameter that allows you to specify additional attributes in the template. + +One of these attributes is the <> field that you may specify as follows: + +[source,java,indent=0] +---- +SpringCloudContractRestDocs.dslContract(Map.of("priority", 1)) +---- + +[[features-restdocs-override]] +== Overriding the DSL contract template + +By default, the output of the contract is based on a file named `default-dsl-contract-only.snippet`. + +You may provide a custom template file instead by overriding the getTemplate() method as follows: + +[source,java,indent=0] +---- +new ContractDslSnippet(){ + @Override + protected String getTemplate() { + return "custom-dsl-contract"; + } +})); +---- + +so the example above showing this line +[source,java,indent=0] +---- +.andDo(document("index", SpringCloudContractRestDocs.dslContract())); +---- + +should be changed to: +[source,java,indent=0] +---- +.andDo(document("index", new ContractDslSnippet(){ + @Override + protected String getTemplate() { + return "custom-dsl-template"; + } + })); +---- + +Templates are resolved by looking for resources on the classpath. The following locations are checked in order: + +* `org/springframework/restdocs/templates/${templateFormatId}/${name}.snippet` +* `org/springframework/restdocs/templates/${name}.snippet` +* `org/springframework/restdocs/templates/${templateFormatId}/default-${name}.snippet` + +Therefore in the example above you should place a file named custom-dsl-template.snippet in `src/test/resources/org/springframework/restdocs/templates/custom-dsl-template.snippet` + + + diff --git a/docs/modules/ROOT/pages/_project-features-stubrunner.adoc b/docs/modules/ROOT/pages/_project-features-stubrunner.adoc index 9f18282f08..619dfb4fad 100644 --- a/docs/modules/ROOT/pages/_project-features-stubrunner.adoc +++ b/docs/modules/ROOT/pages/_project-features-stubrunner.adoc @@ -9,1081 +9,3 @@ Copying the JSON files and setting the client side for messaging manually is out question. That is why we introduced Spring Cloud Contract Stub Runner. It can automatically download and run the stubs for you. -[[features-stub-runner-snapshot-versions]] -== Snapshot Versions - -You can add the additional snapshot repository to your build file to use snapshot -versions, which are automatically uploaded after every successful build, as follows: - -==== -[source,xml,indent=0,subs="verbatim,attributes",role="primary"] -.Maven ----- -include::{standalone_samples_path}/http-server/pom.xml[tags=repos,indent=0] ----- - -[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] -.Gradle (`settings.xml`) ----- -include::{standalone_samples_path}/http-server/settings.gradle[tags=repos,indent=0] ----- -==== - -[[features-stub-runner-publishing-stubs-as-jars]] -== Publishing Stubs as JARs - -The easiest approach to publishing stubs as jars is to centralize the way stubs are kept. -For example, you can keep them as jars in a Maven repository. - -TIP: For both Maven and Gradle, the setup comes ready to work. However, you can customize -it if you want to. - -The following example shows how to publish stubs as jars: - -==== -[source,xml,indent=0,subs="verbatim,attributes",role="primary"] -.Maven ----- - -include::{samples_url}/producer_with_restdocs/pom.xml[tags=skip_jar,indent=0] - - -include::{samples_url}/producer_with_restdocs/pom.xml[tags=assembly,indent=0] - - -include::{samples_url}/producer_with_restdocs/src/assembly/stub.xml[indent=0] ----- - -[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] -.Gradle ----- -include::{plugins_path}/spring-cloud-contract-gradle-plugin/src/test/resources/functionalTest/scenarioProject/build.gradle[tags=jar_setup,indent=0] ----- -==== - -[[features-stub-runner-core]] -== Stub Runner Core - -The stub runner core runs stubs for service collaborators. Treating stubs as contracts of -services lets you use stub-runner as an implementation of -https://martinfowler.com/articles/consumerDrivenContracts.html[Consumer-driven Contracts]. - -Stub Runner lets you automatically download the stubs of the provided dependencies (or -pick those from the classpath), start WireMock servers for them, and feed them with proper -stub definitions. For messaging, special stub routes are defined. - -[[features-stub-runner-retrieving]] -=== Retrieving stubs - -You can pick from the following options of acquiring stubs: - -- Aether-based solution that downloads JARs with stubs from Artifactory or Nexus -- Classpath-scanning solution that searches the classpath with a pattern to retrieve stubs -- Writing your own implementation of the `org.springframework.cloud.contract.stubrunner.StubDownloaderBuilder` for full customization - -The latter example is described in the <> section. - -[[features-stub-runner-downloading-stub]] -==== Downloading Stubs - -You can control the downloading of stubs with the `stubsMode` switch. It picks value from the -`StubRunnerProperties.StubsMode` enumeration. You can use the following options: - -- `StubRunnerProperties.StubsMode.CLASSPATH` (default value): Picks stubs from the classpath -- `StubRunnerProperties.StubsMode.LOCAL`: Picks stubs from a local storage (for example, `.m2`) -- `StubRunnerProperties.StubsMode.REMOTE`: Picks stubs from a remote location - -The following example picks stubs from a local location: - -==== -[source,java] ----- -@AutoConfigureStubRunner(repositoryRoot="https://foo.bar", ids = "com.example:beer-api-producer:+:stubs:8095", stubsMode = StubRunnerProperties.StubsMode.LOCAL) ----- -==== - -[[features-stub-runner-classpath-scanning]] -==== Classpath scanning - -If you set the `stubsMode` property to `StubRunnerProperties.StubsMode.CLASSPATH` -(or set nothing since `CLASSPATH` is the default value), the classpath is scanned. -Consider the following example: - -==== -[source,java] ----- -@AutoConfigureStubRunner(ids = { - "com.example:beer-api-producer:+:stubs:8095", - "com.example.foo:bar:1.0.0:superstubs:8096" -}) ----- -==== - -You can add the dependencies to your classpath, as follows: - -==== -[source,xml,indent=0,subs="verbatim,attributes",role="primary"] -.Maven ----- - - com.example - beer-api-producer-restdocs - stubs - 0.0.1-SNAPSHOT - test - - - * - * - - - - - com.example.thing1 - thing2 - superstubs - 1.0.0 - test - - - * - * - - - ----- - -[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] -.Gradle ----- -testCompile("com.example:beer-api-producer-restdocs:0.0.1-SNAPSHOT:stubs") { - transitive = false -} -testCompile("com.example.thing1:thing2:1.0.0:superstubs") { - transitive = false -} ----- -==== - -Then the specified locations on your classpath get scanned. For `com.example:beer-api-producer-restdocs`, -the following locations are scanned: - -- /META-INF/com.example/beer-api-producer-restdocs/**/*.* -- /contracts/com.example/beer-api-producer-restdocs/**/*.* -- /mappings/com.example/beer-api-producer-restdocs/**/*.* - -For `com.example.thing1:thing2`, the following locations are scanned: - -- /META-INF/com.example.thing1/thing2/**/*.* -- /contracts/com.example.thing1/thing2/**/*.* -- /mappings/com.example.thing1/thing2/**/*.* - -TIP: You have to explicitly provide the group and artifact IDs when you package the -producer stubs. - -To achieve proper stub packaging, the producer would set up the contracts as follows: - -==== -[source,bash] ----- -└── src - └── test - └── resources - └── contracts -    └── com.example -       └── beer-api-producer-restdocs -       └── nested -       └── contract3.groovy - ----- -==== - -By using the https://github.com/spring-cloud-samples/spring-cloud-contract-samples/blob/{samples_branch}/producer_with_restdocs/pom.xml[Maven `assembly` plugin] or the -https://github.com/spring-cloud-samples/spring-cloud-contract-samples/blob/{samples_branch}/producer_with_restdocs/build.gradle[Gradle Jar] task, you have to create the following -structure in your stubs jar: - -==== -[source,bash] ----- -└── META-INF - └── com.example - └── beer-api-producer-restdocs - └── 2.0.0 - ├── contracts - │   └── nested -    │ └── contract2.groovy -    └── mappings -    └── mapping.json - ----- -==== - -By maintaining this structure, the classpath gets scanned and you can profit from the messaging or -HTTP stubs without the need to download artifacts. - -[[features-stub-runner-configuring-http-server-stubs]] -==== Configuring HTTP Server Stubs - -Stub Runner has a notion of a `HttpServerStub` that abstracts the underlying -concrete implementation of the HTTP server (for example, WireMock is one of the implementations). -Sometimes, you need to perform some additional tuning (which is concrete for the given implementation) of the stub servers. -To do that, Stub Runner gives you -the `httpServerStubConfigurer` property that is available in the annotation and the -JUnit rule and is accessible through system properties, where you can provide -your implementation of the `org.springframework.cloud.contract.stubrunner.HttpServerStubConfigurer` -interface. The implementations can alter -the configuration files for the given HTTP server stub. - -Spring Cloud Contract Stub Runner comes with an implementation that you -can extend for WireMock: -`org.springframework.cloud.contract.stubrunner.provider.wiremock.WireMockHttpServerStubConfigurer`. -In the `configure` method, -you can provide your own custom configuration for the given stub. The use -case might be starting WireMock for the given artifact ID, on an HTTPS port. The following -example shows how to do so: - -.WireMockHttpServerStubConfigurer implementation -==== -[source,groovy,indent=0] ----- -include::{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/spring/StubRunnerConfigurationSpec.groovy[tags=wireMockHttpServerStubConfigurer] ----- -==== - -You can then reuse it with the `@AutoConfigureStubRunner` annotation, as follows: - -==== -[source,groovy,indent=0] ----- -include::{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/spring/StubRunnerConfigurationSpec.groovy[tags=annotation] ----- -==== - -Whenever an HTTPS port is found, it takes precedence over the HTTP port. - -[[features-stub-runner-running-stubs]] -=== Running stubs - -This section describes how to run stubs. It contains the following topics: - -* <> -* <> -* <> - -[[features-stub-runner-http-stubs]] -==== HTTP Stubs - -Stubs are defined in JSON documents, whose syntax is defined in the http://wiremock.org/stubbing.html[WireMock documentation]. - -The following example defines a stub in JSON: - -==== -[source,javascript,indent=0] ----- -{ - "request": { - "method": "GET", - "url": "/ping" - }, - "response": { - "status": 200, - "body": "pong", - "headers": { - "Content-Type": "text/plain" - } - } -} ----- -==== - -[[features-stub-runner-viewing]] -==== Viewing Registered Mappings - -Every stubbed collaborator exposes a list of defined mappings under the `__/admin/` endpoint. - -You can also use the `mappingsOutputFolder` property to dump the mappings to files. -For the annotation-based approach, it would resembling the following example: - -==== -[source,java] ----- -@AutoConfigureStubRunner(ids="a.b.c:loanIssuance,a.b.c:fraudDetectionServer", -mappingsOutputFolder = "target/outputmappings/") ----- -==== - -For the JUnit approach, it resembles the following example: - -==== -[source,java] ----- -@ClassRule @Shared StubRunnerRule rule = new StubRunnerRule() - .repoRoot("https://some_url") - .downloadStub("a.b.c", "loanIssuance") - .downloadStub("a.b.c:fraudDetectionServer") - .withMappingsOutputFolder("target/outputmappings") ----- -==== - -Then, if you check out the `target/outputmappings` folder, you would see the following structure; - -==== -[source,bash] ----- -. -├── fraudDetectionServer_13705 -└── loanIssuance_12255 ----- -==== - -That means that there were two stubs registered. `fraudDetectionServer` was registered at port `13705` -and `loanIssuance` at port `12255`. If we take a look at one of the files, we would see (for WireMock) -the mappings available for the given server: - -==== -[source,json] ----- -[{ - "id" : "f9152eb9-bf77-4c38-8289-90be7d10d0d7", - "request" : { - "url" : "/name", - "method" : "GET" - }, - "response" : { - "status" : 200, - "body" : "fraudDetectionServer" - }, - "uuid" : "f9152eb9-bf77-4c38-8289-90be7d10d0d7" -}, -... -] ----- -==== - -[[features-stub-runner-messaging]] -==== Messaging Stubs - -Depending on the provided Stub Runner dependency and the DSL, the messaging routes are automatically set up. - -[[features-stub-runner-junit]] -== Stub Runner JUnit Rule and Stub Runner JUnit5 Extension - -Stub Runner comes with a JUnit rule that lets you can download and run stubs for a given -group and artifact ID, as the following example shows: - -==== -[source,java,indent=0] ----- -include::{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/junit4/StubRunnerRuleJUnitTest.java[tags=classrule] ----- -==== - -A `StubRunnerExtension` is also available for JUnit 5. `StubRunnerRule` and -`StubRunnerExtension` work in a very similar fashion. After the rule or extension is -called, Stub Runner connects to your Maven repository and, for the given list of -dependencies, tries to: - -- Download them -- Cache them locally -- Unzip them to a temporary folder -- Start a WireMock server for each Maven dependency on a random port from the provided -range of ports or the provided port -- Feed the WireMock server with all JSON files that are valid WireMock definitions -- Send messages (remember to pass an implementation of `MessageVerifierSender` interface) - -Stub Runner uses the https://wiki.eclipse.org/Aether[Eclipse Aether] mechanism to download the Maven dependencies. -Check their https://wiki.eclipse.org/Aether[docs] for more information. - -Since the `StubRunnerRule` and `StubRunnerExtension` implement the `StubFinder`, they let -you find the started stubs, as the following example shows: - -==== -[source,groovy,indent=0] ----- -include::{stubrunner_core_path}/src/main/java/org/springframework/cloud/contract/stubrunner/StubFinder.java[lines=16..-1] ----- -==== - -The following examples provide more detail about using Stub Runner: - -==== -[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] -.Spock ----- -include::{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/junit4/StubRunnerRuleSpec.groovy[tags=classrule] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Junit 4 ----- -include::{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/junit4/StubRunnerRuleJUnitTest.java[tags=test] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Junit 5 ----- -include::{stubrunner_core_path}/src/test/java/org/springframework/cloud/contract/stubrunner/junit/StubRunnerJUnit5ExtensionTests.java[tags=extension] ----- -==== - -See the <> for more information on -how to apply global configuration of Stub Runner. - -IMPORTANT: To use the JUnit rule or JUnit 5 extension together with messaging, you have to provide an implementation of the -`MessageVerifierSender` and `MessageVerifierReceiver` interface to the rule builder (for example, `rule.messageVerifierSender(new MyMessageVerifierSender())`). -If you do not do this, then, whenever you try to send a message, an exception is thrown. - -[[features-stub-runner-rule-maven-settings]] -=== Maven Settings - -The stub downloader honors Maven settings for a different local repository folder. -Authentication details for repositories and profiles are currently not taken into account, -so you need to specify it by using the properties mentioned above. - -[[features-stub-runner-rule-fixed-ports]] -=== Providing Fixed Ports - -You can also run your stubs on fixed ports. You can do it in two different ways. -One is to pass it in the properties, and the other is to use the fluent API of -JUnit rule. - -[[features-stub-runner-rule-fluent-api]] -=== Fluent API - -When using the `StubRunnerRule` or `StubRunnerExtension`, you can add a stub to download -and then pass the port for the last downloaded stub. The following example shows how to do so: - -==== -[source,java,indent=0] ----- -include::{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/junit4/StubRunnerRuleCustomPortJUnitTest.java[tags=classrule_with_port] ----- -==== - -For the preceding example, the following test is valid: - -==== -[source,java,indent=0] ----- -include::{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/junit4/StubRunnerRuleCustomPortJUnitTest.java[tags=test_with_port] ----- -==== - -[[features-stub-runner-rule-spring]] -=== Stub Runner with Spring - -Stub Runner with Spring sets up Spring configuration of the Stub Runner project. - -By providing a list of stubs inside your configuration file, Stub Runner automatically downloads -and registers in WireMock the selected stubs. - -If you want to find the URL of your stubbed dependency, you can autowire the `StubFinder` interface and use -its methods, as follows: - -==== -[source,groovy,indent=0] ----- -include::{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/spring/StubRunnerConfigurationSpec.groovy[tags=test] ----- -==== - -Doing so depends on the following configuration file: - -==== -[source,yml,indent=0] ----- -include::{stubrunner_core_path}/src/test/resources/application-test.yml[tags=test] ----- -==== - -Instead of using the properties, you can also use the properties inside the `@AutoConfigureStubRunner`. -The following example achieves the same result by setting values on the annotation: - -==== -[source,groovy,indent=0] ----- -include::{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/spring/cloud/consul/StubRunnerSpringCloudConsulAutoConfigurationSpec.groovy[tags=autoconfigure] ----- -==== - -Stub Runner Spring registers environment variables in the following manner -for every registered WireMock server. The following example shows Stub Runner IDs for -`com.example:thing1` and `com.example:thing2`: - -- `stubrunner.runningstubs.thing1.port` -- `stubrunner.runningstubs.com.example.thing1.port` -- `stubrunner.runningstubs.thing2.port` -- `stubrunner.runningstubs.com.example.thing2.port` - -You can reference these values in your code. - -You can also use the `@StubRunnerPort` annotation to inject the port of a running stub. -The value of the annotation can be the `groupid:artifactid` or only the `artifactid`. -The following example works shows Stub Runner IDs for -`com.example:thing1` and `com.example:thing2`. - -==== -[source,java,indent=0] ----- -@StubRunnerPort("thing1") -int thing1Port; -@StubRunnerPort("com.example:thing2") -int thing2Port; ----- -==== - -[[features-stub-runner-cloud]] -== Stub Runner Spring Cloud - -Stub Runner can integrate with Spring Cloud. - -For real life examples, see: - -- https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/{samples_branch}/producer[The producer application sample] -- https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/{samples_branch}/consumer_with_discovery[The consumer application sample] - -[[features-stub-runner-cloud-stubbing-discovery]] -=== Stubbing Service Discovery - -The most important feature of `Stub Runner Spring Cloud` is the fact that it stubs: - -- `DiscoveryClient` -- `ReactorServiceInstanceLoadBalancer` - -That means that, regardless of whether you use Zookeeper, Consul, Eureka, or anything -else, you do not need that in your tests. We are starting WireMock instances of your -dependencies and we are telling your application, whenever you use `Feign`, to load a -balanced `RestTemplate` or `DiscoveryClient` directly, to call those stubbed servers -instead of calling the real Service Discovery tool. - -[[features-stub-runner-cloud-stubbing-profiles]] -==== Test Profiles and Service Discovery - -In your integration tests, you typically do not want to call either a discovery service (such as Eureka) -or Config Server. That is why you create an additional test configuration in which you want to disable -these features. - -Due to certain limitations of https://github.com/spring-cloud/spring-cloud-commons/issues/156[`spring-cloud-commons`], -to achieve this, you have to disable these properties -in a static block such as the following example (for Eureka): - -==== -[source,java] ----- - //Hack to work around https://github.com/spring-cloud/spring-cloud-commons/issues/156 - static { - System.setProperty("eureka.client.enabled", "false"); - System.setProperty("spring.cloud.config.failFast", "false"); - } ----- -==== - -[[features-stub-runner-additional-config]] -=== Additional Configuration - -You can match the `artifactId` of the stub with the name of your application by using the `stubrunner.idsToServiceIds:` map. - -TIP: By default, all service discovery is stubbed. This means that, regardless of whether you have -an existing `DiscoveryClient`, its results are ignored. However, if you want to reuse it, you can set - `stubrunner.cloud.delegate.enabled` to `true`, and then your existing `DiscoveryClient` results are - merged with the stubbed ones. - -The default Maven configuration used by Stub Runner can be tweaked either -by setting the following system properties or by setting the corresponding environment variables: - -- `maven.repo.local`: Path to the custom maven local repository location -- `org.apache.maven.user-settings`: Path to custom maven user settings location -- `org.apache.maven.global-settings`: Path to maven global settings location - -[[features-stub-runner-boot]] -== Using the Stub Runner Boot Application - -Spring Cloud Contract Stub Runner Boot is a Spring Boot application that exposes REST endpoints to -trigger the messaging labels and to access WireMock servers. - -[[features-stub-runner-boot-security]] -=== Stub Runner Boot Security - -The Stub Runner Boot application is not secured by design - securing it would require to add security to all -stubs even if they don't actually require it. Since this is a testing utility - the server is **not intended** -to be used in production environments. - -IMPORTANT: It is expected that **only a trusted client** has access to the Stub Runner Boot server. You should not -run this application as a Fat Jar or a link:docker-project.html#docker-stubrunner[Docker Image] in untrusted locations. - -[[features-stub-runner-boot-server]] -=== Stub Runner Server - -To use the Stub Runner Server, add the following dependency: - -==== -[source,groovy,indent=0] ----- -compile "org.springframework.cloud:spring-cloud-starter-stub-runner" ----- -==== - -Then annotate a class with `@EnableStubRunnerServer`, build a fat jar, and it is ready to work. - -For the properties, see the <> section. - -[[features-stub-runner-boot-how-fat-jar]] -=== Stub Runner Server Fat Jar - -You can download a standalone JAR from Maven (for example, for version 2.0.1.RELEASE) -by running the following commands: - -==== -[source,bash,indent=0] ----- -$ wget -O stub-runner.jar 'https://search.maven.org/remotecontent?filepath=org/springframework/cloud/spring-cloud-contract-stub-runner-boot/2.0.1.RELEASE/spring-cloud-contract-stub-runner-boot-2.0.1.RELEASE.jar' -$ java -jar stub-runner.jar --stubrunner.ids=... --stubrunner.repositoryRoot=... ----- -==== - -[[features-stub-runner-boot-how-cli]] -=== Spring Cloud CLI - -Starting from the `1.4.0.RELEASE` version of the https://cloud.spring.io/spring-cloud-cli[Spring Cloud CLI] -project, you can start Stub Runner Boot by running `spring cloud stubrunner`. - -To pass the configuration, you can create a `stubrunner.yml` file in the current working directory, -in a subdirectory called `config`, or in `~/.spring-cloud`. The file could resemble the following -example for running stubs installed locally: - - -.stubrunner.yml -==== -[source,yml,indent=0] ----- -stubrunner: - stubsMode: LOCAL - ids: - - com.example:beer-api-producer:+:9876 ----- -==== - -Then you can call `spring cloud stubrunner` from your terminal window to start -the Stub Runner server. It is available at port `8750`. - -[[features-stub-runner-boot-endpoints]] -=== Endpoints - -Stub Runner Boot offers two endpoints: - -* <> -* <> - -[[features-stub-runner-boot-endpoints-http]] -==== HTTP - -For HTTP, Stub Runner Boot makes the following endpoints available: - -- GET `/stubs`: Returns a list of all running stubs in `ivy:integer` notation -- GET `/stubs/{ivy}`: Returns a port for the given `ivy` notation (when calling the endpoint `ivy` can also be `artifactId` only) - -[[features-stub-runner-boot-endpoints-messaging]] -==== Messaging - -For Messaging, Stub Runner Boot makes the following endpoints available: - -- GET `/triggers`: Returns a list of all running labels in `ivy : [ label1, label2 ...]` notation -- POST `/triggers/{label}`: Runs a trigger with `label` -- POST `/triggers/{ivy}/{label}`: Runs a trigger with a `label` for the given `ivy` notation -(when calling the endpoint, `ivy` can also be `artifactId` only) - -[[features-stub-runner-boot-endpoints-example]] -=== Example - -The following example shows typical usage of Stub Runner Boot: - -[source,groovy,indent=0] ----- -include::{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/server/StubRunnerBootSpec.groovy[tags=boot_usage] ----- - -[[features-stub-runner-boot-service-discovery]] -=== Stub Runner Boot with Service Discovery - -One way to use Stub Runner Boot is to use it as a feed of stubs for "`smoke tests`". What does that mean? -Assume that you do not want to deploy 50 microservices to a test environment in order -to see whether your application works. You have already run a suite of tests during the build process, -but you would also like to ensure that the packaging of your application works. You can -deploy your application to an environment, start it, and run a couple of tests on it to see whether -it works. We can call those tests "`smoke tests`", because their purpose is to check only a handful -of testing scenarios. - -The problem with this approach is that, if you use microservices, you most likely also -use a service discovery tool. Stub Runner Boot lets you solve this issue by starting the -required stubs and registering them in a service discovery tool. - -Now assume that we want to start this application so that the stubs get automatically registered. -We can do so by running the application with `java -jar ${SYSTEM_PROPS} stub-runner-boot-eureka-example.jar`, where -`${SYSTEM_PROPS}`. - -That way, your deployed application can send requests to started WireMock servers through service -discovery. Most likely, points 1 through 3 could be set by default in `application.yml`, because they are not -likely to change. That way, you can provide only the list of stubs to download whenever you start -the Stub Runner Boot. - -[[features-stub-runner-stubs-per-consumer]] -== Consumer-Driven Contracts: Stubs Per Consumer - -There are cases in which two consumers of the same endpoint want to have two different responses. - -TIP: This approach also lets you immediately know which consumer uses which part of your API. -You can remove part of a response that your API produces and see which of your autogenerated tests -fails. If none fails, you can safely delete that part of the response, because nobody uses it. - -Consider the following example of a contract defined for the producer called `producer`, -which has two consumers (`foo-consumer` and `bar-consumer`): - -==== -.Consumer `foo-service` -[source,groovy] ----- -request { - url '/foo' - method GET() -} -response { - status OK() - body( - foo: "foo" - } -} ----- - -.Consumer `bar-service` -[source,groovy] ----- -request { - url '/bar' - method GET() -} -response { - status OK() - body( - bar: "bar" - } -} ----- -==== - -You cannot produce two different responses for the same request. That is why you can properly package the -contracts and then profit from the `stubsPerConsumer` feature. - -On the producer side, the consumers can have a folder that contains contracts related only to them. -By setting the `stubrunner.stubs-per-consumer` flag to `true`, we no longer register all stubs but only those that -correspond to the consumer application's name. In other words, we scan the path of every stub and, -if it contains a subfolder with name of the consumer in the path, only then is it registered. - -On the `foo` producer side the contracts would look like this - -[source,bash] ----- -. -└── contracts - ├── bar-consumer - │   ├── bookReturnedForBar.groovy - │   └── shouldCallBar.groovy - └── foo-consumer - ├── bookReturnedForFoo.groovy - └── shouldCallFoo.groovy ----- - -The `bar-consumer` consumer can either set the `spring.application.name` or the `stubrunner.consumer-name` to `bar-consumer` -Alternatively, you can set the test as follows: - -==== -[source,groovy] ----- -include::{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/spring/cloud/StubRunnerStubsPerConsumerSpec.groovy[tags=test] -... -} ----- -==== - -Then only the stubs registered under a path that contains `bar-consumer` in its name (that is, those from the -`src/test/resources/contracts/bar-consumer/some/contracts/...` folder) are allowed to be referenced. - -You can also set the consumer name explicitly, as follows: - -==== -[source,groovy] ----- -include::{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/spring/cloud/StubRunnerStubsPerConsumerWithConsumerNameSpec.groovy[tags=test] -... -} ----- -==== - -Then only the stubs registered under a path that contains the `foo-consumer` in its name (that is, those from the -`src/test/resources/contracts/foo-consumer/some/contracts/...` folder) are allowed to be referenced. - -For more information about the reasons behind this change, -see https://github.com/spring-cloud/spring-cloud-contract/issues/224[issue 224]. - -[[features-stub-runner-stubs-protocol]] -== Fetching Stubs or Contract Definitions From A Location - -Instead of picking the stubs or contract definitions from -Artifactory, Nexus, or Git, you can point to -a location on a drive or the classpath. Doing so can be especially useful in a multi-module project, where one module wants -to reuse stubs or contracts from another module without -the need to actually install those in a local maven -repository to commit those changes to Git. - -In order to achieve this, you can use the `stubs://` -protocol when the repository root parameter is set either -in Stub Runner or in a Spring Cloud Contract plugin. - -In this example, the `producer` project has been successfully -built and stubs were generated under the `target/stubs` folder. As a consumer, one can set up the Stub Runner to pick the stubs from that location by using the `stubs://` protocol. - -==== -[source,java,indent=0,subs="verbatim,attributes",role="primary"] -.Annotation ----- -@AutoConfigureStubRunner( -stubsMode = StubRunnerProperties.StubsMode.REMOTE, - repositoryRoot = "stubs://file://location/to/the/producer/target/stubs/", - ids = "com.example:some-producer") ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.JUnit 4 Rule ----- -@Rule - public StubRunnerRule rule = new StubRunnerRule() - .downloadStub("com.example:some-producer") - .repoRoot("stubs://file://location/to/the/producer/target/stubs/") - .stubsMode(StubRunnerProperties.StubsMode.REMOTE); ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.JUnit 5 Extension ----- -@RegisterExtension - public StubRunnerExtension stubRunnerExtension = new StubRunnerExtension() - .downloadStub("com.example:some-producer") - .repoRoot("stubs://file://location/to/the/producer/target/stubs/") - .stubsMode(StubRunnerProperties.StubsMode.REMOTE); ----- -==== - -Contracts and stubs may be stored in a location, where each producer has its own, dedicated folder for contracts and stub mappings. Under that folder, each consumer can have its own setup. To make Stub Runner find the dedicated folder from the provided IDs, you can pass the `stubs.find-producer=true` property or the `stubrunner.stubs.find-producer=true` system property. -The following listing shows an arrangement of contracts and stubs: - -==== -[source,bash,indent=0] ----- -└── com.example <1> - ├── some-artifact-id <2> - │   └── 0.0.1 - │   ├── contracts <3> - │   │   └── shouldReturnStuffForArtifactId.groovy - │   └── mappings <4> - │   └── shouldReturnStuffForArtifactId.json - └── some-other-artifact-id <5> - ├── contracts - │   └── shouldReturnStuffForOtherArtifactId.groovy - └── mappings - └── shouldReturnStuffForOtherArtifactId.json - ----- -<1> group ID of the consumers -<2> consumer with artifact id [some-artifact-id] -<3> contracts for the consumer with artifact id [some-artifact-id] -<4> mappings for the consumer with artifact id [some-artifact-id] -<5> consumer with artifact id [some-other-artifact-id] -==== - -==== -[source,java,indent=0,subs="verbatim,attributes",role="primary"] -.Annotation ----- -@AutoConfigureStubRunner( -stubsMode = StubRunnerProperties.StubsMode.REMOTE, - repositoryRoot = "stubs://file://location/to/the/contracts/directory", - ids = "com.example:some-producer", - properties="stubs.find-producer=true") ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.JUnit 4 Rule ----- - static Map contractProperties() { - Map map = new HashMap<>(); - map.put("stubs.find-producer", "true"); - return map; - } - -@Rule - public StubRunnerRule rule = new StubRunnerRule() - .downloadStub("com.example:some-producer") - .repoRoot("stubs://file://location/to/the/contracts/directory") - .stubsMode(StubRunnerProperties.StubsMode.REMOTE) - .properties(contractProperties()); ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.JUnit 5 Extension ----- - static Map contractProperties() { - Map map = new HashMap<>(); - map.put("stubs.find-producer", "true"); - return map; - } - -@RegisterExtension - public StubRunnerExtension stubRunnerExtension = new StubRunnerExtension() - .downloadStub("com.example:some-producer") - .repoRoot("stubs://file://location/to/the/contracts/directory") - .stubsMode(StubRunnerProperties.StubsMode.REMOTE) - .properties(contractProperties()); ----- -==== - -[[features-stub-runner-generate-stubs-at-runtime]] -== Generating Stubs at Runtime - -As a consumer, you might not want to wait for the producer to finish its implementation and then publish their stubs. A solution to this problem can be generation of stubs at runtime. - -As a producer, when a contract is defined, you are required to make the generated tests pass in order for the stubs to be published. There are cases where you would like to unblock the consumers so that they can fetch the stubs before your tests actually pass. In this case, you should set such contracts as in-progress. You can read more about this under the <> section. That way, your tests are not generated, but the stubs are generated. - -As a consumer, you can toggle a switch to generate stubs at runtime. Stub Runner ignores all the existing stub mappings and generates new ones for all the contract definitions. Another option is to pass the `stubrunner.generate-stubs` system property. The following example shows such a setup: - -==== -[source,java,indent=0,subs="verbatim,attributes",role="primary"] -.Annotation ----- -@AutoConfigureStubRunner( -stubsMode = StubRunnerProperties.StubsMode.REMOTE, - repositoryRoot = "stubs://file://location/to/the/contracts", - ids = "com.example:some-producer", - generateStubs = true) ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.JUnit 4 Rule ----- -@Rule - public StubRunnerRule rule = new StubRunnerRule() - .downloadStub("com.example:some-producer") - .repoRoot("stubs://file://location/to/the/contracts") - .stubsMode(StubRunnerProperties.StubsMode.REMOTE) - .withGenerateStubs(true); ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.JUnit 5 Extension ----- -@RegisterExtension - public StubRunnerExtension stubRunnerExtension = new StubRunnerExtension() - .downloadStub("com.example:some-producer") - .repoRoot("stubs://file://location/to/the/contracts") - .stubsMode(StubRunnerProperties.StubsMode.REMOTE) - .withGenerateStubs(true); ----- -==== - -[[features-stub-runner-fail-on-no-stubs]] -== Fail On No Stubs - -By default, Stub Runner will fail if no stubs are found. In order to change that behavior, set the `failOnNoStubs` property to `false` in the annotation or call the `withFailOnNoStubs(false)` method on a JUnit Rule or Extension. The following example shows how to do so: - -==== -[source,java,indent=0,subs="verbatim,attributes",role="primary"] -.Annotation ----- -@AutoConfigureStubRunner( -stubsMode = StubRunnerProperties.StubsMode.REMOTE, - repositoryRoot = "stubs://file://location/to/the/contracts", - ids = "com.example:some-producer", - failOnNoStubs = false) ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.JUnit 4 Rule ----- -@Rule - public StubRunnerRule rule = new StubRunnerRule() - .downloadStub("com.example:some-producer") - .repoRoot("stubs://file://location/to/the/contracts") - .stubsMode(StubRunnerProperties.StubsMode.REMOTE) - .withFailOnNoStubs(false); ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.JUnit 5 Extension ----- -@RegisterExtension - public StubRunnerExtension stubRunnerExtension = new StubRunnerExtension() - .downloadStub("com.example:some-producer") - .repoRoot("stubs://file://location/to/the/contracts") - .stubsMode(StubRunnerProperties.StubsMode.REMOTE) - .withFailOnNoStubs(false); ----- -==== - -[[features-stub-runner-common]] -== Common Properties - -This section briefly describes common properties, including: - -* <> -* <> - -[[features-stub-runner-common-properties-junit-spring]] -=== Common Properties for JUnit and Spring - -You can set repetitive properties by using system properties or Spring configuration -properties. The following table shows their names with their default values: - -[frame="topbot",options="header"] -|=============== -| Property name | Default value | Description -|`stubrunner.minPort`|`10000`| Minimum value of a port for a started WireMock with stubs. -|`stubrunner.maxPort`|`15000`| Maximum value of a port for a started WireMock with stubs. -|`stubrunner.repositoryRoot`|| Maven repository URL. If blank, then call the local Maven repo. -|`stubrunner.classifier`|`stubs`| Default classifier for the stub artifacts. -|`stubrunner.stubsMode`|`CLASSPATH`| The way you want to fetch and register the stubs. -|`stubrunner.ids`|| Array of Ivy notation stubs to download. -|`stubrunner.username`|| Optional username to access the tool that stores the JARs with -stubs. -|`stubrunner.password`|| Optional password to access the tool that stores the JARs with -stubs. -|`stubrunner.stubsPerConsumer`|`false`| Set to `true` if you want to use different stubs for -each consumer instead of registering all stubs for every consumer. -|`stubrunner.consumerName`|| If you want to use a stub for each consumer and want to -override the consumer name, change this value. -|=============== - -[[features-stub-runner-stub-runner-stub-ids]] -=== Stub Runner Stubs IDs - -You can set the stubs to download in the `stubrunner.ids` system property. They -use the following pattern: - -==== -[source,java,indent=0] ----- -groupId:artifactId:version:classifier:port ----- -==== - -Note that `version`, `classifier`, and `port` are optional. - -* If you do not provide the `port`, a random one is picked. -* If you do not provide the `classifier`, the default is used. (Note that you can -pass an empty classifier this way: `groupId:artifactId:version:`). -* If you do not provide the `version`, then `+` is passed, and the latest one is -downloaded. - -`port` means the port of the WireMock server. - -IMPORTANT: Starting with version 1.0.4, you can provide a range of versions that you -would like the Stub Runner to take into consideration. You can read more about the -Aether versioning ranges -https://wiki.eclipse.org/Aether/New_and_Noteworthy#Version_Ranges[here]. diff --git a/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-boot.adoc b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-boot.adoc new file mode 100644 index 0000000000..e63b13a26f --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-boot.adoc @@ -0,0 +1,131 @@ +[[features-stub-runner-boot]] += Using the Stub Runner Boot Application + +Spring Cloud Contract Stub Runner Boot is a Spring Boot application that exposes REST endpoints to +trigger the messaging labels and to access WireMock servers. + +[[features-stub-runner-boot-security]] +== Stub Runner Boot Security + +The Stub Runner Boot application is not secured by design - securing it would require to add security to all +stubs even if they don't actually require it. Since this is a testing utility - the server is **not intended** +to be used in production environments. + +IMPORTANT: It is expected that **only a trusted client** has access to the Stub Runner Boot server. You should not +run this application as a Fat Jar or a link:docker-project.html#docker-stubrunner[Docker Image] in untrusted locations. + +[[features-stub-runner-boot-server]] +== Stub Runner Server + +To use the Stub Runner Server, add the following dependency: + +==== +[source,groovy,indent=0] +---- +compile "org.springframework.cloud:spring-cloud-starter-stub-runner" +---- +==== + +Then annotate a class with `@EnableStubRunnerServer`, build a fat jar, and it is ready to work. + +For the properties, see the <> section. + +[[features-stub-runner-boot-how-fat-jar]] +== Stub Runner Server Fat Jar + +You can download a standalone JAR from Maven (for example, for version 2.0.1.RELEASE) +by running the following commands: + +==== +[source,bash,indent=0] +---- +$ wget -O stub-runner.jar 'https://search.maven.org/remotecontent?filepath=org/springframework/cloud/spring-cloud-contract-stub-runner-boot/2.0.1.RELEASE/spring-cloud-contract-stub-runner-boot-2.0.1.RELEASE.jar' +$ java -jar stub-runner.jar --stubrunner.ids=... --stubrunner.repositoryRoot=... +---- +==== + +[[features-stub-runner-boot-how-cli]] +== Spring Cloud CLI + +Starting from the `1.4.0.RELEASE` version of the https://cloud.spring.io/spring-cloud-cli[Spring Cloud CLI] +project, you can start Stub Runner Boot by running `spring cloud stubrunner`. + +To pass the configuration, you can create a `stubrunner.yml` file in the current working directory, +in a subdirectory called `config`, or in `~/.spring-cloud`. The file could resemble the following +example for running stubs installed locally: + + +.stubrunner.yml +==== +[source,yml,indent=0] +---- +stubrunner: + stubsMode: LOCAL + ids: + - com.example:beer-api-producer:+:9876 +---- +==== + +Then you can call `spring cloud stubrunner` from your terminal window to start +the Stub Runner server. It is available at port `8750`. + +[[features-stub-runner-boot-endpoints]] +== Endpoints + +Stub Runner Boot offers two endpoints: + +* <> +* <> + +[[features-stub-runner-boot-endpoints-http]] +=== HTTP + +For HTTP, Stub Runner Boot makes the following endpoints available: + +- GET `/stubs`: Returns a list of all running stubs in `ivy:integer` notation +- GET `/stubs/{ivy}`: Returns a port for the given `ivy` notation (when calling the endpoint `ivy` can also be `artifactId` only) + +[[features-stub-runner-boot-endpoints-messaging]] +=== Messaging + +For Messaging, Stub Runner Boot makes the following endpoints available: + +- GET `/triggers`: Returns a list of all running labels in `ivy : [ label1, label2 ...]` notation +- POST `/triggers/{label}`: Runs a trigger with `label` +- POST `/triggers/{ivy}/{label}`: Runs a trigger with a `label` for the given `ivy` notation +(when calling the endpoint, `ivy` can also be `artifactId` only) + +[[features-stub-runner-boot-endpoints-example]] +== Example + +The following example shows typical usage of Stub Runner Boot: + +[source,groovy,indent=0] +---- +include:../:{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/server/StubRunnerBootSpec.groovy[tags=boot_usage] +---- + +[[features-stub-runner-boot-service-discovery]] +== Stub Runner Boot with Service Discovery + +One way to use Stub Runner Boot is to use it as a feed of stubs for "`smoke tests`". What does that mean? +Assume that you do not want to deploy 50 microservices to a test environment in order +to see whether your application works. You have already run a suite of tests during the build process, +but you would also like to ensure that the packaging of your application works. You can +deploy your application to an environment, start it, and run a couple of tests on it to see whether +it works. We can call those tests "`smoke tests`", because their purpose is to check only a handful +of testing scenarios. + +The problem with this approach is that, if you use microservices, you most likely also +use a service discovery tool. Stub Runner Boot lets you solve this issue by starting the +required stubs and registering them in a service discovery tool. + +Now assume that we want to start this application so that the stubs get automatically registered. +We can do so by running the application with `java -jar ${SYSTEM_PROPS} stub-runner-boot-eureka-example.jar`, where +`${SYSTEM_PROPS}`. + +That way, your deployed application can send requests to started WireMock servers through service +discovery. Most likely, points 1 through 3 could be set by default in `application.yml`, because they are not +likely to change. That way, you can provide only the list of stubs to download whenever you start +the Stub Runner Boot. + diff --git a/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-cloud.adoc b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-cloud.adoc new file mode 100644 index 0000000000..70be63c9a6 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-cloud.adoc @@ -0,0 +1,63 @@ +[[features-stub-runner-cloud]] += Stub Runner Spring Cloud + +Stub Runner can integrate with Spring Cloud. + +For real life examples, see: + +- https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/{samples_branch}/producer[The producer application sample] +- https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/{samples_branch}/consumer_with_discovery[The consumer application sample] + +[[features-stub-runner-cloud-stubbing-discovery]] +== Stubbing Service Discovery + +The most important feature of `Stub Runner Spring Cloud` is the fact that it stubs: + +- `DiscoveryClient` +- `ReactorServiceInstanceLoadBalancer` + +That means that, regardless of whether you use Zookeeper, Consul, Eureka, or anything +else, you do not need that in your tests. We are starting WireMock instances of your +dependencies and we are telling your application, whenever you use `Feign`, to load a +balanced `RestTemplate` or `DiscoveryClient` directly, to call those stubbed servers +instead of calling the real Service Discovery tool. + +[[features-stub-runner-cloud-stubbing-profiles]] +=== Test Profiles and Service Discovery + +In your integration tests, you typically do not want to call either a discovery service (such as Eureka) +or Config Server. That is why you create an additional test configuration in which you want to disable +these features. + +Due to certain limitations of https://github.com/spring-cloud/spring-cloud-commons/issues/156[`spring-cloud-commons`], +to achieve this, you have to disable these properties +in a static block such as the following example (for Eureka): + +==== +[source,java] +---- + //Hack to work around https://github.com/spring-cloud/spring-cloud-commons/issues/156 + static { + System.setProperty("eureka.client.enabled", "false"); + System.setProperty("spring.cloud.config.failFast", "false"); + } +---- +==== + +[[features-stub-runner-additional-config]] +== Additional Configuration + +You can match the `artifactId` of the stub with the name of your application by using the `stubrunner.idsToServiceIds:` map. + +TIP: By default, all service discovery is stubbed. This means that, regardless of whether you have +an existing `DiscoveryClient`, its results are ignored. However, if you want to reuse it, you can set + `stubrunner.cloud.delegate.enabled` to `true`, and then your existing `DiscoveryClient` results are + merged with the stubbed ones. + +The default Maven configuration used by Stub Runner can be tweaked either +by setting the following system properties or by setting the corresponding environment variables: + +- `maven.repo.local`: Path to the custom maven local repository location +- `org.apache.maven.user-settings`: Path to custom maven user settings location +- `org.apache.maven.global-settings`: Path to maven global settings location + diff --git a/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-common.adoc b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-common.adoc new file mode 100644 index 0000000000..3f789dfe04 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-common.adoc @@ -0,0 +1,60 @@ +[[features-stub-runner-common]] += Common Properties + +This section briefly describes common properties, including: + +* <> +* <> + +[[features-stub-runner-common-properties-junit-spring]] +== Common Properties for JUnit and Spring + +You can set repetitive properties by using system properties or Spring configuration +properties. The following table shows their names with their default values: + +[frame="topbot",options="header"] +|=============== +| Property name | Default value | Description +|`stubrunner.minPort`|`10000`| Minimum value of a port for a started WireMock with stubs. +|`stubrunner.maxPort`|`15000`| Maximum value of a port for a started WireMock with stubs. +|`stubrunner.repositoryRoot`|| Maven repository URL. If blank, then call the local Maven repo. +|`stubrunner.classifier`|`stubs`| Default classifier for the stub artifacts. +|`stubrunner.stubsMode`|`CLASSPATH`| The way you want to fetch and register the stubs. +|`stubrunner.ids`|| Array of Ivy notation stubs to download. +|`stubrunner.username`|| Optional username to access the tool that stores the JARs with +stubs. +|`stubrunner.password`|| Optional password to access the tool that stores the JARs with +stubs. +|`stubrunner.stubsPerConsumer`|`false`| Set to `true` if you want to use different stubs for +each consumer instead of registering all stubs for every consumer. +|`stubrunner.consumerName`|| If you want to use a stub for each consumer and want to +override the consumer name, change this value. +|=============== + +[[features-stub-runner-stub-runner-stub-ids]] +== Stub Runner Stubs IDs + +You can set the stubs to download in the `stubrunner.ids` system property. They +use the following pattern: + +==== +[source,java,indent=0] +---- +groupId:artifactId:version:classifier:port +---- +==== + +Note that `version`, `classifier`, and `port` are optional. + +* If you do not provide the `port`, a random one is picked. +* If you do not provide the `classifier`, the default is used. (Note that you can +pass an empty classifier this way: `groupId:artifactId:version:`). +* If you do not provide the `version`, then `+` is passed, and the latest one is +downloaded. + +`port` means the port of the WireMock server. + +IMPORTANT: Starting with version 1.0.4, you can provide a range of versions that you +would like the Stub Runner to take into consideration. You can read more about the +Aether versioning ranges +https://wiki.eclipse.org/Aether/New_and_Noteworthy#Version_Ranges[here]. diff --git a/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-core.adoc b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-core.adoc new file mode 100644 index 0000000000..26902d077b --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-core.adoc @@ -0,0 +1,304 @@ +[[features-stub-runner-core]] += Stub Runner Core + +The stub runner core runs stubs for service collaborators. Treating stubs as contracts of +services lets you use stub-runner as an implementation of +https://martinfowler.com/articles/consumerDrivenContracts.html[Consumer-driven Contracts]. + +Stub Runner lets you automatically download the stubs of the provided dependencies (or +pick those from the classpath), start WireMock servers for them, and feed them with proper +stub definitions. For messaging, special stub routes are defined. + +[[features-stub-runner-retrieving]] +== Retrieving stubs + +You can pick from the following options of acquiring stubs: + +- Aether-based solution that downloads JARs with stubs from Artifactory or Nexus +- Classpath-scanning solution that searches the classpath with a pattern to retrieve stubs +- Writing your own implementation of the `org.springframework.cloud.contract.stubrunner.StubDownloaderBuilder` for full customization + +The latter example is described in the <> section. + +[[features-stub-runner-downloading-stub]] +=== Downloading Stubs + +You can control the downloading of stubs with the `stubsMode` switch. It picks value from the +`StubRunnerProperties.StubsMode` enumeration. You can use the following options: + +- `StubRunnerProperties.StubsMode.CLASSPATH` (default value): Picks stubs from the classpath +- `StubRunnerProperties.StubsMode.LOCAL`: Picks stubs from a local storage (for example, `.m2`) +- `StubRunnerProperties.StubsMode.REMOTE`: Picks stubs from a remote location + +The following example picks stubs from a local location: + +==== +[source,java] +---- +@AutoConfigureStubRunner(repositoryRoot="https://foo.bar", ids = "com.example:beer-api-producer:+:stubs:8095", stubsMode = StubRunnerProperties.StubsMode.LOCAL) +---- +==== + +[[features-stub-runner-classpath-scanning]] +=== Classpath scanning + +If you set the `stubsMode` property to `StubRunnerProperties.StubsMode.CLASSPATH` +(or set nothing since `CLASSPATH` is the default value), the classpath is scanned. +Consider the following example: + +==== +[source,java] +---- +@AutoConfigureStubRunner(ids = { + "com.example:beer-api-producer:+:stubs:8095", + "com.example.foo:bar:1.0.0:superstubs:8096" +}) +---- +==== + +You can add the dependencies to your classpath, as follows: + +==== +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven +---- + + com.example + beer-api-producer-restdocs + stubs + 0.0.1-SNAPSHOT + test + + + * + * + + + + + com.example.thing1 + thing2 + superstubs + 1.0.0 + test + + + * + * + + + +---- + +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle +---- +testCompile("com.example:beer-api-producer-restdocs:0.0.1-SNAPSHOT:stubs") { + transitive = false +} +testCompile("com.example.thing1:thing2:1.0.0:superstubs") { + transitive = false +} +---- +==== + +Then the specified locations on your classpath get scanned. For `com.example:beer-api-producer-restdocs`, +the following locations are scanned: + +- /META-INF/com.example/beer-api-producer-restdocs/**/*.* +- /contracts/com.example/beer-api-producer-restdocs/**/*.* +- /mappings/com.example/beer-api-producer-restdocs/**/*.* + +For `com.example.thing1:thing2`, the following locations are scanned: + +- /META-INF/com.example.thing1/thing2/**/*.* +- /contracts/com.example.thing1/thing2/**/*.* +- /mappings/com.example.thing1/thing2/**/*.* + +TIP: You have to explicitly provide the group and artifact IDs when you package the +producer stubs. + +To achieve proper stub packaging, the producer would set up the contracts as follows: + +==== +[source,bash] +---- +└── src + └── test + └── resources + └── contracts +    └── com.example +       └── beer-api-producer-restdocs +       └── nested +       └── contract3.groovy + +---- +==== + +By using the https://github.com/spring-cloud-samples/spring-cloud-contract-samples/blob/{samples_branch}/producer_with_restdocs/pom.xml[Maven `assembly` plugin] or the +https://github.com/spring-cloud-samples/spring-cloud-contract-samples/blob/{samples_branch}/producer_with_restdocs/build.gradle[Gradle Jar] task, you have to create the following +structure in your stubs jar: + +==== +[source,bash] +---- +└── META-INF + └── com.example + └── beer-api-producer-restdocs + └── 2.0.0 + ├── contracts + │   └── nested +    │ └── contract2.groovy +    └── mappings +    └── mapping.json + +---- +==== + +By maintaining this structure, the classpath gets scanned and you can profit from the messaging or +HTTP stubs without the need to download artifacts. + +[[features-stub-runner-configuring-http-server-stubs]] +=== Configuring HTTP Server Stubs + +Stub Runner has a notion of a `HttpServerStub` that abstracts the underlying +concrete implementation of the HTTP server (for example, WireMock is one of the implementations). +Sometimes, you need to perform some additional tuning (which is concrete for the given implementation) of the stub servers. +To do that, Stub Runner gives you +the `httpServerStubConfigurer` property that is available in the annotation and the +JUnit rule and is accessible through system properties, where you can provide +your implementation of the `org.springframework.cloud.contract.stubrunner.HttpServerStubConfigurer` +interface. The implementations can alter +the configuration files for the given HTTP server stub. + +Spring Cloud Contract Stub Runner comes with an implementation that you +can extend for WireMock: +`org.springframework.cloud.contract.stubrunner.provider.wiremock.WireMockHttpServerStubConfigurer`. +In the `configure` method, +you can provide your own custom configuration for the given stub. The use +case might be starting WireMock for the given artifact ID, on an HTTPS port. The following +example shows how to do so: + +.WireMockHttpServerStubConfigurer implementation +==== +[source,groovy,indent=0] +---- +include:../:{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/spring/StubRunnerConfigurationSpec.groovy[tags=wireMockHttpServerStubConfigurer] +---- +==== + +You can then reuse it with the `@AutoConfigureStubRunner` annotation, as follows: + +==== +[source,groovy,indent=0] +---- +include:../:{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/spring/StubRunnerConfigurationSpec.groovy[tags=annotation] +---- +==== + +Whenever an HTTPS port is found, it takes precedence over the HTTP port. + +[[features-stub-runner-running-stubs]] +== Running stubs + +This section describes how to run stubs. It contains the following topics: + +* <> +* <> +* <> + +[[features-stub-runner-http-stubs]] +=== HTTP Stubs + +Stubs are defined in JSON documents, whose syntax is defined in the http://wiremock.org/stubbing.html[WireMock documentation]. + +The following example defines a stub in JSON: + +==== +[source,javascript,indent=0] +---- +{ + "request": { + "method": "GET", + "url": "/ping" + }, + "response": { + "status": 200, + "body": "pong", + "headers": { + "Content-Type": "text/plain" + } + } +} +---- +==== + +[[features-stub-runner-viewing]] +=== Viewing Registered Mappings + +Every stubbed collaborator exposes a list of defined mappings under the `__/admin/` endpoint. + +You can also use the `mappingsOutputFolder` property to dump the mappings to files. +For the annotation-based approach, it would resembling the following example: + +==== +[source,java] +---- +@AutoConfigureStubRunner(ids="a.b.c:loanIssuance,a.b.c:fraudDetectionServer", +mappingsOutputFolder = "target/outputmappings/") +---- +==== + +For the JUnit approach, it resembles the following example: + +==== +[source,java] +---- +@ClassRule @Shared StubRunnerRule rule = new StubRunnerRule() + .repoRoot("https://some_url") + .downloadStub("a.b.c", "loanIssuance") + .downloadStub("a.b.c:fraudDetectionServer") + .withMappingsOutputFolder("target/outputmappings") +---- +==== + +Then, if you check out the `target/outputmappings` folder, you would see the following structure; + +==== +[source,bash] +---- +. +├── fraudDetectionServer_13705 +└── loanIssuance_12255 +---- +==== + +That means that there were two stubs registered. `fraudDetectionServer` was registered at port `13705` +and `loanIssuance` at port `12255`. If we take a look at one of the files, we would see (for WireMock) +the mappings available for the given server: + +==== +[source,json] +---- +[{ + "id" : "f9152eb9-bf77-4c38-8289-90be7d10d0d7", + "request" : { + "url" : "/name", + "method" : "GET" + }, + "response" : { + "status" : 200, + "body" : "fraudDetectionServer" + }, + "uuid" : "f9152eb9-bf77-4c38-8289-90be7d10d0d7" +}, +... +] +---- +==== + +[[features-stub-runner-messaging]] +=== Messaging Stubs + +Depending on the provided Stub Runner dependency and the DSL, the messaging routes are automatically set up. + diff --git a/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-fail-on-no-stubs.adoc b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-fail-on-no-stubs.adoc new file mode 100644 index 0000000000..3480c144f3 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-fail-on-no-stubs.adoc @@ -0,0 +1,39 @@ +[[features-stub-runner-fail-on-no-stubs]] += Fail On No Stubs + +By default, Stub Runner will fail if no stubs are found. In order to change that behavior, set the `failOnNoStubs` property to `false` in the annotation or call the `withFailOnNoStubs(false)` method on a JUnit Rule or Extension. The following example shows how to do so: + +==== +[source,java,indent=0,subs="verbatim,attributes",role="primary"] +.Annotation +---- +@AutoConfigureStubRunner( +stubsMode = StubRunnerProperties.StubsMode.REMOTE, + repositoryRoot = "stubs://file://location/to/the/contracts", + ids = "com.example:some-producer", + failOnNoStubs = false) +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.JUnit 4 Rule +---- +@Rule + public StubRunnerRule rule = new StubRunnerRule() + .downloadStub("com.example:some-producer") + .repoRoot("stubs://file://location/to/the/contracts") + .stubsMode(StubRunnerProperties.StubsMode.REMOTE) + .withFailOnNoStubs(false); +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.JUnit 5 Extension +---- +@RegisterExtension + public StubRunnerExtension stubRunnerExtension = new StubRunnerExtension() + .downloadStub("com.example:some-producer") + .repoRoot("stubs://file://location/to/the/contracts") + .stubsMode(StubRunnerProperties.StubsMode.REMOTE) + .withFailOnNoStubs(false); +---- +==== + diff --git a/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-generate-stubs-at-runtime.adoc b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-generate-stubs-at-runtime.adoc new file mode 100644 index 0000000000..e0c884de6a --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-generate-stubs-at-runtime.adoc @@ -0,0 +1,43 @@ +[[features-stub-runner-generate-stubs-at-runtime]] += Generating Stubs at Runtime + +As a consumer, you might not want to wait for the producer to finish its implementation and then publish their stubs. A solution to this problem can be generation of stubs at runtime. + +As a producer, when a contract is defined, you are required to make the generated tests pass in order for the stubs to be published. There are cases where you would like to unblock the consumers so that they can fetch the stubs before your tests actually pass. In this case, you should set such contracts as in-progress. You can read more about this under the <> section. That way, your tests are not generated, but the stubs are generated. + +As a consumer, you can toggle a switch to generate stubs at runtime. Stub Runner ignores all the existing stub mappings and generates new ones for all the contract definitions. Another option is to pass the `stubrunner.generate-stubs` system property. The following example shows such a setup: + +==== +[source,java,indent=0,subs="verbatim,attributes",role="primary"] +.Annotation +---- +@AutoConfigureStubRunner( +stubsMode = StubRunnerProperties.StubsMode.REMOTE, + repositoryRoot = "stubs://file://location/to/the/contracts", + ids = "com.example:some-producer", + generateStubs = true) +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.JUnit 4 Rule +---- +@Rule + public StubRunnerRule rule = new StubRunnerRule() + .downloadStub("com.example:some-producer") + .repoRoot("stubs://file://location/to/the/contracts") + .stubsMode(StubRunnerProperties.StubsMode.REMOTE) + .withGenerateStubs(true); +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.JUnit 5 Extension +---- +@RegisterExtension + public StubRunnerExtension stubRunnerExtension = new StubRunnerExtension() + .downloadStub("com.example:some-producer") + .repoRoot("stubs://file://location/to/the/contracts") + .stubsMode(StubRunnerProperties.StubsMode.REMOTE) + .withGenerateStubs(true); +---- +==== + diff --git a/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-junit.adoc b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-junit.adoc new file mode 100644 index 0000000000..60cb487e84 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-junit.adoc @@ -0,0 +1,167 @@ +[[features-stub-runner-junit]] += Stub Runner JUnit Rule and Stub Runner JUnit5 Extension + +Stub Runner comes with a JUnit rule that lets you can download and run stubs for a given +group and artifact ID, as the following example shows: + +==== +[source,java,indent=0] +---- +include:../:{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/junit4/StubRunnerRuleJUnitTest.java[tags=classrule] +---- +==== + +A `StubRunnerExtension` is also available for JUnit 5. `StubRunnerRule` and +`StubRunnerExtension` work in a very similar fashion. After the rule or extension is +called, Stub Runner connects to your Maven repository and, for the given list of +dependencies, tries to: + +- Download them +- Cache them locally +- Unzip them to a temporary folder +- Start a WireMock server for each Maven dependency on a random port from the provided +range of ports or the provided port +- Feed the WireMock server with all JSON files that are valid WireMock definitions +- Send messages (remember to pass an implementation of `MessageVerifierSender` interface) + +Stub Runner uses the https://wiki.eclipse.org/Aether[Eclipse Aether] mechanism to download the Maven dependencies. +Check their https://wiki.eclipse.org/Aether[docs] for more information. + +Since the `StubRunnerRule` and `StubRunnerExtension` implement the `StubFinder`, they let +you find the started stubs, as the following example shows: + +==== +[source,groovy,indent=0] +---- +include:../:{stubrunner_core_path}/src/main/java/org/springframework/cloud/contract/stubrunner/StubFinder.java[lines=16..-1] +---- +==== + +The following examples provide more detail about using Stub Runner: + +==== +[source,groovy,indent=0,subs="verbatim,attributes",role="primary"] +.Spock +---- +include:../:{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/junit4/StubRunnerRuleSpec.groovy[tags=classrule] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Junit 4 +---- +include:../:{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/junit4/StubRunnerRuleJUnitTest.java[tags=test] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Junit 5 +---- +include:../:{stubrunner_core_path}/src/test/java/org/springframework/cloud/contract/stubrunner/junit/StubRunnerJUnit5ExtensionTests.java[tags=extension] +---- +==== + +See the <> for more information on +how to apply global configuration of Stub Runner. + +IMPORTANT: To use the JUnit rule or JUnit 5 extension together with messaging, you have to provide an implementation of the +`MessageVerifierSender` and `MessageVerifierReceiver` interface to the rule builder (for example, `rule.messageVerifierSender(new MyMessageVerifierSender())`). +If you do not do this, then, whenever you try to send a message, an exception is thrown. + +[[features-stub-runner-rule-maven-settings]] +== Maven Settings + +The stub downloader honors Maven settings for a different local repository folder. +Authentication details for repositories and profiles are currently not taken into account, +so you need to specify it by using the properties mentioned above. + +[[features-stub-runner-rule-fixed-ports]] +== Providing Fixed Ports + +You can also run your stubs on fixed ports. You can do it in two different ways. +One is to pass it in the properties, and the other is to use the fluent API of +JUnit rule. + +[[features-stub-runner-rule-fluent-api]] +== Fluent API + +When using the `StubRunnerRule` or `StubRunnerExtension`, you can add a stub to download +and then pass the port for the last downloaded stub. The following example shows how to do so: + +==== +[source,java,indent=0] +---- +include:../:{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/junit4/StubRunnerRuleCustomPortJUnitTest.java[tags=classrule_with_port] +---- +==== + +For the preceding example, the following test is valid: + +==== +[source,java,indent=0] +---- +include:../:{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/junit4/StubRunnerRuleCustomPortJUnitTest.java[tags=test_with_port] +---- +==== + +[[features-stub-runner-rule-spring]] +== Stub Runner with Spring + +Stub Runner with Spring sets up Spring configuration of the Stub Runner project. + +By providing a list of stubs inside your configuration file, Stub Runner automatically downloads +and registers in WireMock the selected stubs. + +If you want to find the URL of your stubbed dependency, you can autowire the `StubFinder` interface and use +its methods, as follows: + +==== +[source,groovy,indent=0] +---- +include:../:{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/spring/StubRunnerConfigurationSpec.groovy[tags=test] +---- +==== + +Doing so depends on the following configuration file: + +==== +[source,yml,indent=0] +---- +include:../:{stubrunner_core_path}/src/test/resources/application-test.yml[tags=test] +---- +==== + +Instead of using the properties, you can also use the properties inside the `@AutoConfigureStubRunner`. +The following example achieves the same result by setting values on the annotation: + +==== +[source,groovy,indent=0] +---- +include:../:{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/spring/cloud/consul/StubRunnerSpringCloudConsulAutoConfigurationSpec.groovy[tags=autoconfigure] +---- +==== + +Stub Runner Spring registers environment variables in the following manner +for every registered WireMock server. The following example shows Stub Runner IDs for +`com.example:thing1` and `com.example:thing2`: + +- `stubrunner.runningstubs.thing1.port` +- `stubrunner.runningstubs.com.example.thing1.port` +- `stubrunner.runningstubs.thing2.port` +- `stubrunner.runningstubs.com.example.thing2.port` + +You can reference these values in your code. + +You can also use the `@StubRunnerPort` annotation to inject the port of a running stub. +The value of the annotation can be the `groupid:artifactid` or only the `artifactid`. +The following example works shows Stub Runner IDs for +`com.example:thing1` and `com.example:thing2`. + +==== +[source,java,indent=0] +---- +@StubRunnerPort("thing1") +int thing1Port; +@StubRunnerPort("com.example:thing2") +int thing2Port; +---- +==== + diff --git a/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-publishing-stubs-as-jars.adoc b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-publishing-stubs-as-jars.adoc new file mode 100644 index 0000000000..3e12070ae2 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-publishing-stubs-as-jars.adoc @@ -0,0 +1,32 @@ +[[features-stub-runner-publishing-stubs-as-jars]] += Publishing Stubs as JARs + +The easiest approach to publishing stubs as jars is to centralize the way stubs are kept. +For example, you can keep them as jars in a Maven repository. + +TIP: For both Maven and Gradle, the setup comes ready to work. However, you can customize +it if you want to. + +The following example shows how to publish stubs as jars: + +==== +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven +---- + +include:../:{samples_url}/producer_with_restdocs/pom.xml[tags=skip_jar,indent=0] + + +include:../:{samples_url}/producer_with_restdocs/pom.xml[tags=assembly,indent=0] + + +include:../:{samples_url}/producer_with_restdocs/src/assembly/stub.xml[indent=0] +---- + +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle +---- +include:../:{plugins_path}/spring-cloud-contract-gradle-plugin/src/test/resources/functionalTest/scenarioProject/build.gradle[tags=jar_setup,indent=0] +---- +==== + diff --git a/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-snapshot-versions.adoc b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-snapshot-versions.adoc new file mode 100644 index 0000000000..69379f637f --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-snapshot-versions.adoc @@ -0,0 +1,20 @@ +[[features-stub-runner-snapshot-versions]] += Snapshot Versions + +You can add the additional snapshot repository to your build file to use snapshot +versions, which are automatically uploaded after every successful build, as follows: + +==== +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven +---- +include:../:{standalone_samples_path}/http-server/pom.xml[tags=repos,indent=0] +---- + +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle (`settings.xml`) +---- +include:../:{standalone_samples_path}/http-server/settings.gradle[tags=repos,indent=0] +---- +==== + diff --git a/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-stubs-per-consumer.adoc b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-stubs-per-consumer.adoc new file mode 100644 index 0000000000..9b2cf5cc1e --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-stubs-per-consumer.adoc @@ -0,0 +1,98 @@ +[[features-stub-runner-stubs-per-consumer]] += Consumer-Driven Contracts: Stubs Per Consumer + +There are cases in which two consumers of the same endpoint want to have two different responses. + +TIP: This approach also lets you immediately know which consumer uses which part of your API. +You can remove part of a response that your API produces and see which of your autogenerated tests +fails. If none fails, you can safely delete that part of the response, because nobody uses it. + +Consider the following example of a contract defined for the producer called `producer`, +which has two consumers (`foo-consumer` and `bar-consumer`): + +==== +.Consumer `foo-service` +[source,groovy] +---- +request { + url '/foo' + method GET() +} +response { + status OK() + body( + foo: "foo" + } +} +---- + +.Consumer `bar-service` +[source,groovy] +---- +request { + url '/bar' + method GET() +} +response { + status OK() + body( + bar: "bar" + } +} +---- +==== + +You cannot produce two different responses for the same request. That is why you can properly package the +contracts and then profit from the `stubsPerConsumer` feature. + +On the producer side, the consumers can have a folder that contains contracts related only to them. +By setting the `stubrunner.stubs-per-consumer` flag to `true`, we no longer register all stubs but only those that +correspond to the consumer application's name. In other words, we scan the path of every stub and, +if it contains a subfolder with name of the consumer in the path, only then is it registered. + +On the `foo` producer side the contracts would look like this + +[source,bash] +---- +. +└── contracts + ├── bar-consumer + │   ├── bookReturnedForBar.groovy + │   └── shouldCallBar.groovy + └── foo-consumer + ├── bookReturnedForFoo.groovy + └── shouldCallFoo.groovy +---- + +The `bar-consumer` consumer can either set the `spring.application.name` or the `stubrunner.consumer-name` to `bar-consumer` +Alternatively, you can set the test as follows: + +==== +[source,groovy] +---- +include:../:{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/spring/cloud/StubRunnerStubsPerConsumerSpec.groovy[tags=test] +... +} +---- +==== + +Then only the stubs registered under a path that contains `bar-consumer` in its name (that is, those from the +`src/test/resources/contracts/bar-consumer/some/contracts/...` folder) are allowed to be referenced. + +You can also set the consumer name explicitly, as follows: + +==== +[source,groovy] +---- +include:../:{stubrunner_core_path}/src/test/groovy/org/springframework/cloud/contract/stubrunner/spring/cloud/StubRunnerStubsPerConsumerWithConsumerNameSpec.groovy[tags=test] +... +} +---- +==== + +Then only the stubs registered under a path that contains the `foo-consumer` in its name (that is, those from the +`src/test/resources/contracts/foo-consumer/some/contracts/...` folder) are allowed to be referenced. + +For more information about the reasons behind this change, +see https://github.com/spring-cloud/spring-cloud-contract/issues/224[issue 224]. + diff --git a/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-stubs-protocol.adoc b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-stubs-protocol.adoc new file mode 100644 index 0000000000..c4085957a7 --- /dev/null +++ b/docs/modules/ROOT/pages/_project-features-stubrunner/stub-runner-stubs-protocol.adoc @@ -0,0 +1,121 @@ +[[features-stub-runner-stubs-protocol]] += Fetching Stubs or Contract Definitions From A Location + +Instead of picking the stubs or contract definitions from +Artifactory, Nexus, or Git, you can point to +a location on a drive or the classpath. Doing so can be especially useful in a multi-module project, where one module wants +to reuse stubs or contracts from another module without +the need to actually install those in a local maven +repository to commit those changes to Git. + +In order to achieve this, you can use the `stubs://` +protocol when the repository root parameter is set either +in Stub Runner or in a Spring Cloud Contract plugin. + +In this example, the `producer` project has been successfully +built and stubs were generated under the `target/stubs` folder. As a consumer, one can set up the Stub Runner to pick the stubs from that location by using the `stubs://` protocol. + +==== +[source,java,indent=0,subs="verbatim,attributes",role="primary"] +.Annotation +---- +@AutoConfigureStubRunner( +stubsMode = StubRunnerProperties.StubsMode.REMOTE, + repositoryRoot = "stubs://file://location/to/the/producer/target/stubs/", + ids = "com.example:some-producer") +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.JUnit 4 Rule +---- +@Rule + public StubRunnerRule rule = new StubRunnerRule() + .downloadStub("com.example:some-producer") + .repoRoot("stubs://file://location/to/the/producer/target/stubs/") + .stubsMode(StubRunnerProperties.StubsMode.REMOTE); +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.JUnit 5 Extension +---- +@RegisterExtension + public StubRunnerExtension stubRunnerExtension = new StubRunnerExtension() + .downloadStub("com.example:some-producer") + .repoRoot("stubs://file://location/to/the/producer/target/stubs/") + .stubsMode(StubRunnerProperties.StubsMode.REMOTE); +---- +==== + +Contracts and stubs may be stored in a location, where each producer has its own, dedicated folder for contracts and stub mappings. Under that folder, each consumer can have its own setup. To make Stub Runner find the dedicated folder from the provided IDs, you can pass the `stubs.find-producer=true` property or the `stubrunner.stubs.find-producer=true` system property. +The following listing shows an arrangement of contracts and stubs: + +==== +[source,bash,indent=0] +---- +└── com.example <1> + ├── some-artifact-id <2> + │   └── 0.0.1 + │   ├── contracts <3> + │   │   └── shouldReturnStuffForArtifactId.groovy + │   └── mappings <4> + │   └── shouldReturnStuffForArtifactId.json + └── some-other-artifact-id <5> + ├── contracts + │   └── shouldReturnStuffForOtherArtifactId.groovy + └── mappings + └── shouldReturnStuffForOtherArtifactId.json + +---- +<1> group ID of the consumers +<2> consumer with artifact id [some-artifact-id] +<3> contracts for the consumer with artifact id [some-artifact-id] +<4> mappings for the consumer with artifact id [some-artifact-id] +<5> consumer with artifact id [some-other-artifact-id] +==== + +==== +[source,java,indent=0,subs="verbatim,attributes",role="primary"] +.Annotation +---- +@AutoConfigureStubRunner( +stubsMode = StubRunnerProperties.StubsMode.REMOTE, + repositoryRoot = "stubs://file://location/to/the/contracts/directory", + ids = "com.example:some-producer", + properties="stubs.find-producer=true") +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.JUnit 4 Rule +---- + static Map contractProperties() { + Map map = new HashMap<>(); + map.put("stubs.find-producer", "true"); + return map; + } + +@Rule + public StubRunnerRule rule = new StubRunnerRule() + .downloadStub("com.example:some-producer") + .repoRoot("stubs://file://location/to/the/contracts/directory") + .stubsMode(StubRunnerProperties.StubsMode.REMOTE) + .properties(contractProperties()); +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.JUnit 5 Extension +---- + static Map contractProperties() { + Map map = new HashMap<>(); + map.put("stubs.find-producer", "true"); + return map; + } + +@RegisterExtension + public StubRunnerExtension stubRunnerExtension = new StubRunnerExtension() + .downloadStub("com.example:some-producer") + .repoRoot("stubs://file://location/to/the/contracts/directory") + .stubsMode(StubRunnerProperties.StubsMode.REMOTE) + .properties(contractProperties()); +---- +==== + diff --git a/docs/modules/ROOT/pages/getting-started.adoc b/docs/modules/ROOT/pages/getting-started.adoc index 3ff38cd2a5..451647f90c 100644 --- a/docs/modules/ROOT/pages/getting-started.adoc +++ b/docs/modules/ROOT/pages/getting-started.adoc @@ -8,1414 +8,3 @@ includes an introduction to {project-full-name}, along with installation instruc walk you through building your first {project-full-name} application, discussing some core principles as we go. -[[getting-started-introducing-spring-cloud-contract]] -== Introducing Spring Cloud Contract - -Spring Cloud Contract moves TDD to the level of software architecture. -It lets you perform consumer-driven and producer-driven contract testing. - -[[getting-started-introducing-spring-cloud-contract-history]] -=== 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 (https://github.com/Codearte[Codearte]). - -The `0.1.0` release took place on 26 Jan 2015, and it became stable with `1.0.0` release on 29 Feb 2016. - -[[getting-started-introducing-spring-cloud-contract-why]] -==== Why Do You Need It? - -Assume that we have a system that consists of multiple microservices, as the following -image shows: - -image::Deps.png[Microservices Architecture] - -[[getting-started-introducing-spring-cloud-contract-testing-issues]] -==== Testing Issues - -If we want to test the application in the top left corner of the image in the preceding -section to determine whether it can communicate with other services, we could do one of -two things: - -- Deploy all microservices and perform end-to-end tests. -- Mock other microservices in unit and integration tests. - -Both have their advantages but also a lot of disadvantages. - -*Deploy all microservices and perform end-to-end tests* - -Advantages: - -- Simulates production. -- Tests real communication between services. - -Disadvantages: - -- To test one microservice, we have to deploy six microservices, a couple of databases, -and other items. -- The environment where the tests run is locked for a single suite of tests (nobody else -would be able to run the tests in the meantime). -- They take a long time to run. -- The feedback comes very late in the process. -- They are extremely hard to debug. - -*Mock other microservices in unit and integration tests* - -Advantages: - -- They provide very fast feedback. -- They have no infrastructure requirements. - -Disadvantages: - -- The implementor of the service creates stubs that might have nothing to do with -reality. -- You can go to production with passing tests and failing production. - -To solve the aforementioned issues, Spring Cloud Contract was created. The main idea is to -give you very fast feedback, without the need to set up the -whole world of microservices. If you work on stubs, then the only applications you need -are those that your application directly uses. The following image shows the relationship -of stubs to an application: - -image::Stubs2.png[Stubbed Services] - -Spring Cloud Contract gives you the certainty that the stubs that you use were -created by the service that you call. Also, if you can use them, it means that they -were tested against the producer's side. In short, you can trust those stubs. - -[[getting-started-introducing-spring-cloud-contract-purposes]] -=== Purposes - -The main purposes of Spring Cloud Contract are: - -- To ensure that HTTP and messaging stubs (used when developing the client) do exactly -what the actual server-side implementation does. -- To promote the ATDD (acceptance test-driven development) method, and the microservices architectural style. -- To provide a way to publish changes in contracts that are immediately visible on both sides. -- To generate boilerplate test code to be used on the server side. - -By default, Spring Cloud Contract integrates with http://wiremock.org[Wiremock] as the HTTP server stub. - -IMPORTANT: Spring Cloud Contract's purpose is NOT to start writing business -features in the contracts. Assume that we have a business use case of fraud check. If a -user can be a fraud for 100 different reasons, we would assume that you would create two -contracts, one for the positive case and one for the negative case. Contract tests are -used to test contracts between applications, not to simulate full behavior. - -[[getting-started-what-is-a-contract]] -=== What Is a Contract? - -As consumers of services, we need to define what exactly we want to achieve. We need to -formulate our expectations. That is why we write contracts. In other words, a contract is -an agreement on how the API or message communication should look. Consider the following example: - -Assume that you want to send a request that contains the ID of a client company and the -amount it wants to borrow from us. You also want to send it to the `/fraudcheck` URL by using -the `PUT` method. The following listing shows a contract to check whether a client should -be marked as a fraud in both Groovy and YAML: - -==== -[source,groovy,indent=0,role="primary"] -.groovy ----- -include::{introduction_url}/samples/standalone/dsl/http-server/src/test/resources/contracts/fraud/shouldMarkClientAsFraud.groovy[] ----- -//// - -//// -[source,yaml,indent=0,role="secondary"] -.yaml ----- -include::{introduction_url}/samples/standalone/dsl/http-server/src/test/resources/contracts/yml/fraud/shouldMarkClientAsFraud.yml[] ----- -==== - -IMPORTANT: It is expected that contracts are coming from a **trusted source**. You should never download nor interact with contracts coming from untrusted locations. - -[[getting-started-three-second-tour]] -== A Three-second Tour - -This very brief tour walks through using Spring Cloud Contract. It consists of the -following topics: - -* <> -* <> - -You can find a somewhat longer tour -<>. - -The following UML diagram shows the relationship of the parts within Spring Cloud Contract: - -[plantuml, getting-started-three-second, png] ----- -"API Producer"->"API Producer": add Spring Cloud \nContract (SCC) plugin -"API Producer"->"API Producer": add SCC Verifier dependency -"API Producer"->"API Producer": define contracts -"API Producer"->"Build": run build -"Build"->"SCC Plugin": generate \ntests, stubs and stubs \nartifact (e.g. stubs-jar) -"Build"->"Stub Storage": upload contracts \nand stubs and the project arifact -"Build"->"API Producer": Build successful -"API Consumer"->"API Consumer": add SCC Stub Runner \ndependency -"API Consumer"->"API Consumer": write a SCC Stub Runner \nbased contract test -"SCC Stub Runner"->"Stub Storage": test asks for [API Producer] stubs -"Stub Storage"->"SCC Stub Runner": fetch the [API Producer] stubs -"SCC Stub Runner"->"SCC Stub Runner": run in memory\n HTTP server stubs -"API Consumer"->"SCC Stub Runner": send a request \nto the HTTP server stub -"SCC Stub Runner"->"API Consumer": communication is correct ----- - -[[getting-started-three-second-tour-producer]] -=== On the Producer Side - -To start working with Spring Cloud Contract, you can add files with REST or messaging contracts -expressed in either Groovy DSL or YAML to the contracts directory, which is set by the -`contractsDslDir` property. By default, it is `$rootDir/src/test/resources/contracts`. - -Then you can add the Spring Cloud Contract Verifier dependency and plugin to your build file, as -the following example shows: - -==== -[source,xml,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=verifier_test_dependencies,indent=0] ----- -==== - -The following listing shows how to add the plugin, which should go in the build/plugins -portion of the file: - -==== -[source,xml,indent=0] ----- - - org.springframework.cloud - spring-cloud-contract-maven-plugin - ${spring-cloud-contract.version} - true - ----- -==== - -Running `./mvnw clean install` automatically generates tests that verify the application -compliance with the added contracts. By default, the tests get generated under -`org.springframework.cloud.contract.verifier.tests.`. - -As the implementation of the functionalities described by the contracts is not yet -present, the tests fail. - -To make them pass, you must add the correct implementation of either handling HTTP -requests or messages. Also, you must add a base test class for auto-generated -tests to the project. This class is extended by all the auto-generated tests, and it -should contain all the setup information necessary to run them (for example `RestAssuredMockMvc` -controller setup or messaging test setup). - -The following example, from `pom.xml`, shows how to specify the base test class: - -==== -[source,xml,indent=0] ----- - - - - org.springframework.cloud - spring-cloud-contract-maven-plugin - 2.1.2.RELEASE - true - - com.example.contractTest.BaseTestClass <1> - - - - org.springframework.boot - spring-boot-maven-plugin - - - ----- -<1> The `baseClassForTests` element lets you specify your base test class. It must be a child -of a `configuration` element within `spring-cloud-contract-maven-plugin`. -==== - -Once the implementation and the test base class are in place, the tests pass, and both the -application and the stub artifacts are built and installed in the local Maven repository. -You can now merge the changes, and you can publish both the application and the stub artifacts -in an online repository. - -[[getting-started-three-second-tour-consumer]] -=== On the Consumer Side - -You can use `Spring Cloud Contract Stub Runner` in the integration tests to get a running -WireMock instance or messaging route that simulates the actual service. - -To do so, add the dependency to `Spring Cloud Contract Stub Runner`, as the -following example shows: - -==== -[source,xml,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=stub_runner,indent=0] ----- -==== - -You can get the Producer-side stubs installed in your Maven repository in either of two -ways: - -* By checking out the Producer side repository and adding contracts and generating the stubs -by running the following commands: -+ -==== -[source,bash,indent=0] ----- -$ cd local-http-server-repo -$ ./mvnw clean install -DskipTests ----- -==== - -TIP: The tests are being skipped because the producer-side contract implementation is not -in place yet, so the automatically-generated contract tests fail. - -* By getting already-existing producer service stubs from a remote repository. To do so, -pass the stub artifact IDs and artifact repository URL as `Spring Cloud Contract -Stub Runner` properties, as the following example shows: -+ -==== -[source,yaml,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[] ----- -==== - -Now you can annotate your test class with `@AutoConfigureStubRunner`. In the annotation, -provide the `group-id` and `artifact-id` values for `Spring Cloud Contract Stub Runner` to -run the collaborators' stubs for you, as the following example shows: - -==== -[source,java, indent=0] ----- -@RunWith(SpringRunner.class) -@SpringBootTest(webEnvironment=WebEnvironment.NONE) -@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:6565"}, - stubsMode = StubRunnerProperties.StubsMode.LOCAL) -public class LoanApplicationServiceTests { - . . . -} ----- -==== - -TIP: Use the `REMOTE` `stubsMode` when downloading stubs from an online repository and -`LOCAL` for offline work. - -Now, in your integration test, you can receive stubbed versions of HTTP responses or -messages that are expected to be emitted by the collaborator service. - -[[getting-started-first-application]] -== Developing Your First Spring Cloud Contract-based Application - -This brief tour walks through using Spring Cloud Contract. It consists of the following topics: - -* <> -* <> - -You can find an even more brief tour -<>. - -For the sake of this example, the `Stub Storage` is Nexus/Artifactory. - -The following UML diagram shows the relationship of the parts of Spring Cloud Contract: - -image::getting-started-three-second.png[Getting started first application] - -[[getting-started-first-application-producer]] -=== On the Producer Side - -To start working with `Spring Cloud Contract`, you can add the Spring Cloud Contract Verifier -dependency and plugin to your build file, as the following example shows: - -==== -[source,xml,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=verifier_test_dependencies,indent=0] ----- -==== - -The following listing shows how to add the plugin, which should go in the build/plugins -portion of the file: - -==== -[source,xml,indent=0] ----- - - org.springframework.cloud - spring-cloud-contract-maven-plugin - ${spring-cloud-contract.version} - true - ----- -==== - -[TIP] -==== -The easiest way to get started is to go to https://start.spring.io[the Spring Initializr] -and add "`Web`" and "`Contract Verifier`" as dependencies. Doing so pulls in the previously -mentioned dependencies and everything else you need in the `pom.xml` file (except for -setting the base test class, which we cover later in this section). The following image -shows the settings to use in https://start.spring.io[the Spring Initializr]: - -image::start_spring_io_dependencies.png[width=800,alt=Spring Initializr with Web and Contract Verifier] -==== - -Now you can add files with `REST/` messaging contracts -expressed in either Groovy DSL or YAML to the contracts directory, which is set by the -`contractsDslDir` property. By default, it is `$rootDir/src/test/resources/contracts`. -Note that the file name does not matter. You can organize your contracts within this -directory with whatever naming scheme you like. - -For the HTTP stubs, a contract defines what kind of response should be returned for a -given request (taking into account the HTTP methods, URLs, headers, status codes, and so -on). The following example shows an HTTP stub contract in both Groovy and YAML: - -==== -[source,groovy,indent=0,role="primary"] -.groovy ----- -package contracts - -org.springframework.cloud.contract.spec.Contract.make { - request { - method 'PUT' - url '/fraudcheck' - body([ - "client.id": $(regex('[0-9]{10}')), - loanAmount: 99999 - ]) - headers { - contentType('application/json') - } - } - response { - status OK() - body([ - fraudCheckStatus: "FRAUD", - "rejection.reason": "Amount too high" - ]) - headers { - contentType('application/json') - } - } -} ----- - -[source,yaml,indent=0,role="secondary"] -.yaml ----- -request: - method: PUT - url: /fraudcheck - body: - "client.id": 1234567890 - loanAmount: 99999 - headers: - Content-Type: application/json - matchers: - body: - - path: $.['client.id'] - type: by_regex - value: "[0-9]{10}" -response: - status: 200 - body: - fraudCheckStatus: "FRAUD" - "rejection.reason": "Amount too high" - headers: - Content-Type: application/json;charset=UTF-8 ----- -==== - -If you need to use messaging, you can define: - -* The input and output messages (taking into account from where it -was sent, the message body, and the header). -* The methods that should be called after the message is received. -* The methods that, when called, should trigger a message. - -The following example shows a Camel messaging contract: - -==== -[source,groovy,indent=0,role="primary"] -.groovy ----- -include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_method_dsl] ----- - -[source,yaml,indent=0,role="secondary"] -.yaml ----- -include::{verifier_core_path}/src/test/resources/yml/contract_message_scenario1.yml[indent=0] ----- -==== - -Running `./mvnw clean install` automatically generates tests that verify the application -compliance with the added contracts. By default, the generated tests are under -`org.springframework.cloud.contract.verifier.tests.`. - -The generated tests may differ, depending on which framework and test type you have set up -in your plugin. - -In the next listing, you can find: - -- The default test mode for HTTP contracts in `MockMvc` -- A JAX-RS client with the `JAXRS` test mode -- A `WebTestClient`-based test (this is particularly recommended while working with -Reactive, `Web-Flux`-based applications) set with the `WEBTESTCLIENT` test mode - -NOTE: You need only one of these test frameworks. MockMvc is the default. To use one -of the other frameworks, add its library to your classpath. - -The following listing shows samples for all frameworks: - -==== -[source,java,indent=0,role="primary"] -.mockmvc ----- -@Test -public void validate_shouldMarkClientAsFraud() throws Exception { - // given: - MockMvcRequestSpecification request = given() - .header("Content-Type", "application/vnd.fraud.v1+json") - .body("{\"client.id\":\"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("['rejection.reason']").isEqualTo("Amount too high"); -} ----- - -[source,java,indent=0,role="secondary"] -.jaxrs ----- -@SuppressWarnings("rawtypes") -public class FooTest { - WebTarget webTarget; - - @Test - public void validate_() throws Exception { - - // when: - Response response = webTarget - .path("/users") - .queryParam("limit", "10") - .queryParam("offset", "20") - .queryParam("filter", "email") - .queryParam("sort", "name") - .queryParam("search", "55") - .queryParam("age", "99") - .queryParam("name", "Denis.Stepanov") - .queryParam("email", "bob@email.com") - .request() - .build("GET") - .invoke(); - String responseAsString = response.readEntity(String.class); - - // then: - assertThat(response.getStatus()).isEqualTo(200); - - // and: - DocumentContext parsedJson = JsonPath.parse(responseAsString); - assertThatJson(parsedJson).field("['property1']").isEqualTo("a"); - } - -} ----- - -[source,java,indent=0,role="secondary"] -.webtestclient ----- -@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"); - } ----- -==== - -As the implementation of the functionalities described by the contracts is not yet -present, the tests fail. - -To make them pass, you must add the correct implementation of handling either HTTP -requests or messages. Also, you must add a base test class for auto-generated -tests to the project. This class is extended by all the auto-generated tests and should -contain all the setup necessary information needed to run them (for example, -`RestAssuredMockMvc` controller setup or messaging test setup). - -The following example, from `pom.xml`, shows how to specify the base test class: - -==== -[source,xml,indent=0] ----- - - - - org.springframework.cloud - spring-cloud-contract-maven-plugin - 2.1.2.RELEASE - true - - com.example.contractTest.BaseTestClass <1> - - - - org.springframework.boot - spring-boot-maven-plugin - - - ----- -<1> The `baseClassForTests` element lets you specify your base test class. It must be a child -of a `configuration` element within `spring-cloud-contract-maven-plugin`. -==== - -The following example shows a minimal (but functional) base test class: - -==== -[source,java, indent=0] ----- -package com.example.contractTest; - -import org.junit.Before; - -import io.restassured.module.mockmvc.RestAssuredMockMvc; - -public class BaseTestClass { - - @Before - public void setup() { - RestAssuredMockMvc.standaloneSetup(new FraudController()); - } -} ----- -==== - -This minimal class really is all you need to get your tests to work. It serves as a -starting place to which the automatically generated tests attach. - -Now we can move on to the implementation. For that, we first need a data class, which we -then use in our controller. The following listing shows the data class: - -==== -[source,java, indent=0] ----- -package com.example.Test; - -import com.fasterxml.jackson.annotation.JsonProperty; - -public class LoanRequest { - - @JsonProperty("client.id") - private String clientId; - - private Long loanAmount; - - public String getClientId() { - return clientId; - } - - public void setClientId(String clientId) { - this.clientId = clientId; - } - - public Long getLoanAmount() { - return loanAmount; - } - - public void setLoanRequestAmount(Long loanAmount) { - this.loanAmount = loanAmount; - } -} ----- -==== - -The preceding class provides an object in which we can store the parameters. Because the -client ID in the contract is called `client.id`, we need to use the -`@JsonProperty("client.id")` parameter to map it to the `clientId` field. - -Now we can move along to the controller, which the following listing shows: - -==== -[source,java, indent=0] ----- -package com.example.docTest; - -import org.springframework.web.bind.annotation.PutMapping; -import org.springframework.web.bind.annotation.RequestBody; -import org.springframework.web.bind.annotation.RestController; - -@RestController -public class FraudController { - - @PutMapping(value = "/fraudcheck", consumes="application/json", produces="application/json") - public String check(@RequestBody LoanRequest loanRequest) { <1> - - if (loanRequest.getLoanAmount() > 10000) { <2> - return "{fraudCheckStatus: FRAUD, rejection.reason: Amount too high}"; <3> - } else { - return "{fraudCheckStatus: OK, acceptance.reason: Amount OK}"; <4> - } - } -} ----- -<1> We map the incoming parameters to a `LoanRequest` object. -<2> We check the requested loan amount to see if it is too much. -<3> If it is too much, we return the JSON (created with a simple string here) that the -test expects. -<4> If we had a test to catch when the amount is allowable, we could match it to this output. -==== - -The `FraudController` is about as simple as things get. You can do much more, including -logging, validating the client ID, and so on. - -Once the implementation and the test base class are in place, the tests pass, and both the -application and the stub artifacts are built and installed in the local Maven repository. -Information about installing the stubs jar to the local repository appears in the logs, as -the following example shows: - -==== -[source,bash,indent=0] ----- - [INFO] --- spring-cloud-contract-maven-plugin:1.0.0.BUILD-SNAPSHOT:generateStubs (default-generateStubs) @ http-server --- - [INFO] Building jar: /some/path/http-server/target/http-server-0.0.1-SNAPSHOT-stubs.jar - [INFO] - [INFO] --- maven-jar-plugin:2.6:jar (default-jar) @ http-server --- - [INFO] Building jar: /some/path/http-server/target/http-server-0.0.1-SNAPSHOT.jar - [INFO] - [INFO] --- spring-boot-maven-plugin:1.5.5.BUILD-SNAPSHOT:repackage (default) @ http-server --- - [INFO] - [INFO] --- maven-install-plugin:2.5.2:install (default-install) @ http-server --- - [INFO] Installing /some/path/http-server/target/http-server-0.0.1-SNAPSHOT.jar to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT.jar - [INFO] Installing /some/path/http-server/pom.xml to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT.pom - [INFO] Installing /some/path/http-server/target/http-server-0.0.1-SNAPSHOT-stubs.jar to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar ----- -==== - -You can now merge the changes and publish both the application and the stub artifacts -in an online repository. - -[[getting-started-first-application-consumer]] -=== On the Consumer Side - -You can use Spring Cloud Contract Stub Runner in the integration tests to get a running -WireMock instance or messaging route that simulates the actual service. - -To get started, add the dependency to `Spring Cloud Contract Stub Runner`, as follows: - -==== -[source,xml,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=stub_runner,indent=0] ----- -==== - -You can get the Producer-side stubs installed in your Maven repository in either of two -ways: - -* By checking out the Producer side repository and adding contracts and generating the -stubs by running the following commands: -+ -==== -[source,bash,indent=0] ----- -$ cd local-http-server-repo -$ ./mvnw clean install -DskipTests ----- -==== -NOTE: The tests are skipped because the Producer-side contract implementation is not yet -in place, so the automatically-generated contract tests fail. - -* By getting existing producer service stubs from a remote repository. To do so, -pass the stub artifact IDs and artifact repository URL as `Spring Cloud Contract Stub -Runner` properties, as the following example shows: -+ -==== -[source,yaml,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[] ----- -==== - -Now you can annotate your test class with `@AutoConfigureStubRunner`. In the annotation, -provide the `group-id` and `artifact-id` for `Spring Cloud Contract Stub Runner` to run -the collaborators' stubs for you, as the following example shows: - -==== -[source,java, indent=0] ----- -@RunWith(SpringRunner.class) -@SpringBootTest(webEnvironment=WebEnvironment.NONE) -@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:6565"}, - stubsMode = StubRunnerProperties.StubsMode.LOCAL) -public class LoanApplicationServiceTests { - . . . -} ----- -==== - -TIP: Use the `REMOTE` `stubsMode` when downloading stubs from an online repository and -`LOCAL` for offline work. - -In your integration test, you can receive stubbed versions of HTTP responses or messages -that are expected to be emitted by the collaborator service. You can see entries similar -to the following in the build logs: - -==== -[source,bash,indent=0] ----- -2016-07-19 14:22:25.403 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Desired version is + - will try to resolve the latest version -2016-07-19 14:22:25.438 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved version is 0.0.1-SNAPSHOT -2016-07-19 14:22:25.439 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolving artifact com.example:http-server:jar:stubs:0.0.1-SNAPSHOT using remote repositories [] -2016-07-19 14:22:25.451 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved artifact com.example:http-server:jar:stubs:0.0.1-SNAPSHOT to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar -2016-07-19 14:22:25.465 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacking stub from JAR [URI: file:/path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar] -2016-07-19 14:22:25.475 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacked file to [/var/folders/0p/xwq47sq106x1_g3dtv6qfm940000gq/T/contracts100276532569594265] -2016-07-19 14:22:27.737 INFO 41050 --- [ main] o.s.c.c.stubrunner.StubRunnerExecutor : All stubs are now running RunningStubs [namesAndPorts={com.example:http-server:0.0.1-SNAPSHOT:stubs=8080}] ----- -==== - -[[getting-started-cdc]] -== Step-by-step Guide to Consumer Driven Contracts (CDC) with Contracts on the Producer Side - -Consider an example of fraud detection and the loan issuance process. The business -scenario is such that we want to issue loans to people but do not want them to steal from -us. The current implementation of our system grants loans to everybody. - -Assume that `Loan Issuance` is a client to the `Fraud Detection` server. In the current -sprint, we must develop a new feature: if a client wants to borrow too much money, -we mark the client as a fraud. - -Technical remarks - -* Fraud Detection has an `artifact-id` of `http-server`. -* Loan Issuance has an `artifact-id` of `http-client`. -* Both have a `group-id` of `com.example`. -* For the sake of this example, the `Stub Storage` is Nexus/Artifactory. - -Social remarks - -* Both the client and the server development teams need to communicate directly and -discuss changes while going through the process. -* CDC is all about communication. - -The server-side code is available under Spring Cloud Contract's repository `samples/standalone/dsl/http-server` path, and the client-side code is available under Spring Cloud Contract's repository `samples/standalone/dsl/http-client` path. - -TIP: In this case, the producer owns the contracts. Physically, all the contracts are -in the producer's repository. - -[[getting-started-cdc-technical-note]] -=== Technical Note - -If you use the SNAPSHOT, Milestone, or Release Candidate versions, you need to add the -following section to your build: - -==== -[source,xml,indent=0,subs="verbatim,attributes",role="primary"] -.Maven ----- -include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=repos,indent=0] ----- -//// - -//// -[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] -.Gradle ----- -include::{introduction_url}/samples/standalone/dsl/http-server/build.gradle[tags=deps_repos,indent=0] ----- -==== - -For simplicity, we use the following acronyms: - -- Loan Issuance (LI): The HTTP client -- Fraud Detection (FD): The HTTP server -- SCC: Spring Cloud Contract - -[[getting-started-cdc-consumer]] -=== The Consumer Side (Loan Issuance) - -As a developer of the Loan Issuance service (a consumer of the Fraud Detection server), you might do the following steps: - -. Start doing TDD by writing a test for your feature. -. Write the missing implementation. -. Clone the Fraud Detection service repository locally. -. Define the contract locally in the repository of the fraud detection service. -. Add the Spring Cloud Contract (SCC) plugin. -. Run the integration tests. -. File a pull request. -. Create an initial implementation. -. Take over the pull request. -. Write the missing implementation. -. Deploy your application. -. Work online. - -We start with the loan issuance flow, which the following UML diagram shows: - -[plantuml, getting-started-cdc-client, png] ----- -"Loan\nIssuance"->"Loan\nIssuance": start doing TDD\nby writing a test\nfor your feature -"Loan\nIssuance"->"Loan\nIssuance": write the \nmissing implementation -"Loan\nIssuance"->"Loan\nIssuance": run a test - it fails\ndue to no server running -"Loan\nIssuance"->"Fraud\nDetection\nClone": clone the repository -"Fraud\nDetection\nClone"->"Fraud\nDetection\nClone": add missing dependencies\n& define contracts -"Fraud\nDetection\nClone"->"Fraud\nDetection\nClone": add the SCC plugin -"Fraud\nDetection\nClone"->"FD \nClone Build": install the stubs locally -"FD \nClone Build"->"SCC Plugin \nin FD Clone": generate stubs \nand stubs \nartifact (e.g. stubs-jar) -"SCC Plugin \nin FD Clone"->"FD \nClone Build": stubs and artifacts\ngenerated -"FD \nClone Build"->"Local storage": install the stubs locally -"Local storage"->"FD \nClone Build": stub sucessfully installed -"FD \nClone Build"->"Fraud\nDetection\nClone": build successful -"Loan\nIssuance"->"Loan\nIssuance": add a SCC\nStub Runner\ndependency\nand setup -"Loan\nIssuance"->"LI\nSCC\nStub Runner": start stubs\nof FD from\nlocal storage -"LI\nSCC\nStub Runner"->"Local storage": find stubs of [FD] -"Local storage"->"LI\nSCC\nStub Runner": stubs of [FD] found -"LI\nSCC\nStub Runner"->"FD stub": run stubs of [FD] -"FD stub"->"LI\nSCC\nStub Runner": [FD] stub is running -"LI\nSCC\nStub Runner"->"Loan\nIssuance": stubs running and ready for the test -"Loan\nIssuance"->"Loan\nIssuance": run a test -"Loan\nIssuance"->"FD stub": the test\nsends a request\nto the running stub -"FD stub"->"Loan\nIssuance": stub responds successfuly -"Loan\nIssuance"->"Loan\nIssuance": the test passes successfully -"Loan\nIssuance"->"Fraud\nDetection": send a pull request\nwith the\nsuggested contracts ----- - -[[getting-started-cdc-consumer-start]] -==== Start Doing TDD by Writing a Test for Your Feature - -The following listing shows a test that we might use to check whether a loan amount is too -large: - -==== -[source,groovy,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-client/src/test/java/com/example/loan/LoanApplicationServiceTests.java[tags=client_tdd,indent=0] ----- -==== - -Assume that you have written a test of your new feature. If a loan application for a big -amount is received, the system should reject that loan application with some description. - -[[getting-started-cdc-consumer-write]] -==== Write the Missing Implementation - -At some point in time, you need to send a request to the Fraud Detection service. Assume -that you need to send the request containing the ID of the client and the amount the -client wants to borrow. You want to send it to the `/fraudcheck` URL by using the `PUT` method. -To do so, you might use code similar to the following: - -==== -[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] ----- -==== - -For simplicity, the port of the Fraud Detection service is set to `8080`, and the -application runs on `8090`. - -NOTE: If you start the test at this point, it breaks, because no service currently runs on port -`8080`. - -[[getting-started-cdc-consumer-clone]] -==== Clone the Fraud Detection service repository locally - -You can start by playing around with the server side contract. To do so, you must first -clone it, by running the following command: - -==== -[source,bash,indent=0] ----- -$ git clone https://your-git-server.com/server-side.git local-http-server-repo ----- -==== - -[[getting-started-cdc-consumer-define]] -==== Define the Contract Locally in the Repository of the Fraud Detection Service - -As a consumer, you need to define what exactly you want to achieve. You need to formulate -your expectations. To do so, write the following contract: - -IMPORTANT: Place the contract in the `src/test/resources/contracts/fraud` folder. The `fraud` folder -is important because the producer's test base class name references that folder. - -The following example shows our contract, in both Groovy and YAML: - -==== -[source,groovy,indent=0,role="primary"] -.groovy ----- -include::{introduction_url}/samples/standalone/dsl/http-server/src/test/resources/contracts/fraud/shouldMarkClientAsFraud.groovy[] ----- -//// - -//// -[source,yaml,indent=0,role="secondary"] -.yaml ----- -include::{introduction_url}/samples/standalone/dsl/http-server/src/test/resources/contracts/yml/fraud/shouldMarkClientAsFraud.yml[] ----- -==== - -The YML contract is quite straightforward. However, when you take a look at the contract -written with a statically typed Groovy DSL, you might wonder what the -`value(client(...), server(...))` parts are. By using this notation, Spring Cloud -Contract lets you define parts of a JSON block, a URL, or other structure that is dynamic. In the case -of an identifier or a timestamp, you need not hardcode a value. You want to allow some -different ranges of values. To enable ranges of values, you can set regular expressions -that match those values for the consumer side. You can provide the body by means of either -a map notation or a String with interpolations. We highly recommend using the map notation. - -TIP: To set up contracts, you must understand the map notation. See the -https://groovy-lang.org/json.html[Groovy docs regarding JSON]. - -The previously shown contract is an agreement between two sides that: - -* If an HTTP request is sent with all of: -** A `PUT` method on the `/fraudcheck` endpoint -** A JSON body with a `client.id` that matches the regular expression `[0-9]{10}` and -`loanAmount` equal to `99999` -** A `Content-Type` header with a value of `application/vnd.fraud.v1+json` -* Then an HTTP response is sent to the consumer that -** Has status `200` -** Contains a JSON body with the `fraudCheckStatus` field containing a value of `FRAUD` and -the `rejectionReason` field having a value of `Amount too high` -** Has a `Content-Type` header with a value of `application/vnd.fraud.v1+json` - -Once you are ready to check the API in practice in the integration tests, you need to -install the stubs locally. - -[[getting-started-cdc-consumer-add]] -==== Add the Spring Cloud Contract Verifier Plugin - -We can add either a Maven or a Gradle plugin. In this example, we show how to add Maven. -First, we add the `Spring Cloud Contract` BOM, as the following example shows: - -==== -[source,xml,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=contract_bom,indent=0] ----- -==== - -Next, add the `Spring Cloud Contract Verifier` Maven plugin, as the following example shows: - -==== -[source,xml,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=contract_maven_plugin,indent=0] ----- -==== - -Since the plugin was added, you get the `Spring Cloud Contract Verifier` features, which, -from the provided contracts: - -- Generate and run tests -- Produce and install stubs - -You do not want to generate tests, since you, as the consumer, want only to play with the -stubs. You need to skip the test generation and invokation. To do so, run the following commands: - -==== -[source,bash,indent=0] ----- -$ cd local-http-server-repo -$ ./mvnw clean install -DskipTests ----- -==== - -Once you run those commands, you should you see something like the following content in the logs: - -==== -[source,bash,indent=0] ----- -[INFO] --- spring-cloud-contract-maven-plugin:1.0.0.BUILD-SNAPSHOT:generateStubs (default-generateStubs) @ http-server --- -[INFO] Building jar: /some/path/http-server/target/http-server-0.0.1-SNAPSHOT-stubs.jar -[INFO] -[INFO] --- maven-jar-plugin:2.6:jar (default-jar) @ http-server --- -[INFO] Building jar: /some/path/http-server/target/http-server-0.0.1-SNAPSHOT.jar -[INFO] -[INFO] --- spring-boot-maven-plugin:1.5.5.BUILD-SNAPSHOT:repackage (default) @ http-server --- -[INFO] -[INFO] --- maven-install-plugin:2.5.2:install (default-install) @ http-server --- -[INFO] Installing /some/path/http-server/target/http-server-0.0.1-SNAPSHOT.jar to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT.jar -[INFO] Installing /some/path/http-server/pom.xml to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT.pom -[INFO] Installing /some/path/http-server/target/http-server-0.0.1-SNAPSHOT-stubs.jar to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar ----- -==== - -The following line is extremely important: - -==== -[source,bash,indent=0] ----- -[INFO] Installing /some/path/http-server/target/http-server-0.0.1-SNAPSHOT-stubs.jar to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar ----- -==== - -It confirms that the stubs of the `http-server` have been installed in the local -repository. - -[[getting-started-cdc-consumer-run]] -==== Running the Integration Tests - -In order to profit from the Spring Cloud Contract Stub Runner functionality of automatic -stub downloading, you must do the following in your consumer side project (`Loan -Application service`): - -. Add the `Spring Cloud Contract` BOM, as follows: -+ -==== -[source,xml,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=contract_bom,indent=0] ----- -==== - -. Add the dependency to `Spring Cloud Contract Stub Runner`, as follows: -+ -==== -[source,xml,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=stub_runner,indent=0] ----- -==== - -. Annotate your test class with `@AutoConfigureStubRunner`. In the annotation, provide the -`group-id` and `artifact-id` for the Stub Runner to download the 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] ----- -==== - -. (Optional) Because you are playing with the collaborators offline, you -can also provide the offline work switch (`StubRunnerProperties.StubsMode.LOCAL`). - -Now, when you run your tests, you see something like the following output in the logs: - -==== -[source,bash,indent=0] ----- -2016-07-19 14:22:25.403 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Desired version is + - will try to resolve the latest version -2016-07-19 14:22:25.438 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved version is 0.0.1-SNAPSHOT -2016-07-19 14:22:25.439 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolving artifact com.example:http-server:jar:stubs:0.0.1-SNAPSHOT using remote repositories [] -2016-07-19 14:22:25.451 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved artifact com.example:http-server:jar:stubs:0.0.1-SNAPSHOT to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar -2016-07-19 14:22:25.465 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacking stub from JAR [URI: file:/path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar] -2016-07-19 14:22:25.475 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacked file to [/var/folders/0p/xwq47sq106x1_g3dtv6qfm940000gq/T/contracts100276532569594265] -2016-07-19 14:22:27.737 INFO 41050 --- [ main] o.s.c.c.stubrunner.StubRunnerExecutor : All stubs are now running RunningStubs [namesAndPorts={com.example:http-server:0.0.1-SNAPSHOT:stubs=8080}] ----- -==== - -This output means that Stub Runner has found your stubs and started a server for your application -with a group ID of `com.example` and an artifact ID of `http-server` with version `0.0.1-SNAPSHOT` of -the stubs and with the `stubs` classifier on port `8080`. - -[[getting-started-cdc-consumer-file]] -==== Filing a Pull Request - -What you have done until now is an iterative process. You can play around with the -contract, install it locally, and work on the consumer side until the contract works as -you wish. - -Once you are satisfied with the results and the test passes, you can publish a pull request to -the server side. Currently, the consumer side work is done. - -[[getting-started-cdc-producer]] -=== The Producer Side (Fraud Detection server) - -As a developer of the Fraud Detection server (a server to the Loan Issuance service), you -might want to: - -- Take over the pull request -- Write the missing implementation -- Deploy the application - -The following UML diagram shows the fraud detection flow: - -[plantuml, getting-started-cdc-server, png] ----- -"Fraud\nDetection"->"Fraud\nDetection": take over the\n pull request -"Fraud\nDetection"->"Fraud\nDetection": setup\nSpring Cloud\nContract plugin -"Fraud\nDetection"->"Fraud\nDetection\nBuild": run the build -"Fraud\nDetection\nBuild"->"SCC Plugin": generate tests\nstubs \nand stubs artifact \n(e.g. stubs-jar) -"SCC Plugin"->"Fraud\nDetection\nBuild": tests and stubs generated -"Fraud\nDetection\nBuild"->"Fraud\nDetection\nBuild": run tests -"Fraud\nDetection\nBuild"->"Fraud\nDetection": generated tests failed! -"Fraud\nDetection"->"Fraud\nDetection": setup\nbase classes\nfor contract tests -"Fraud\nDetection"->"Fraud\nDetection\nBuild": run the build -"Fraud\nDetection\nBuild"->"SCC Plugin": generate tests\nstubs \nand stubs artifact \n(e.g. stubs-jar) -"SCC Plugin"->"Fraud\nDetection\nBuild": tests and stubs generated -"Fraud\nDetection\nBuild"->"Fraud\nDetection\nBuild": run tests -"Fraud\nDetection\nBuild"->"Fraud\nDetection": all the tests passed! -"Fraud\nDetection"->"Fraud\nDetection": commit and push changes -"Fraud\nDetection"->"CI": commit pushed!\nTriggers the build -"CI"->"Stub Storage": build successful,\nupload artifacts ----- - -[[getting-started-cdc-producer-pr]] -==== Taking over the Pull Request - -As a reminder, the following listing shows the initial implementation: - -==== -[source,java,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=server_api,indent=0] -include::{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=initial_impl,indent=0] -} ----- -==== - -Then you can run the following commands: - -==== -[source,bash,indent=0] ----- -$ git checkout -b contract-change-pr master -$ git pull https://your-git-server.com/server-side-fork.git contract-change-pr ----- -==== - -You must add the dependencies needed by the autogenerated tests, as follows: - -==== -[source,xml,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=verifier_test_dependencies,indent=0] ----- -==== - -In the configuration of the Maven plugin, you must pass the `packageWithBaseClasses` property, as follows: - -==== -[source,xml,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=contract_maven_plugin,indent=0] ----- -==== - -IMPORTANT: This example uses "`convention-based`" naming by setting the -`packageWithBaseClasses` property. Doing so means that the two last packages combine to -make the name of the base test class. In our case, the contracts were placed under -`src/test/resources/contracts/fraud`. Since you do not have two packages starting from -the `contracts` folder, pick only one, which should be `fraud`. Add the `Base` suffix and -capitalize `fraud`. That gives you the `FraudBase` test class name. - -All the generated tests extend that class. Over there, you can set up your Spring Context -or whatever is necessary. In this case, you should use https://github.com/rest-assured/rest-assured[Rest Assured MVC] to -start the server side `FraudDetectionController`. The following listing shows the -`FraudBase` class: - -==== -[source,java,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-server/src/test/java/com/example/fraud/FraudBase.java[] ----- -==== - -Now, if you run the `./mvnw clean install`, you get something like the following output: - -==== -[source,bash,indent=0] ----- -Results : - -Tests in error: - ContractVerifierTest.validate_shouldMarkClientAsFraud:32 » IllegalState Parsed... ----- -==== - -This error occurs because you have a new contract from which a test was generated, and it -failed since you have not implemented the feature. The auto-generated test would look -like the following test method: - -==== -[source,java,indent=0] ----- -@Test -public void validate_shouldMarkClientAsFraud() throws Exception { - // given: - MockMvcRequestSpecification request = given() - .header("Content-Type", "application/vnd.fraud.v1+json") - .body("{\"client.id\":\"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("['rejection.reason']").isEqualTo("Amount too high"); -} ----- -==== - -If you used the Groovy DSL, you can see that all the `producer()` parts of the Contract that were present in the -`value(consumer(...), producer(...))` blocks got injected into the test. -If you use YAML, the same applies for the `matchers` sections of the `response`. - -Note that, on the producer side, you are also doing TDD. The expectations are expressed -in the form of a test. This test sends a request to our own application with the URL, -headers, and body defined in the contract. It also expects precisely defined values -in the response. In other words, you have the `red` part of `red`, `green`, and -`refactor`. It is time to convert the `red` into the `green`. - -[[getting-started-cdc-producer-impl]] -==== Write the Missing Implementation - -Because you know the expected input and expected output, you can write the missing -implementation as follows: - -==== -[source,java,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=server_api,indent=0] -include::{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=new_impl,indent=0] -include::{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=initial_impl,indent=0] -} ----- -==== - -When you run `./mvnw clean install` again, the tests pass. Since the Spring Cloud -Contract Verifier plugin adds the tests to the `generated-test-sources`, you can -actually run those tests from your IDE. - -[[getting-started-cdc-producer-deploy]] -==== Deploying Your Application - -Once you finish your work, you can deploy your changes. To do so, you must first merge the -branch by running the following commands: - -==== -[source,bash,indent=0] ----- -$ git checkout master -$ git merge --no-ff contract-change-pr -$ git push origin master ----- -==== - -Your CI might run a command such as `./mvnw clean deploy`, which would publish both the -application and the stub artifacts. - -[[getting-started-cdc-consumer-final]] -=== Consumer Side (Loan Issuance), Final Step - -As a developer of the loan issuance service (a consumer of the Fraud Detection server), you need to: - -- Merge our feature branch to `master` -- Switch to online mode of working - -The following UML diagram shows the final state of the process: - -[plantuml, getting-started-cdc-client-final, png] ----- -"Loan\nIssuance"->"Loan\nIssuance": merge the\nfeature branch\nto master branch -"Loan\nIssuance"->"Loan\nIssuance": setup SCC Stub Runner\nto fetch stubs\nfrom Stub Storage -"Loan\nIssuance"->"LI\nSCC\nStub Runner": start stubs\nof FD from\nStub Storage -"LI\nSCC\nStub Runner"->"Stub Storage": find stubs of [FD] -"Stub Storage"->"LI\nSCC\nStub Runner": stubs of [FD] found -"LI\nSCC\nStub Runner"->"FD stub": run stubs of [FD] -"FD stub"->"LI\nSCC\nStub Runner": [FD] stub is running -"LI\nSCC\nStub Runner"->"Loan\nIssuance": stubs running and ready for the test -"Loan\nIssuance"->"Loan\nIssuance": run a test -"Loan\nIssuance"->"FD stub": the test\nsends a request\nto the running stub -"FD stub"->"Loan\nIssuance": stub responds successfuly -"Loan\nIssuance"->"Loan\nIssuance": the test passes successfully ----- - -[[getting-started-cdc-consumer-final-merge]] -==== Merging a Branch to Master - -The following commands show one way to merge a branch into master with Git: - -==== -[source,bash,indent=0] ----- -$ git checkout master -$ git merge --no-ff contract-change-pr ----- -==== - -[[getting-started-cdc-consumer-final-online]] -==== Working Online - -Now you can disable the offline work for Spring Cloud Contract Stub Runner and indicate -where the repository with your stubs is located. At this moment, the stubs of the server -side are automatically downloaded from Nexus/Artifactory. You can set the value of -`stubsMode` to `REMOTE`. The following code shows an example of -achieving the same thing by changing the properties: - -==== -[source,yaml,indent=0] ----- -include::{introduction_url}/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[] ----- -==== - -That's it. You have finished the tutorial. - -[[getting-started-whats-next]] -== Next Steps - -Hopefully, this section provided some of the {project-full-name} basics and got you on your way -to writing your own applications. If you are a task-oriented type of developer, you might -want to jump over to https://spring.io and check out some -https://spring.io/guides/[getting started] guides that solve specific "`How do I do that -with Spring?`" problems. We also have {project-full-name}-specific -"`<>`" reference documentation. - -Otherwise, the next logical step is to read <>. If -you are really impatient, you could also jump ahead and read about -<>. - -In addition, you can check out the following videos: - -- "Consumer Driven Contracts and Your Microservice Architecture" by Olga Maciaszek-Sharma and Marcin Grzejszczak - -video::pDkC_00hhvA[youtube,width=640,height=480] - -- "Contract Tests in the Enterprise" by Marcin Grzejszczak - -video::ZyHG-VOzPZg[youtube,width=640,height=480] - -- "Why Contract Tests Matter?" by Marcin Grzejszczak - -video::TvpkZu1e2Dc[youtube,start=6262,width=640,height=480] - -You can find the default project samples at -https://github.com/spring-cloud-samples/spring-cloud-contract-samples[samples]. diff --git a/docs/modules/ROOT/pages/getting-started/cdc.adoc b/docs/modules/ROOT/pages/getting-started/cdc.adoc new file mode 100644 index 0000000000..0a889312d9 --- /dev/null +++ b/docs/modules/ROOT/pages/getting-started/cdc.adoc @@ -0,0 +1,588 @@ +[[getting-started-cdc]] += Step-by-step Guide to Consumer Driven Contracts (CDC) with Contracts on the Producer Side + +Consider an example of fraud detection and the loan issuance process. The business +scenario is such that we want to issue loans to people but do not want them to steal from +us. The current implementation of our system grants loans to everybody. + +Assume that `Loan Issuance` is a client to the `Fraud Detection` server. In the current +sprint, we must develop a new feature: if a client wants to borrow too much money, +we mark the client as a fraud. + +Technical remarks + +* Fraud Detection has an `artifact-id` of `http-server`. +* Loan Issuance has an `artifact-id` of `http-client`. +* Both have a `group-id` of `com.example`. +* For the sake of this example, the `Stub Storage` is Nexus/Artifactory. + +Social remarks + +* Both the client and the server development teams need to communicate directly and +discuss changes while going through the process. +* CDC is all about communication. + +The server-side code is available under Spring Cloud Contract's repository `samples/standalone/dsl/http-server` path, and the client-side code is available under Spring Cloud Contract's repository `samples/standalone/dsl/http-client` path. + +TIP: In this case, the producer owns the contracts. Physically, all the contracts are +in the producer's repository. + +[[getting-started-cdc-technical-note]] +== Technical Note + +If you use the SNAPSHOT, Milestone, or Release Candidate versions, you need to add the +following section to your build: + +==== +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.Maven +---- +include:../:{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=repos,indent=0] +---- +//// + +//// +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.Gradle +---- +include:../:{introduction_url}/samples/standalone/dsl/http-server/build.gradle[tags=deps_repos,indent=0] +---- +==== + +For simplicity, we use the following acronyms: + +- Loan Issuance (LI): The HTTP client +- Fraud Detection (FD): The HTTP server +- SCC: Spring Cloud Contract + +[[getting-started-cdc-consumer]] +== The Consumer Side (Loan Issuance) + +As a developer of the Loan Issuance service (a consumer of the Fraud Detection server), you might do the following steps: + +. Start doing TDD by writing a test for your feature. +. Write the missing implementation. +. Clone the Fraud Detection service repository locally. +. Define the contract locally in the repository of the fraud detection service. +. Add the Spring Cloud Contract (SCC) plugin. +. Run the integration tests. +. File a pull request. +. Create an initial implementation. +. Take over the pull request. +. Write the missing implementation. +. Deploy your application. +. Work online. + +We start with the loan issuance flow, which the following UML diagram shows: + +[plantuml, getting-started-cdc-client, png] +---- +"Loan\nIssuance"->"Loan\nIssuance": start doing TDD\nby writing a test\nfor your feature +"Loan\nIssuance"->"Loan\nIssuance": write the \nmissing implementation +"Loan\nIssuance"->"Loan\nIssuance": run a test - it fails\ndue to no server running +"Loan\nIssuance"->"Fraud\nDetection\nClone": clone the repository +"Fraud\nDetection\nClone"->"Fraud\nDetection\nClone": add missing dependencies\n& define contracts +"Fraud\nDetection\nClone"->"Fraud\nDetection\nClone": add the SCC plugin +"Fraud\nDetection\nClone"->"FD \nClone Build": install the stubs locally +"FD \nClone Build"->"SCC Plugin \nin FD Clone": generate stubs \nand stubs \nartifact (e.g. stubs-jar) +"SCC Plugin \nin FD Clone"->"FD \nClone Build": stubs and artifacts\ngenerated +"FD \nClone Build"->"Local storage": install the stubs locally +"Local storage"->"FD \nClone Build": stub sucessfully installed +"FD \nClone Build"->"Fraud\nDetection\nClone": build successful +"Loan\nIssuance"->"Loan\nIssuance": add a SCC\nStub Runner\ndependency\nand setup +"Loan\nIssuance"->"LI\nSCC\nStub Runner": start stubs\nof FD from\nlocal storage +"LI\nSCC\nStub Runner"->"Local storage": find stubs of [FD] +"Local storage"->"LI\nSCC\nStub Runner": stubs of [FD] found +"LI\nSCC\nStub Runner"->"FD stub": run stubs of [FD] +"FD stub"->"LI\nSCC\nStub Runner": [FD] stub is running +"LI\nSCC\nStub Runner"->"Loan\nIssuance": stubs running and ready for the test +"Loan\nIssuance"->"Loan\nIssuance": run a test +"Loan\nIssuance"->"FD stub": the test\nsends a request\nto the running stub +"FD stub"->"Loan\nIssuance": stub responds successfuly +"Loan\nIssuance"->"Loan\nIssuance": the test passes successfully +"Loan\nIssuance"->"Fraud\nDetection": send a pull request\nwith the\nsuggested contracts +---- + +[[getting-started-cdc-consumer-start]] +=== Start Doing TDD by Writing a Test for Your Feature + +The following listing shows a test that we might use to check whether a loan amount is too +large: + +==== +[source,groovy,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-client/src/test/java/com/example/loan/LoanApplicationServiceTests.java[tags=client_tdd,indent=0] +---- +==== + +Assume that you have written a test of your new feature. If a loan application for a big +amount is received, the system should reject that loan application with some description. + +[[getting-started-cdc-consumer-write]] +=== Write the Missing Implementation + +At some point in time, you need to send a request to the Fraud Detection service. Assume +that you need to send the request containing the ID of the client and the amount the +client wants to borrow. You want to send it to the `/fraudcheck` URL by using the `PUT` method. +To do so, you might use code similar to the following: + +==== +[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] +---- +==== + +For simplicity, the port of the Fraud Detection service is set to `8080`, and the +application runs on `8090`. + +NOTE: If you start the test at this point, it breaks, because no service currently runs on port +`8080`. + +[[getting-started-cdc-consumer-clone]] +=== Clone the Fraud Detection service repository locally + +You can start by playing around with the server side contract. To do so, you must first +clone it, by running the following command: + +==== +[source,bash,indent=0] +---- +$ git clone https://your-git-server.com/server-side.git local-http-server-repo +---- +==== + +[[getting-started-cdc-consumer-define]] +=== Define the Contract Locally in the Repository of the Fraud Detection Service + +As a consumer, you need to define what exactly you want to achieve. You need to formulate +your expectations. To do so, write the following contract: + +IMPORTANT: Place the contract in the `src/test/resources/contracts/fraud` folder. The `fraud` folder +is important because the producer's test base class name references that folder. + +The following example shows our contract, in both Groovy and YAML: + +==== +[source,groovy,indent=0,role="primary"] +.groovy +---- +include:../:{introduction_url}/samples/standalone/dsl/http-server/src/test/resources/contracts/fraud/shouldMarkClientAsFraud.groovy[] +---- +//// + +//// +[source,yaml,indent=0,role="secondary"] +.yaml +---- +include:../:{introduction_url}/samples/standalone/dsl/http-server/src/test/resources/contracts/yml/fraud/shouldMarkClientAsFraud.yml[] +---- +==== + +The YML contract is quite straightforward. However, when you take a look at the contract +written with a statically typed Groovy DSL, you might wonder what the +`value(client(...), server(...))` parts are. By using this notation, Spring Cloud +Contract lets you define parts of a JSON block, a URL, or other structure that is dynamic. In the case +of an identifier or a timestamp, you need not hardcode a value. You want to allow some +different ranges of values. To enable ranges of values, you can set regular expressions +that match those values for the consumer side. You can provide the body by means of either +a map notation or a String with interpolations. We highly recommend using the map notation. + +TIP: To set up contracts, you must understand the map notation. See the +https://groovy-lang.org/json.html[Groovy docs regarding JSON]. + +The previously shown contract is an agreement between two sides that: + +* If an HTTP request is sent with all of: +** A `PUT` method on the `/fraudcheck` endpoint +** A JSON body with a `client.id` that matches the regular expression `[0-9]{10}` and +`loanAmount` equal to `99999` +** A `Content-Type` header with a value of `application/vnd.fraud.v1+json` +* Then an HTTP response is sent to the consumer that +** Has status `200` +** Contains a JSON body with the `fraudCheckStatus` field containing a value of `FRAUD` and +the `rejectionReason` field having a value of `Amount too high` +** Has a `Content-Type` header with a value of `application/vnd.fraud.v1+json` + +Once you are ready to check the API in practice in the integration tests, you need to +install the stubs locally. + +[[getting-started-cdc-consumer-add]] +=== Add the Spring Cloud Contract Verifier Plugin + +We can add either a Maven or a Gradle plugin. In this example, we show how to add Maven. +First, we add the `Spring Cloud Contract` BOM, as the following example shows: + +==== +[source,xml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=contract_bom,indent=0] +---- +==== + +Next, add the `Spring Cloud Contract Verifier` Maven plugin, as the following example shows: + +==== +[source,xml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=contract_maven_plugin,indent=0] +---- +==== + +Since the plugin was added, you get the `Spring Cloud Contract Verifier` features, which, +from the provided contracts: + +- Generate and run tests +- Produce and install stubs + +You do not want to generate tests, since you, as the consumer, want only to play with the +stubs. You need to skip the test generation and invokation. To do so, run the following commands: + +==== +[source,bash,indent=0] +---- +$ cd local-http-server-repo +$ ./mvnw clean install -DskipTests +---- +==== + +Once you run those commands, you should you see something like the following content in the logs: + +==== +[source,bash,indent=0] +---- +[INFO] --- spring-cloud-contract-maven-plugin:1.0.0.BUILD-SNAPSHOT:generateStubs (default-generateStubs) @ http-server --- +[INFO] Building jar: /some/path/http-server/target/http-server-0.0.1-SNAPSHOT-stubs.jar +[INFO] +[INFO] --- maven-jar-plugin:2.6:jar (default-jar) @ http-server --- +[INFO] Building jar: /some/path/http-server/target/http-server-0.0.1-SNAPSHOT.jar +[INFO] +[INFO] --- spring-boot-maven-plugin:1.5.5.BUILD-SNAPSHOT:repackage (default) @ http-server --- +[INFO] +[INFO] --- maven-install-plugin:2.5.2:install (default-install) @ http-server --- +[INFO] Installing /some/path/http-server/target/http-server-0.0.1-SNAPSHOT.jar to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT.jar +[INFO] Installing /some/path/http-server/pom.xml to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT.pom +[INFO] Installing /some/path/http-server/target/http-server-0.0.1-SNAPSHOT-stubs.jar to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar +---- +==== + +The following line is extremely important: + +==== +[source,bash,indent=0] +---- +[INFO] Installing /some/path/http-server/target/http-server-0.0.1-SNAPSHOT-stubs.jar to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar +---- +==== + +It confirms that the stubs of the `http-server` have been installed in the local +repository. + +[[getting-started-cdc-consumer-run]] +=== Running the Integration Tests + +In order to profit from the Spring Cloud Contract Stub Runner functionality of automatic +stub downloading, you must do the following in your consumer side project (`Loan +Application service`): + +. Add the `Spring Cloud Contract` BOM, as follows: ++ +==== +[source,xml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=contract_bom,indent=0] +---- +==== + +. Add the dependency to `Spring Cloud Contract Stub Runner`, as follows: ++ +==== +[source,xml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=stub_runner,indent=0] +---- +==== + +. Annotate your test class with `@AutoConfigureStubRunner`. In the annotation, provide the +`group-id` and `artifact-id` for the Stub Runner to download the 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] +---- +==== + +. (Optional) Because you are playing with the collaborators offline, you +can also provide the offline work switch (`StubRunnerProperties.StubsMode.LOCAL`). + +Now, when you run your tests, you see something like the following output in the logs: + +==== +[source,bash,indent=0] +---- +2016-07-19 14:22:25.403 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Desired version is + - will try to resolve the latest version +2016-07-19 14:22:25.438 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved version is 0.0.1-SNAPSHOT +2016-07-19 14:22:25.439 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolving artifact com.example:http-server:jar:stubs:0.0.1-SNAPSHOT using remote repositories [] +2016-07-19 14:22:25.451 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved artifact com.example:http-server:jar:stubs:0.0.1-SNAPSHOT to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar +2016-07-19 14:22:25.465 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacking stub from JAR [URI: file:/path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar] +2016-07-19 14:22:25.475 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacked file to [/var/folders/0p/xwq47sq106x1_g3dtv6qfm940000gq/T/contracts100276532569594265] +2016-07-19 14:22:27.737 INFO 41050 --- [ main] o.s.c.c.stubrunner.StubRunnerExecutor : All stubs are now running RunningStubs [namesAndPorts={com.example:http-server:0.0.1-SNAPSHOT:stubs=8080}] +---- +==== + +This output means that Stub Runner has found your stubs and started a server for your application +with a group ID of `com.example` and an artifact ID of `http-server` with version `0.0.1-SNAPSHOT` of +the stubs and with the `stubs` classifier on port `8080`. + +[[getting-started-cdc-consumer-file]] +=== Filing a Pull Request + +What you have done until now is an iterative process. You can play around with the +contract, install it locally, and work on the consumer side until the contract works as +you wish. + +Once you are satisfied with the results and the test passes, you can publish a pull request to +the server side. Currently, the consumer side work is done. + +[[getting-started-cdc-producer]] +== The Producer Side (Fraud Detection server) + +As a developer of the Fraud Detection server (a server to the Loan Issuance service), you +might want to: + +- Take over the pull request +- Write the missing implementation +- Deploy the application + +The following UML diagram shows the fraud detection flow: + +[plantuml, getting-started-cdc-server, png] +---- +"Fraud\nDetection"->"Fraud\nDetection": take over the\n pull request +"Fraud\nDetection"->"Fraud\nDetection": setup\nSpring Cloud\nContract plugin +"Fraud\nDetection"->"Fraud\nDetection\nBuild": run the build +"Fraud\nDetection\nBuild"->"SCC Plugin": generate tests\nstubs \nand stubs artifact \n(e.g. stubs-jar) +"SCC Plugin"->"Fraud\nDetection\nBuild": tests and stubs generated +"Fraud\nDetection\nBuild"->"Fraud\nDetection\nBuild": run tests +"Fraud\nDetection\nBuild"->"Fraud\nDetection": generated tests failed! +"Fraud\nDetection"->"Fraud\nDetection": setup\nbase classes\nfor contract tests +"Fraud\nDetection"->"Fraud\nDetection\nBuild": run the build +"Fraud\nDetection\nBuild"->"SCC Plugin": generate tests\nstubs \nand stubs artifact \n(e.g. stubs-jar) +"SCC Plugin"->"Fraud\nDetection\nBuild": tests and stubs generated +"Fraud\nDetection\nBuild"->"Fraud\nDetection\nBuild": run tests +"Fraud\nDetection\nBuild"->"Fraud\nDetection": all the tests passed! +"Fraud\nDetection"->"Fraud\nDetection": commit and push changes +"Fraud\nDetection"->"CI": commit pushed!\nTriggers the build +"CI"->"Stub Storage": build successful,\nupload artifacts +---- + +[[getting-started-cdc-producer-pr]] +=== Taking over the Pull Request + +As a reminder, the following listing shows the initial implementation: + +==== +[source,java,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=server_api,indent=0] +include:../:{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=initial_impl,indent=0] +} +---- +==== + +Then you can run the following commands: + +==== +[source,bash,indent=0] +---- +$ git checkout -b contract-change-pr master +$ git pull https://your-git-server.com/server-side-fork.git contract-change-pr +---- +==== + +You must add the dependencies needed by the autogenerated tests, as follows: + +==== +[source,xml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=verifier_test_dependencies,indent=0] +---- +==== + +In the configuration of the Maven plugin, you must pass the `packageWithBaseClasses` property, as follows: + +==== +[source,xml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=contract_maven_plugin,indent=0] +---- +==== + +IMPORTANT: This example uses "`convention-based`" naming by setting the +`packageWithBaseClasses` property. Doing so means that the two last packages combine to +make the name of the base test class. In our case, the contracts were placed under +`src/test/resources/contracts/fraud`. Since you do not have two packages starting from +the `contracts` folder, pick only one, which should be `fraud`. Add the `Base` suffix and +capitalize `fraud`. That gives you the `FraudBase` test class name. + +All the generated tests extend that class. Over there, you can set up your Spring Context +or whatever is necessary. In this case, you should use https://github.com/rest-assured/rest-assured[Rest Assured MVC] to +start the server side `FraudDetectionController`. The following listing shows the +`FraudBase` class: + +==== +[source,java,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-server/src/test/java/com/example/fraud/FraudBase.java[] +---- +==== + +Now, if you run the `./mvnw clean install`, you get something like the following output: + +==== +[source,bash,indent=0] +---- +Results : + +Tests in error: + ContractVerifierTest.validate_shouldMarkClientAsFraud:32 » IllegalState Parsed... +---- +==== + +This error occurs because you have a new contract from which a test was generated, and it +failed since you have not implemented the feature. The auto-generated test would look +like the following test method: + +==== +[source,java,indent=0] +---- +@Test +public void validate_shouldMarkClientAsFraud() throws Exception { + // given: + MockMvcRequestSpecification request = given() + .header("Content-Type", "application/vnd.fraud.v1+json") + .body("{\"client.id\":\"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("['rejection.reason']").isEqualTo("Amount too high"); +} +---- +==== + +If you used the Groovy DSL, you can see that all the `producer()` parts of the Contract that were present in the +`value(consumer(...), producer(...))` blocks got injected into the test. +If you use YAML, the same applies for the `matchers` sections of the `response`. + +Note that, on the producer side, you are also doing TDD. The expectations are expressed +in the form of a test. This test sends a request to our own application with the URL, +headers, and body defined in the contract. It also expects precisely defined values +in the response. In other words, you have the `red` part of `red`, `green`, and +`refactor`. It is time to convert the `red` into the `green`. + +[[getting-started-cdc-producer-impl]] +=== Write the Missing Implementation + +Because you know the expected input and expected output, you can write the missing +implementation as follows: + +==== +[source,java,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=server_api,indent=0] +include:../:{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=new_impl,indent=0] +include:../:{introduction_url}/samples/standalone/dsl/http-server/src/main/java/com/example/fraud/FraudDetectionController.java[tags=initial_impl,indent=0] +} +---- +==== + +When you run `./mvnw clean install` again, the tests pass. Since the Spring Cloud +Contract Verifier plugin adds the tests to the `generated-test-sources`, you can +actually run those tests from your IDE. + +[[getting-started-cdc-producer-deploy]] +=== Deploying Your Application + +Once you finish your work, you can deploy your changes. To do so, you must first merge the +branch by running the following commands: + +==== +[source,bash,indent=0] +---- +$ git checkout master +$ git merge --no-ff contract-change-pr +$ git push origin master +---- +==== + +Your CI might run a command such as `./mvnw clean deploy`, which would publish both the +application and the stub artifacts. + +[[getting-started-cdc-consumer-final]] +== Consumer Side (Loan Issuance), Final Step + +As a developer of the loan issuance service (a consumer of the Fraud Detection server), you need to: + +- Merge our feature branch to `master` +- Switch to online mode of working + +The following UML diagram shows the final state of the process: + +[plantuml, getting-started-cdc-client-final, png] +---- +"Loan\nIssuance"->"Loan\nIssuance": merge the\nfeature branch\nto master branch +"Loan\nIssuance"->"Loan\nIssuance": setup SCC Stub Runner\nto fetch stubs\nfrom Stub Storage +"Loan\nIssuance"->"LI\nSCC\nStub Runner": start stubs\nof FD from\nStub Storage +"LI\nSCC\nStub Runner"->"Stub Storage": find stubs of [FD] +"Stub Storage"->"LI\nSCC\nStub Runner": stubs of [FD] found +"LI\nSCC\nStub Runner"->"FD stub": run stubs of [FD] +"FD stub"->"LI\nSCC\nStub Runner": [FD] stub is running +"LI\nSCC\nStub Runner"->"Loan\nIssuance": stubs running and ready for the test +"Loan\nIssuance"->"Loan\nIssuance": run a test +"Loan\nIssuance"->"FD stub": the test\nsends a request\nto the running stub +"FD stub"->"Loan\nIssuance": stub responds successfuly +"Loan\nIssuance"->"Loan\nIssuance": the test passes successfully +---- + +[[getting-started-cdc-consumer-final-merge]] +=== Merging a Branch to Master + +The following commands show one way to merge a branch into master with Git: + +==== +[source,bash,indent=0] +---- +$ git checkout master +$ git merge --no-ff contract-change-pr +---- +==== + +[[getting-started-cdc-consumer-final-online]] +=== Working Online + +Now you can disable the offline work for Spring Cloud Contract Stub Runner and indicate +where the repository with your stubs is located. At this moment, the stubs of the server +side are automatically downloaded from Nexus/Artifactory. You can set the value of +`stubsMode` to `REMOTE`. The following code shows an example of +achieving the same thing by changing the properties: + +==== +[source,yaml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[] +---- +==== + +That's it. You have finished the tutorial. + diff --git a/docs/modules/ROOT/pages/getting-started/first-application.adoc b/docs/modules/ROOT/pages/getting-started/first-application.adoc new file mode 100644 index 0000000000..a194ff9bef --- /dev/null +++ b/docs/modules/ROOT/pages/getting-started/first-application.adoc @@ -0,0 +1,491 @@ +[[getting-started-first-application]] += Developing Your First Spring Cloud Contract-based Application + +This brief tour walks through using Spring Cloud Contract. It consists of the following topics: + +* <> +* <> + +You can find an even more brief tour +<>. + +For the sake of this example, the `Stub Storage` is Nexus/Artifactory. + +The following UML diagram shows the relationship of the parts of Spring Cloud Contract: + +image::getting-started-three-second.png[Getting started first application] + +[[getting-started-first-application-producer]] +== On the Producer Side + +To start working with `Spring Cloud Contract`, you can add the Spring Cloud Contract Verifier +dependency and plugin to your build file, as the following example shows: + +==== +[source,xml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=verifier_test_dependencies,indent=0] +---- +==== + +The following listing shows how to add the plugin, which should go in the build/plugins +portion of the file: + +==== +[source,xml,indent=0] +---- + + org.springframework.cloud + spring-cloud-contract-maven-plugin + ${spring-cloud-contract.version} + true + +---- +==== + +[TIP] +==== +The easiest way to get started is to go to https://start.spring.io[the Spring Initializr] +and add "`Web`" and "`Contract Verifier`" as dependencies. Doing so pulls in the previously +mentioned dependencies and everything else you need in the `pom.xml` file (except for +setting the base test class, which we cover later in this section). The following image +shows the settings to use in https://start.spring.io[the Spring Initializr]: + +image::start_spring_io_dependencies.png[width=800,alt=Spring Initializr with Web and Contract Verifier] +==== + +Now you can add files with `REST/` messaging contracts +expressed in either Groovy DSL or YAML to the contracts directory, which is set by the +`contractsDslDir` property. By default, it is `$rootDir/src/test/resources/contracts`. +Note that the file name does not matter. You can organize your contracts within this +directory with whatever naming scheme you like. + +For the HTTP stubs, a contract defines what kind of response should be returned for a +given request (taking into account the HTTP methods, URLs, headers, status codes, and so +on). The following example shows an HTTP stub contract in both Groovy and YAML: + +==== +[source,groovy,indent=0,role="primary"] +.groovy +---- +package contracts + +org.springframework.cloud.contract.spec.Contract.make { + request { + method 'PUT' + url '/fraudcheck' + body([ + "client.id": $(regex('[0-9]{10}')), + loanAmount: 99999 + ]) + headers { + contentType('application/json') + } + } + response { + status OK() + body([ + fraudCheckStatus: "FRAUD", + "rejection.reason": "Amount too high" + ]) + headers { + contentType('application/json') + } + } +} +---- + +[source,yaml,indent=0,role="secondary"] +.yaml +---- +request: + method: PUT + url: /fraudcheck + body: + "client.id": 1234567890 + loanAmount: 99999 + headers: + Content-Type: application/json + matchers: + body: + - path: $.['client.id'] + type: by_regex + value: "[0-9]{10}" +response: + status: 200 + body: + fraudCheckStatus: "FRAUD" + "rejection.reason": "Amount too high" + headers: + Content-Type: application/json;charset=UTF-8 +---- +==== + +If you need to use messaging, you can define: + +* The input and output messages (taking into account from where it +was sent, the message body, and the header). +* The methods that should be called after the message is received. +* The methods that, when called, should trigger a message. + +The following example shows a Camel messaging contract: + +==== +[source,groovy,indent=0,role="primary"] +.groovy +---- +include:../:{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_method_dsl] +---- + +[source,yaml,indent=0,role="secondary"] +.yaml +---- +include:../:{verifier_core_path}/src/test/resources/yml/contract_message_scenario1.yml[indent=0] +---- +==== + +Running `./mvnw clean install` automatically generates tests that verify the application +compliance with the added contracts. By default, the generated tests are under +`org.springframework.cloud.contract.verifier.tests.`. + +The generated tests may differ, depending on which framework and test type you have set up +in your plugin. + +In the next listing, you can find: + +- The default test mode for HTTP contracts in `MockMvc` +- A JAX-RS client with the `JAXRS` test mode +- A `WebTestClient`-based test (this is particularly recommended while working with +Reactive, `Web-Flux`-based applications) set with the `WEBTESTCLIENT` test mode + +NOTE: You need only one of these test frameworks. MockMvc is the default. To use one +of the other frameworks, add its library to your classpath. + +The following listing shows samples for all frameworks: + +==== +[source,java,indent=0,role="primary"] +.mockmvc +---- +@Test +public void validate_shouldMarkClientAsFraud() throws Exception { + // given: + MockMvcRequestSpecification request = given() + .header("Content-Type", "application/vnd.fraud.v1+json") + .body("{\"client.id\":\"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("['rejection.reason']").isEqualTo("Amount too high"); +} +---- + +[source,java,indent=0,role="secondary"] +.jaxrs +---- +@SuppressWarnings("rawtypes") +public class FooTest { + WebTarget webTarget; + + @Test + public void validate_() throws Exception { + + // when: + Response response = webTarget + .path("/users") + .queryParam("limit", "10") + .queryParam("offset", "20") + .queryParam("filter", "email") + .queryParam("sort", "name") + .queryParam("search", "55") + .queryParam("age", "99") + .queryParam("name", "Denis.Stepanov") + .queryParam("email", "bob@email.com") + .request() + .build("GET") + .invoke(); + String responseAsString = response.readEntity(String.class); + + // then: + assertThat(response.getStatus()).isEqualTo(200); + + // and: + DocumentContext parsedJson = JsonPath.parse(responseAsString); + assertThatJson(parsedJson).field("['property1']").isEqualTo("a"); + } + +} +---- + +[source,java,indent=0,role="secondary"] +.webtestclient +---- +@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"); + } +---- +==== + +As the implementation of the functionalities described by the contracts is not yet +present, the tests fail. + +To make them pass, you must add the correct implementation of handling either HTTP +requests or messages. Also, you must add a base test class for auto-generated +tests to the project. This class is extended by all the auto-generated tests and should +contain all the setup necessary information needed to run them (for example, +`RestAssuredMockMvc` controller setup or messaging test setup). + +The following example, from `pom.xml`, shows how to specify the base test class: + +==== +[source,xml,indent=0] +---- + + + + org.springframework.cloud + spring-cloud-contract-maven-plugin + 2.1.2.RELEASE + true + + com.example.contractTest.BaseTestClass <1> + + + + org.springframework.boot + spring-boot-maven-plugin + + + +---- +<1> The `baseClassForTests` element lets you specify your base test class. It must be a child +of a `configuration` element within `spring-cloud-contract-maven-plugin`. +==== + +The following example shows a minimal (but functional) base test class: + +==== +[source,java, indent=0] +---- +package com.example.contractTest; + +import org.junit.Before; + +import io.restassured.module.mockmvc.RestAssuredMockMvc; + +public class BaseTestClass { + + @Before + public void setup() { + RestAssuredMockMvc.standaloneSetup(new FraudController()); + } +} +---- +==== + +This minimal class really is all you need to get your tests to work. It serves as a +starting place to which the automatically generated tests attach. + +Now we can move on to the implementation. For that, we first need a data class, which we +then use in our controller. The following listing shows the data class: + +==== +[source,java, indent=0] +---- +package com.example.Test; + +import com.fasterxml.jackson.annotation.JsonProperty; + +public class LoanRequest { + + @JsonProperty("client.id") + private String clientId; + + private Long loanAmount; + + public String getClientId() { + return clientId; + } + + public void setClientId(String clientId) { + this.clientId = clientId; + } + + public Long getLoanAmount() { + return loanAmount; + } + + public void setLoanRequestAmount(Long loanAmount) { + this.loanAmount = loanAmount; + } +} +---- +==== + +The preceding class provides an object in which we can store the parameters. Because the +client ID in the contract is called `client.id`, we need to use the +`@JsonProperty("client.id")` parameter to map it to the `clientId` field. + +Now we can move along to the controller, which the following listing shows: + +==== +[source,java, indent=0] +---- +package com.example.docTest; + +import org.springframework.web.bind.annotation.PutMapping; +import org.springframework.web.bind.annotation.RequestBody; +import org.springframework.web.bind.annotation.RestController; + +@RestController +public class FraudController { + + @PutMapping(value = "/fraudcheck", consumes="application/json", produces="application/json") + public String check(@RequestBody LoanRequest loanRequest) { <1> + + if (loanRequest.getLoanAmount() > 10000) { <2> + return "{fraudCheckStatus: FRAUD, rejection.reason: Amount too high}"; <3> + } else { + return "{fraudCheckStatus: OK, acceptance.reason: Amount OK}"; <4> + } + } +} +---- +<1> We map the incoming parameters to a `LoanRequest` object. +<2> We check the requested loan amount to see if it is too much. +<3> If it is too much, we return the JSON (created with a simple string here) that the +test expects. +<4> If we had a test to catch when the amount is allowable, we could match it to this output. +==== + +The `FraudController` is about as simple as things get. You can do much more, including +logging, validating the client ID, and so on. + +Once the implementation and the test base class are in place, the tests pass, and both the +application and the stub artifacts are built and installed in the local Maven repository. +Information about installing the stubs jar to the local repository appears in the logs, as +the following example shows: + +==== +[source,bash,indent=0] +---- + [INFO] --- spring-cloud-contract-maven-plugin:1.0.0.BUILD-SNAPSHOT:generateStubs (default-generateStubs) @ http-server --- + [INFO] Building jar: /some/path/http-server/target/http-server-0.0.1-SNAPSHOT-stubs.jar + [INFO] + [INFO] --- maven-jar-plugin:2.6:jar (default-jar) @ http-server --- + [INFO] Building jar: /some/path/http-server/target/http-server-0.0.1-SNAPSHOT.jar + [INFO] + [INFO] --- spring-boot-maven-plugin:1.5.5.BUILD-SNAPSHOT:repackage (default) @ http-server --- + [INFO] + [INFO] --- maven-install-plugin:2.5.2:install (default-install) @ http-server --- + [INFO] Installing /some/path/http-server/target/http-server-0.0.1-SNAPSHOT.jar to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT.jar + [INFO] Installing /some/path/http-server/pom.xml to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT.pom + [INFO] Installing /some/path/http-server/target/http-server-0.0.1-SNAPSHOT-stubs.jar to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar +---- +==== + +You can now merge the changes and publish both the application and the stub artifacts +in an online repository. + +[[getting-started-first-application-consumer]] +== On the Consumer Side + +You can use Spring Cloud Contract Stub Runner in the integration tests to get a running +WireMock instance or messaging route that simulates the actual service. + +To get started, add the dependency to `Spring Cloud Contract Stub Runner`, as follows: + +==== +[source,xml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=stub_runner,indent=0] +---- +==== + +You can get the Producer-side stubs installed in your Maven repository in either of two +ways: + +* By checking out the Producer side repository and adding contracts and generating the +stubs by running the following commands: ++ +==== +[source,bash,indent=0] +---- +$ cd local-http-server-repo +$ ./mvnw clean install -DskipTests +---- +==== +NOTE: The tests are skipped because the Producer-side contract implementation is not yet +in place, so the automatically-generated contract tests fail. + +* By getting existing producer service stubs from a remote repository. To do so, +pass the stub artifact IDs and artifact repository URL as `Spring Cloud Contract Stub +Runner` properties, as the following example shows: ++ +==== +[source,yaml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[] +---- +==== + +Now you can annotate your test class with `@AutoConfigureStubRunner`. In the annotation, +provide the `group-id` and `artifact-id` for `Spring Cloud Contract Stub Runner` to run +the collaborators' stubs for you, as the following example shows: + +==== +[source,java, indent=0] +---- +@RunWith(SpringRunner.class) +@SpringBootTest(webEnvironment=WebEnvironment.NONE) +@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:6565"}, + stubsMode = StubRunnerProperties.StubsMode.LOCAL) +public class LoanApplicationServiceTests { + . . . +} +---- +==== + +TIP: Use the `REMOTE` `stubsMode` when downloading stubs from an online repository and +`LOCAL` for offline work. + +In your integration test, you can receive stubbed versions of HTTP responses or messages +that are expected to be emitted by the collaborator service. You can see entries similar +to the following in the build logs: + +==== +[source,bash,indent=0] +---- +2016-07-19 14:22:25.403 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Desired version is + - will try to resolve the latest version +2016-07-19 14:22:25.438 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved version is 0.0.1-SNAPSHOT +2016-07-19 14:22:25.439 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolving artifact com.example:http-server:jar:stubs:0.0.1-SNAPSHOT using remote repositories [] +2016-07-19 14:22:25.451 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Resolved artifact com.example:http-server:jar:stubs:0.0.1-SNAPSHOT to /path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar +2016-07-19 14:22:25.465 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacking stub from JAR [URI: file:/path/to/your/.m2/repository/com/example/http-server/0.0.1-SNAPSHOT/http-server-0.0.1-SNAPSHOT-stubs.jar] +2016-07-19 14:22:25.475 INFO 41050 --- [ main] o.s.c.c.stubrunner.AetherStubDownloader : Unpacked file to [/var/folders/0p/xwq47sq106x1_g3dtv6qfm940000gq/T/contracts100276532569594265] +2016-07-19 14:22:27.737 INFO 41050 --- [ main] o.s.c.c.stubrunner.StubRunnerExecutor : All stubs are now running RunningStubs [namesAndPorts={com.example:http-server:0.0.1-SNAPSHOT:stubs=8080}] +---- +==== + diff --git a/docs/modules/ROOT/pages/getting-started/introducing-spring-cloud-contract.adoc b/docs/modules/ROOT/pages/getting-started/introducing-spring-cloud-contract.adoc new file mode 100644 index 0000000000..4cedb1d226 --- /dev/null +++ b/docs/modules/ROOT/pages/getting-started/introducing-spring-cloud-contract.adoc @@ -0,0 +1,126 @@ +[[getting-started-introducing-spring-cloud-contract]] += Introducing Spring Cloud Contract + +Spring Cloud Contract moves TDD to the level of software architecture. +It lets you perform consumer-driven and producer-driven contract testing. + +[[getting-started-introducing-spring-cloud-contract-history]] +== 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 (https://github.com/Codearte[Codearte]). + +The `0.1.0` release took place on 26 Jan 2015, and it became stable with `1.0.0` release on 29 Feb 2016. + +[[getting-started-introducing-spring-cloud-contract-why]] +=== Why Do You Need It? + +Assume that we have a system that consists of multiple microservices, as the following +image shows: + +image::Deps.png[Microservices Architecture] + +[[getting-started-introducing-spring-cloud-contract-testing-issues]] +=== Testing Issues + +If we want to test the application in the top left corner of the image in the preceding +section to determine whether it can communicate with other services, we could do one of +two things: + +- Deploy all microservices and perform end-to-end tests. +- Mock other microservices in unit and integration tests. + +Both have their advantages but also a lot of disadvantages. + +*Deploy all microservices and perform end-to-end tests* + +Advantages: + +- Simulates production. +- Tests real communication between services. + +Disadvantages: + +- To test one microservice, we have to deploy six microservices, a couple of databases, +and other items. +- The environment where the tests run is locked for a single suite of tests (nobody else +would be able to run the tests in the meantime). +- They take a long time to run. +- The feedback comes very late in the process. +- They are extremely hard to debug. + +*Mock other microservices in unit and integration tests* + +Advantages: + +- They provide very fast feedback. +- They have no infrastructure requirements. + +Disadvantages: + +- The implementor of the service creates stubs that might have nothing to do with +reality. +- You can go to production with passing tests and failing production. + +To solve the aforementioned issues, Spring Cloud Contract was created. The main idea is to +give you very fast feedback, without the need to set up the +whole world of microservices. If you work on stubs, then the only applications you need +are those that your application directly uses. The following image shows the relationship +of stubs to an application: + +image::Stubs2.png[Stubbed Services] + +Spring Cloud Contract gives you the certainty that the stubs that you use were +created by the service that you call. Also, if you can use them, it means that they +were tested against the producer's side. In short, you can trust those stubs. + +[[getting-started-introducing-spring-cloud-contract-purposes]] +== Purposes + +The main purposes of Spring Cloud Contract are: + +- To ensure that HTTP and messaging stubs (used when developing the client) do exactly +what the actual server-side implementation does. +- To promote the ATDD (acceptance test-driven development) method, and the microservices architectural style. +- To provide a way to publish changes in contracts that are immediately visible on both sides. +- To generate boilerplate test code to be used on the server side. + +By default, Spring Cloud Contract integrates with http://wiremock.org[Wiremock] as the HTTP server stub. + +IMPORTANT: Spring Cloud Contract's purpose is NOT to start writing business +features in the contracts. Assume that we have a business use case of fraud check. If a +user can be a fraud for 100 different reasons, we would assume that you would create two +contracts, one for the positive case and one for the negative case. Contract tests are +used to test contracts between applications, not to simulate full behavior. + +[[getting-started-what-is-a-contract]] +== What Is a Contract? + +As consumers of services, we need to define what exactly we want to achieve. We need to +formulate our expectations. That is why we write contracts. In other words, a contract is +an agreement on how the API or message communication should look. Consider the following example: + +Assume that you want to send a request that contains the ID of a client company and the +amount it wants to borrow from us. You also want to send it to the `/fraudcheck` URL by using +the `PUT` method. The following listing shows a contract to check whether a client should +be marked as a fraud in both Groovy and YAML: + +==== +[source,groovy,indent=0,role="primary"] +.groovy +---- +include:../:{introduction_url}/samples/standalone/dsl/http-server/src/test/resources/contracts/fraud/shouldMarkClientAsFraud.groovy[] +---- +//// + +//// +[source,yaml,indent=0,role="secondary"] +.yaml +---- +include:../:{introduction_url}/samples/standalone/dsl/http-server/src/test/resources/contracts/yml/fraud/shouldMarkClientAsFraud.yml[] +---- +==== + +IMPORTANT: It is expected that contracts are coming from a **trusted source**. You should never download nor interact with contracts coming from untrusted locations. + diff --git a/docs/modules/ROOT/pages/getting-started/three-second-tour.adoc b/docs/modules/ROOT/pages/getting-started/three-second-tour.adoc new file mode 100644 index 0000000000..a275d49171 --- /dev/null +++ b/docs/modules/ROOT/pages/getting-started/three-second-tour.adoc @@ -0,0 +1,176 @@ +[[getting-started-three-second-tour]] += A Three-second Tour + +This very brief tour walks through using Spring Cloud Contract. It consists of the +following topics: + +* <> +* <> + +You can find a somewhat longer tour +<>. + +The following UML diagram shows the relationship of the parts within Spring Cloud Contract: + +[plantuml, getting-started-three-second, png] +---- +"API Producer"->"API Producer": add Spring Cloud \nContract (SCC) plugin +"API Producer"->"API Producer": add SCC Verifier dependency +"API Producer"->"API Producer": define contracts +"API Producer"->"Build": run build +"Build"->"SCC Plugin": generate \ntests, stubs and stubs \nartifact (e.g. stubs-jar) +"Build"->"Stub Storage": upload contracts \nand stubs and the project arifact +"Build"->"API Producer": Build successful +"API Consumer"->"API Consumer": add SCC Stub Runner \ndependency +"API Consumer"->"API Consumer": write a SCC Stub Runner \nbased contract test +"SCC Stub Runner"->"Stub Storage": test asks for [API Producer] stubs +"Stub Storage"->"SCC Stub Runner": fetch the [API Producer] stubs +"SCC Stub Runner"->"SCC Stub Runner": run in memory\n HTTP server stubs +"API Consumer"->"SCC Stub Runner": send a request \nto the HTTP server stub +"SCC Stub Runner"->"API Consumer": communication is correct +---- + +[[getting-started-three-second-tour-producer]] +== On the Producer Side + +To start working with Spring Cloud Contract, you can add files with REST or messaging contracts +expressed in either Groovy DSL or YAML to the contracts directory, which is set by the +`contractsDslDir` property. By default, it is `$rootDir/src/test/resources/contracts`. + +Then you can add the Spring Cloud Contract Verifier dependency and plugin to your build file, as +the following example shows: + +==== +[source,xml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-server/pom.xml[tags=verifier_test_dependencies,indent=0] +---- +==== + +The following listing shows how to add the plugin, which should go in the build/plugins +portion of the file: + +==== +[source,xml,indent=0] +---- + + org.springframework.cloud + spring-cloud-contract-maven-plugin + ${spring-cloud-contract.version} + true + +---- +==== + +Running `./mvnw clean install` automatically generates tests that verify the application +compliance with the added contracts. By default, the tests get generated under +`org.springframework.cloud.contract.verifier.tests.`. + +As the implementation of the functionalities described by the contracts is not yet +present, the tests fail. + +To make them pass, you must add the correct implementation of either handling HTTP +requests or messages. Also, you must add a base test class for auto-generated +tests to the project. This class is extended by all the auto-generated tests, and it +should contain all the setup information necessary to run them (for example `RestAssuredMockMvc` +controller setup or messaging test setup). + +The following example, from `pom.xml`, shows how to specify the base test class: + +==== +[source,xml,indent=0] +---- + + + + org.springframework.cloud + spring-cloud-contract-maven-plugin + 2.1.2.RELEASE + true + + com.example.contractTest.BaseTestClass <1> + + + + org.springframework.boot + spring-boot-maven-plugin + + + +---- +<1> The `baseClassForTests` element lets you specify your base test class. It must be a child +of a `configuration` element within `spring-cloud-contract-maven-plugin`. +==== + +Once the implementation and the test base class are in place, the tests pass, and both the +application and the stub artifacts are built and installed in the local Maven repository. +You can now merge the changes, and you can publish both the application and the stub artifacts +in an online repository. + +[[getting-started-three-second-tour-consumer]] +== On the Consumer Side + +You can use `Spring Cloud Contract Stub Runner` in the integration tests to get a running +WireMock instance or messaging route that simulates the actual service. + +To do so, add the dependency to `Spring Cloud Contract Stub Runner`, as the +following example shows: + +==== +[source,xml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-client/pom.xml[tags=stub_runner,indent=0] +---- +==== + +You can get the Producer-side stubs installed in your Maven repository in either of two +ways: + +* By checking out the Producer side repository and adding contracts and generating the stubs +by running the following commands: ++ +==== +[source,bash,indent=0] +---- +$ cd local-http-server-repo +$ ./mvnw clean install -DskipTests +---- +==== + +TIP: The tests are being skipped because the producer-side contract implementation is not +in place yet, so the automatically-generated contract tests fail. + +* By getting already-existing producer service stubs from a remote repository. To do so, +pass the stub artifact IDs and artifact repository URL as `Spring Cloud Contract +Stub Runner` properties, as the following example shows: ++ +==== +[source,yaml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[] +---- +==== + +Now you can annotate your test class with `@AutoConfigureStubRunner`. In the annotation, +provide the `group-id` and `artifact-id` values for `Spring Cloud Contract Stub Runner` to +run the collaborators' stubs for you, as the following example shows: + +==== +[source,java, indent=0] +---- +@RunWith(SpringRunner.class) +@SpringBootTest(webEnvironment=WebEnvironment.NONE) +@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:6565"}, + stubsMode = StubRunnerProperties.StubsMode.LOCAL) +public class LoanApplicationServiceTests { + . . . +} +---- +==== + +TIP: Use the `REMOTE` `stubsMode` when downloading stubs from an online repository and +`LOCAL` for offline work. + +Now, in your integration test, you can receive stubbed versions of HTTP responses or +messages that are expected to be emitted by the collaborator service. + diff --git a/docs/modules/ROOT/pages/getting-started/whats-next.adoc b/docs/modules/ROOT/pages/getting-started/whats-next.adoc new file mode 100644 index 0000000000..3e257bf58f --- /dev/null +++ b/docs/modules/ROOT/pages/getting-started/whats-next.adoc @@ -0,0 +1,30 @@ +[[getting-started-whats-next]] += Next Steps + +Hopefully, this section provided some of the {project-full-name} basics and got you on your way +to writing your own applications. If you are a task-oriented type of developer, you might +want to jump over to https://spring.io and check out some +https://spring.io/guides/[getting started] guides that solve specific "`How do I do that +with Spring?`" problems. We also have {project-full-name}-specific +"`<>`" reference documentation. + +Otherwise, the next logical step is to read <>. If +you are really impatient, you could also jump ahead and read about +<>. + +In addition, you can check out the following videos: + +- "Consumer Driven Contracts and Your Microservice Architecture" by Olga Maciaszek-Sharma and Marcin Grzejszczak + +video::pDkC_00hhvA[youtube,width=640,height=480] + +- "Contract Tests in the Enterprise" by Marcin Grzejszczak + +video::ZyHG-VOzPZg[youtube,width=640,height=480] + +- "Why Contract Tests Matter?" by Marcin Grzejszczak + +video::TvpkZu1e2Dc[youtube,start=6262,width=640,height=480] + +You can find the default project samples at +https://github.com/spring-cloud-samples/spring-cloud-contract-samples[samples]. diff --git a/docs/modules/ROOT/pages/howto.adoc b/docs/modules/ROOT/pages/howto.adoc index 76c30db2e7..39d40dcee2 100644 --- a/docs/modules/ROOT/pages/howto.adoc +++ b/docs/modules/ROOT/pages/howto.adoc @@ -14,1047 +14,3 @@ the `{project-name}` tag). We are also more than happy to extend this section. If you want to add a "`how-to`", send us a {github-code}[pull request]. -[[why-spring-cloud-contract]] -== Why use Spring Cloud Contract? - -Spring Cloud Contract works great in a polyglot environment. This project has a lot of -really interesting features. Quite a few of these features definitely make -Spring Cloud Contract Verifier stand out on the market of Consumer Driven Contract -(CDC) tooling. The most interesting features include the following: - -- Ability to do CDC with messaging. -- Clear and easy to use, statically typed DSL. -- Ability to copy-paste your current JSON file to the contract and edit only its elements. -- Automatic generation of tests from the defined contract. -- Stub Runner functionality: The stubs are automatically downloaded at runtime from Nexus or Artifactory. -- Spring Cloud integration: No discovery service is needed for integration tests. -- Ability to add support for any language & framework through Docker. - -[[how-to-not-write-contracts-in-groovy]] -== How Can I Write Contracts in a Language Other than Groovy? - -You can write a contract in YAML. See <> for more information. - -We are working on allowing more ways of describing the contracts. You can check the {github-issues}[github-issues] for more information. - -[[how-to-provide-dynamic-values]] -== How Can I Provide Dynamic Values to a Contract? - -One of the biggest challenges related to stubs is their reusability. Only if they can be widely used can they serve their purpose. -The hard-coded values (such as dates and IDs) of request and response elements generally make that difficult. -Consider the following JSON request: - -==== -[source,json,indent=0] ----- -{ - "time" : "2016-10-10 20:10:15", - "id" : "9febab1c-6f36-4a0b-88d6-3b6a6d81cd4a", - "body" : "foo" -} ----- -==== - -Now consider the following JSON response: - -==== -[source,json,indent=0] ----- -{ - "time" : "2016-10-10 21:10:15", - "id" : "c4231e1f-3ca9-48d3-b7e7-567d55f0d051", - "body" : "bar" -} ----- -==== - -Imagine the pain required to set the proper value of the `time` field (assume that this content is generated by the -database) by changing the clock in the system or by providing stub implementations of data providers. The same is related -to the `id` field. You could create a stubbed implementation of UUID generator, but doing so makes little sense. - -So, as a consumer, you want to send a request that matches any form of a time or any UUID. That way, your system -works as usual, generating data without you having to stub out anything. Assume that, in case of the aforementioned -JSON, the most important part is the `body` field. You can focus on that and provide matching for other fields. In other words, -you would like the stub to work as follows: - -==== -[source,json,indent=0] ----- -{ - "time" : "SOMETHING THAT MATCHES TIME", - "id" : "SOMETHING THAT MATCHES UUID", - "body" : "foo" -} ----- -==== - -As far as the response goes, as a consumer, you need a concrete value on which you can operate. -Consequently, the following JSON is valid: - -==== -[source,json,indent=0] ----- -{ - "time" : "2016-10-10 21:10:15", - "id" : "c4231e1f-3ca9-48d3-b7e7-567d55f0d051", - "body" : "bar" -} ----- -==== - -In the previous sections, we generated tests from contracts. So, from the producer's side, the situation looks -much different. We parse the provided contract, and, in the test, we want to send a real request to your endpoints. -So, for the case of a producer for the request, we cannot have any sort of matching. We need concrete values on which the -producer's backend can work. Consequently, the following JSON would be valid: - -==== -[source,json,indent=0] ----- -{ - "time" : "2016-10-10 20:10:15", - "id" : "9febab1c-6f36-4a0b-88d6-3b6a6d81cd4a", - "body" : "foo" -} ----- -==== - -On the other hand, from the point of view of the validity of the contract, the response does not necessarily have to -contain concrete values for `time` or `id`. Suppose you generate those on the producer side. Again, you -have to do a lot of stubbing to ensure that you always return the same values. That is why, from the producer's side, -you might want the following response: - -==== -[source,json,indent=0] ----- -{ - "time" : "SOMETHING THAT MATCHES TIME", - "id" : "SOMETHING THAT MATCHES UUID", - "body" : "bar" -} ----- -==== - -How can you then provide a matcher for the consumer and a concrete value for the producer (and the opposite at some other time)? -Spring Cloud Contract lets you provide a dynamic value. That means that it can differ for both -sides of the communication. - -You can read more about this in the <> section. - -IMPORTANT: Read the https://groovy-lang.org/json.html[Groovy docs related to JSON] to understand how to -properly structure the request and response bodies. - -[[how-to-do-stubs-versioning]] -== How to Do Stubs versioning? - -This section covers versioning of the stubs, which you can handle in a number of different ways: - -* <> -* <> -* <> - -[[how-to-api-versioning]] -=== API Versioning - -What does versioning really mean? If you refer to the API version, there are -different approaches: - -- Use hypermedia links and do not version your API by any means -- Pass the version through headers and URLs - -We do not try to answer the question of which approach is better. You should pick whatever -suits your needs and lets you generate business value. - -Assume that you do version your API. In that case, you should provide as many contracts with as many versions as you support. -You can create a subfolder for every version or append it to the contract name -- whatever suits you best. - -[[how-to-jar-versioning]] -=== JAR versioning - -If, by versioning, you mean the version of the JAR that contains the stubs, then there are essentially two main approaches. - -Assume that you do continuous delivery and deployment, which means that you generate a new version of -the jar each time you go through the pipeline and that the jar can go to production at any time. For example, your jar version -looks like the following (because it got built on the 20.10.2016 at 20:15:21) : - -==== -[source,groovy,indent=0] ----- -1.0.0.20161020-201521-RELEASE ----- -==== - -In that case, your generated stub jar should look like the following: - -==== -[source,groovy,indent=0] ----- -1.0.0.20161020-201521-RELEASE-stubs.jar ----- -==== - -In this case, you should, inside your `application.yml` or `@AutoConfigureStubRunner` when -referencing stubs, provide the latest version of the stubs. You can do that by passing the -`+` sign. the following example shows how to do so: - -==== -[source,java,indent=0] ----- -@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:8080"}) ----- -==== - -If the versioning, however, is fixed (for example, `1.0.4.RELEASE` or `2.1.1`), you have to set the concrete value of the jar -version. The following example shows how to do so for version 2.1.1: - -==== -[source,java,indent=0] ----- -@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:2.1.1:stubs:8080"}) ----- -==== - -[[how-to-dev-or-prod-stubs]] -=== Development or Production Stubs - -You can manipulate the classifier to run the tests against the current development version -of the stubs of other services or the ones that were deployed to production. If you alter -your build to deploy the stubs with the `prod-stubs` classifier once you reach production -deployment, you can run tests in one case with development stubs and in another case with production stubs. - -The following example works for tests that use the development version of the stubs: - -==== -[source,java,indent=0] ----- -@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:8080"}) ----- -==== - -The following example works for tests that use the production version of stubs: - -==== -[source,java,indent=0] ----- -@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:prod-stubs:8080"}) ----- -==== - -You can also pass those values also in properties from your deployment pipeline. - -[[how-to-common-repo-with-contracts]] -== How Can I use a Common Repository with Contracts Instead of Storing Them with the Producer? - -Another way of storing contracts, rather than having them with the producer, is to keep -them in a common place. This situation can be related to security issues (where the -consumers cannot clone the producer's code). Also, if you keep contracts in a single place, -then you, as a producer, know how many consumers you have and which consumer you may break -with your local changes. - -[[how-to-repo-structure]] -=== Repo Structure - -Assume that we have a producer with coordinates of `com.example:server` and three -consumers: `client1`, `client2`, and `client3`. Then, in the repository with common -contracts, you could have the following setup (which you can check out -https://github.com/spring-cloud/spring-cloud-contract/tree/{github-tag}/samples/standalone/contracts[here]). -The following listing shows such a structure: - -==== -[source,bash,indent=0] ----- -├── com -│   └── example -│   └── server -│   ├── client1 -│   │   └── expectation.groovy -│   ├── client2 -│   │   └── expectation.groovy -│   ├── client3 -│   │   └── expectation.groovy -│   └── pom.xml -├── mvnw -├── mvnw.cmd -├── pom.xml -└── src - └── assembly - └── contracts.xml ----- -==== - -Under the slash-delimited `groupid/artifact id` folder (`com/example/server`), you have -expectations of the three consumers (`client1`, `client2`, and `client3`). Expectations are the standard Groovy DSL -contract files, as described throughout this documentation. This repository has to produce a JAR file that maps -one-to-one to the contents of the repository. - -The following example shows a `pom.xml` file inside the `server` folder: - -==== -[source,xml,indent=0] ----- -include::{introduction_url}/samples/standalone/contracts/com/example/server/pom.xml[indent=0] ----- -==== - -There are no dependencies other than the Spring Cloud Contract Maven Plugin. -Those `pom.xml` files are necessary for the consumer side to run `mvn clean install -DskipTests` to locally install -the stubs of the producer project. - -The `pom.xml` file in the root folder can look like the following: - -==== -[source,xml,indent=0] ----- -include::{introduction_url}/samples/standalone/contracts/pom.xml[indent=0] ----- -==== - -It uses the assembly plugin to build the JAR with all the contracts. The following example -shows such a setup: - -==== -[source,xml,indent=0] ----- -include::{introduction_url}/samples/standalone/contracts/src/assembly/contracts.xml[indent=0] ----- -==== - -[[how-to-workflow]] -=== Workflow - -The workflow assumes that Spring Cloud Contract is set up both on the consumer and on the -producer side. There is also the proper plugin setup in the common repository with -contracts. The CI jobs are set for a common repository to build an artifact of all -contracts and upload it to Nexus or Artifactory. The following image shows the UML for this -workflow: - -[plantuml, how-to-common-repo, png] ----- -"API Consumer"->"Common repo": create a folder \nfor producer [API Producer] -"API Consumer"->"Common repo": under [API Producer] create a folder \nfor consumer \n[API Consumer] -"API Consumer"->"Common repo": define contracts under \n[API Consumer] folder -"API Consumer"->"Common repo": install stubs of [API Producer]\nin local storage -"Common repo"->"Common Repo\nSCC Plugin": install stubs \nin local storage. \nDon't generate tests. -"Common Repo\nSCC Plugin"->"Local storage": install stubs -"Local storage"->"Common Repo\nSCC Plugin": stubs installed -"API Consumer"->"API Consumer": write a SCC Stub Runner \nbased contract test -"API Consumer"->"API Consumer\nSCC Stub Runner": fetch the stubs\n of [API Producer] \nfrom local storage -"API Consumer\nSCC Stub Runner"->"Local storage": test asks for [API Producer] stubs -"Local storage"->"API Consumer\nSCC Stub Runner": [API Producer] stubs found -"API Consumer\nSCC Stub Runner"->"API Consumer\nSCC Stub Runner": run in memory\n HTTP server stubs -"API Consumer\nSCC Stub Runner"->"API Consumer": HTTP server stubs running,\n ready for tests -"API Consumer"->"API Consumer\nSCC Stub Runner": send a request \nto the HTTP server stub -"API Consumer\nSCC Stub Runner"->"API Consumer": communication is correct. \nTests are passing -"API Consumer"->"Common repo": file pull request \nwith contracts -"API Producer"->"Common repo": take over \nthe pull request -"API Producer"->"Common repo": install the JAR \nwith all contracts\n in local storage -"Common repo"->"Local storage": install the JAR -"Local storage"->"Common repo": contracts JAR installed -"API Producer"->"Producer Build": run the build \nand fetch contracts from \nlocal storage -"Producer Build"->"Producer\nSCC Plugin": generate \ntests, stubs and stubs \nartifact (e.g. stubs-jar) -"Producer\nSCC Plugin"->"Local storage": fetch contract definitions for [API Prodcer] -"Local storage"->"Producer\nSCC Plugin": contracts fetched -"Producer\nSCC Plugin"->"Producer Build": tests and stubs created -"Producer Build"->"Nexus / Artifactory": upload contracts \nand stubs and the project arifact -"Producer Build"->"API Producer": Build successful -"API Producer"->"Common repo": merge the pull request -"Common repo"->"Nexus / Artifactory": upload the fresh JAR \nwith contract definitions -"API Producer"->"API Producer": start fetching contract definitions \nfrom Nexus / Artifactory ----- - -[[how-to-workflow-consumer]] -=== Consumer - -When the consumer wants to work on the contracts offline, instead of cloning the producer -code, the consumer team clones the common repository, goes to the required producer's -folder (for example, `com/example/server`) and runs `mvn clean install -DskipTests` to -locally install the stubs converted from the contracts. - -TIP: You need to have https://maven.apache.org/download.cgi[Maven installed locally]. - -[[how-to-workflow-producer]] -=== Producer - -As a producer, you can alter the Spring Cloud Contract Verifier to provide the URL and -the dependency of the JAR that contains the contracts, as follows: - -==== -[source,xml,indent=0] ----- -include::{introduction_url}/spring-cloud-contract-tools/spring-cloud-contract-maven-plugin/src/test/projects/basic-remote-contracts/pom-with-repo.xml[tags=remote_config,indent=0] ----- -==== - -With this setup, the JAR with a `groupid` of `com.example.standalone` and an `artifactid` of -`contracts` is downloaded from `https://link/to/your/nexus/or/artifactory/or/sth`. It is -then unpacked in a local temporary folder, and the contracts present in -`com/example/server` are picked as the ones used to generate the tests and the stubs. Due -to this convention, the producer team can know which consumer teams are broken when -some incompatible changes are made. - -The rest of the flow looks the same. - -[[how-to-define-messaging-contracts-per-topic]] -=== How Can I Define Messaging Contracts per Topic Rather than per Producer? - -To avoid messaging contracts duplication in the common repository, when a few producers write messages to one topic, -we could create a structure in which the REST contracts are placed in a folder per producer and messaging -contracts are placed in the folder per topic. - -[[how-to-define-messaging-contracts-per-topic-maven]] -==== For Maven Projects - -To make it possible to work on the producer side, we should specify an inclusion pattern for -filtering common repository jar files by messaging topics we are interested in. The -`includedFiles` property of the Maven Spring Cloud Contract plugin -lets us do so. Also, `contractsPath` need to be specified, since the default path would be -the common repository `groupid/artifactid`. The following example shows a Maven -plugin for Spring Cloud Contract: - -==== -[source,xml,indent=0] ----- - - org.springframework.cloud - spring-cloud-contract-maven-plugin - ${spring-cloud-contract.version} - - REMOTE - https://link/to/your/nexus/or/artifactory/or/sth - - com.example - common-repo-with-contracts - + - - / - - - .*messaging.* - com.example.services.MessagingBase - - - .*rest.* - com.example.services.TestBase - - - - **/${project.artifactId}/** - **/${first-topic}/** - **/${second-topic}/** - - - ----- -==== - -NOTE: Many of the values in the preceding Maven plugin can be changed. We included it for -illustration purposes rather than trying to provide a "`typical`" example. - -[[how-to-define-messaging-contracts-per-topic-gradle]] -==== For Gradle Projects - -To work with a Gradle project: - -. Add a custom configuration for the common repository dependency, as follows: -+ -==== -[source,groovy,indent=0] ----- -ext { - contractsGroupId = "com.example" - contractsArtifactId = "common-repo" - contractsVersion = "1.2.3" -} - -configurations { - contracts { - transitive = false - } -} ----- -==== - -. Add the common repository dependency to your classpath, as follows: -+ -==== -[source,groovy,indent=0] ----- -dependencies { - contracts "${contractsGroupId}:${contractsArtifactId}:${contractsVersion}" - testCompile "${contractsGroupId}:${contractsArtifactId}:${contractsVersion}" -} ----- -==== - -. Download the dependency to an appropriate folder, as follows: -+ -==== -[source,groovy,indent=0] ----- -task getContracts(type: Copy) { - from configurations.contracts - into new File(project.buildDir, "downloadedContracts") -} ----- -==== - -. Unzip the JAR, as follows: -+ -==== -[source,groovy,indent=0] ----- -task unzipContracts(type: Copy) { - def zipFile = new File(project.buildDir, "downloadedContracts/${contractsArtifactId}-${contractsVersion}.jar") - def outputDir = file("${buildDir}/unpackedContracts") - - from zipTree(zipFile) - into outputDir -} ----- -==== - -. Cleanup unused contracts, as follows: -+ -==== -[source,groovy,indent=0] ----- -task deleteUnwantedContracts(type: Delete) { - delete fileTree(dir: "${buildDir}/unpackedContracts", - include: "**/*", - excludes: [ - "**/${project.name}/**"", - "**/${first-topic}/**", - "**/${second-topic}/**"]) -} ----- -==== - -. Create task dependencies, as follows: -+ -==== -[source,groovy,indent=0] ----- -unzipContracts.dependsOn("getContracts") -deleteUnwantedContracts.dependsOn("unzipContracts") -build.dependsOn("deleteUnwantedContracts") ----- -==== - -. Configure the plugin by specifying the directory that contains the contracts, by setting -the `contractsDslDir` property, as follows: -+ -==== -[source,groovy,indent=0] ----- -contracts { - contractsDslDir = new File("${buildDir}/unpackedContracts") -} ----- -==== - -[[how-to-use-git-as-storage]] -== How Can I Use Git as the Storage for Contracts and Stubs? - -In the polyglot world, there are languages that do not use binary storage, as -Artifactory and Nexus do. Starting from Spring Cloud Contract version 2.0.0, we provide -mechanisms to store contracts and stubs in a SCM (Source Control Management) repository. Currently, the -only supported SCM is Git. - -The repository would have to have the following setup -(which you can checkout from https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/{samples_branch}/contracts_git/[here]): - -==== -[source,indent=0] ----- -. -└── META-INF - └── com.example - └── beer-api-producer-git - └── 0.0.1-SNAPSHOT - ├── contracts - │   └── beer-api-consumer - │   ├── messaging - │   │   ├── shouldSendAcceptedVerification.groovy - │   │   └── shouldSendRejectedVerification.groovy - │   └── rest - │   ├── shouldGrantABeerIfOldEnough.groovy - │   └── shouldRejectABeerIfTooYoung.groovy - └── mappings - └── beer-api-consumer - └── rest - ├── shouldGrantABeerIfOldEnough.json - └── shouldRejectABeerIfTooYoung.json ----- -==== - -Under the `META-INF` folder: - -* We group applications by `groupId` (such as `com.example`). -* Each application is represented by its `artifactId` (for example, `beer-api-producer-git`). -* Next, each application is organized by its version (such as `0.0.1-SNAPSHOT`). Starting -from Spring Cloud Contract version `2.1.0`, you can specify the versions as follows -(assuming that your versions follow semantic versioning): -** `+` or `latest`: To find the latest version of your stubs (assuming that the snapshots -are always the latest artifact for a given revision number). That means: -*** If you have `1.0.0.RELEASE`, `2.0.0.BUILD-SNAPSHOT`, and `2.0.0.RELEASE`, we assume -that the latest is `2.0.0.BUILD-SNAPSHOT`. -*** If you have `1.0.0.RELEASE` and `2.0.0.RELEASE`, we assume that the latest is `2.0.0.RELEASE`. -*** If you have a version called `latest` or `+`, we will pick that folder. -** `release`: To find the latest release version of your stubs. That means: -*** If you have `1.0.0.RELEASE`, `2.0.0.BUILD-SNAPSHOT`, and `2.0.0.RELEASE` we assume -that the latest is `2.0.0.RELEASE`. -*** If you have a version called `release`, we pick that folder. - -Finally, there are two folders: - -* `contracts`: The good practice is to store the contracts required by each -consumer in the folder with the consumer name (such as `beer-api-consumer`). That way, you -can use the `stubs-per-consumer` feature. Further directory structure is arbitrary. -* `mappings`: The Maven or Gradle Spring Cloud Contract plugins push -the stub server mappings in this folder. On the consumer side, Stub Runner scans this folder -to start stub servers with stub definitions. The folder structure is a copy -of the one created in the `contracts` subfolder. - -[[how-to-protocol-convention]] -=== Protocol Convention - -To control the type and location of the source of contracts (whether -binary storage or an SCM repository), you can use the protocol in the URL of -the repository. Spring Cloud Contract iterates over registered protocol resolvers -and tries to fetch the contracts (by using a plugin) or stubs (from Stub Runner). - -For the SCM functionality, currently, we support the Git repository. To use it, -in the property where the repository URL needs to be placed, you have to prefix -the connection URL with `git://`. The following listing shows some examples: - -==== -[source,indent=0] ----- -git://file:///foo/bar -git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git -git://git@github.com:spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git ----- -==== - -[[how-to-protocol-convention-producer]] -=== Producer - -For the producer, to use the SCM (Source Control Management) approach, we can reuse the -same mechanism we use for external contracts. We route Spring Cloud Contract -to use the SCM implementation from the URL that starts with -the `git://` protocol. - -IMPORTANT: You have to manually add the `pushStubsToScm` -goal in Maven or use (bind) the `pushStubsToScm` task in -Gradle. We do not push stubs to the `origin` of your git -repository. - -The following listing includes the relevant parts both Maven and Gradle build files: - -==== -[source,xml,indent=0,role="primary"] -.Maven ----- - - org.springframework.cloud - spring-cloud-contract-maven-plugin - ${spring-cloud-contract.version} - true - - - - - git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git - - - - ${project.groupId} - ${project.artifactId} - ${project.version} - - - - REMOTE - - - - package - - - pushStubsToScm - - - - ----- - -[source,groovy,indent=0,role="secondary"] -.Gradle ----- -contracts { - // We want to pick contracts from a Git repository - contractDependency { - stringNotation = "${project.group}:${project.name}:${project.version}" - } - /* - We reuse the contract dependency section to set up the path - to the folder that contains the contract definitions. In our case the - path will be /groupId/artifactId/version/contracts - */ - contractRepository { - repositoryUrl = "git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git" - } - // The mode can't be classpath - contractsMode = "REMOTE" - // Base class mappings etc. -} - -/* -In this scenario we want to publish stubs to SCM whenever -the `publish` task is invoked -*/ -publish.dependsOn("publishStubsToScm") ----- -==== - -You can also further customize the `publishStubsToScm` gradle task. In the following example, -the task is customized to pick contracts from a local git repository: - -==== -[source,groovy,indent=0] -.gradle ----- -publishStubsToScm { - // We want to modify the default set up of the plugin when publish stubs to scm is called - // We want to pick contracts from a Git repository - contractDependency { - stringNotation = "${project.group}:${project.name}:${project.version}" - } - /* - We reuse the contract dependency section to set up the path - to the folder that contains the contract definitions. In our case the - path will be /groupId/artifactId/version/contracts - */ - contractRepository { - repositoryUrl = "git://file://${new File(project.rootDir, "../target")}/contract_empty_git/" - } - // We set the contracts mode to `LOCAL` - contractsMode = "LOCAL" - } ----- -==== - -IMPORTANT:: Starting with the `2.3.0.RELEASE`, the `customize{}` closure previously used for the -`publishStubsToScm` customization is no longer available. The settings should be applied directly -within the `publishStubsToScm` closure, as in the preceding example. - -With such a setup: - -* A git project is cloned to a temporary directory -* The SCM stub downloader goes to the `META-INF/groupId/artifactId/version/contracts` folder -to find contracts. For example, for `com.example:foo:1.0.0`, the path would be -`META-INF/com.example/foo/1.0.0/contracts`. -* Tests are generated from the contracts. -* Stubs are created from the contracts. -* Once the tests pass, the stubs are committed in the cloned repository. -* Finally, a push is sent to that repo's `origin`. - -[[how-to-protocol-convention-producer-with-contracts-stored-locally]] -=== Producer with Contracts Stored Locally - -Another option to use the SCM as the destination for stubs and contracts is to store the -contracts locally, with the producer, and only push the contracts and the stubs to SCM. -The following listing shows the setup required to achieve this with Maven and Gradle: - -==== -[source,xml,indent=0,role="primary"] -.Maven ----- -include::{samples_url}/producer_with_empty_git/pom.xml[tags=plugin,indent=0] ----- - -[source,groovy,indent=0,role="secondary"] -.Gradle ----- -include::{samples_url}/producer_with_empty_git/build.gradle[tags=plugin,indent=0] ----- -==== - -With such a setup: - -* Contracts from the default `src/test/resources/contracts` directory are picked. -* Tests are generated from the contracts. -* Stubs are created from the contracts. -* Once the tests pass: -** The git project is cloned to a temporary directory. -** The stubs and contracts are committed in the cloned repository. -* Finally, a push is done to that repository's `origin`. - -[[how-to-protocol-convention-contracts-producer-stubs-external]] -=== Keeping Contracts with the Producer and Stubs in an External Repository - -You can also keep the contracts in the producer repository but keep the stubs in an external git repository. -This is most useful when you want to use the base consumer-producer collaboration flow but cannot -use an artifact repository to store the stubs. - -To do so, use the usual producer setup and then add the `pushStubsToScm` goal and set -`contractsRepositoryUrl` to the repository where you want to keep the stubs. - -[[how-to-protocol-convention-contracts-producer-stubs-external-consumer]] -=== Consumer - -On the consumer side, when passing the `repositoryRoot` parameter, -either from the `@AutoConfigureStubRunner` annotation, the -JUnit 4 rule, JUnit 5 extension, or properties, you can pass the URL of the -SCM repository, prefixed with the `git://` protocol. The following example shows how to do so: - -==== -[source,java,indent=0] ----- -@AutoConfigureStubRunner( - stubsMode="REMOTE", - repositoryRoot="git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git", - ids="com.example:bookstore:0.0.1.RELEASE" -) ----- -==== - -With such a setup: - -* The git project is cloned to a temporary directory. -* The SCM stub downloader goes to the `META-INF/groupId/artifactId/version/` folder -to find stub definitions and contracts. For example, for `com.example:foo:1.0.0`, the path would be -`META-INF/com.example/foo/1.0.0/`. -* Stub servers are started and fed with mappings. -* Messaging definitions are read and used in the messaging tests. - -[[how-to-debug]] -== How Can I Debug the Request/Response Being Sent by the Generated Tests Client? - -The generated tests all boil down to RestAssured in some form or fashion. RestAssured -relies on the https://hc.apache.org/httpcomponents-client-ga/[Apache HttpClient]. -HttpClient has a facility called -https://hc.apache.org/httpcomponents-client-ga/logging.html#Wire_Logging[wire logging], -which logs the entire request and response to HttpClient. Spring Boot has a logging -https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html[common application property] -for doing this sort of thing. To use it, add it to your application properties, as follows: - -==== -[source,properties,indent=0] ----- -logging.level.org.apache.http.wire=DEBUG ----- -==== - -[[how-to-debug-wiremock]] -== How Can I Debug the Mapping, Request, or Response Being Sent by WireMock? - -Starting from version `1.2.0`, we set WireMock logging to -`info` and set the WireMock notifier to being verbose. Now you can -exactly know what request was received by the WireMock server and which -matching response definition was picked. - -To turn off this feature, set WireMock logging to `ERROR`, as follows: - -==== -[source,properties,indent=0] ----- -logging.level.com.github.tomakehurst.wiremock=ERROR ----- -==== - -[[how-to-see-registered-stubs]] -== How Can I See What Got Registered in the HTTP Server Stub? - -You can use the `mappingsOutputFolder` property on `@AutoConfigureStubRunner`, `StubRunnerRule`, or -`StubRunnerExtension` to dump all mappings for each artifact ID. Also, the port at which the given stub server -was started is attached. - -[[how-to-reference-text-from-file]] -== How Can I Reference Text from File? - -In version 1.2.0, we added this ability. You can call a `file(...)` method in the -DSL and provide a path relative to where the contract lies. -If you use YAML, you can use the `bodyFromFile` property. - -[[how-to-generate-pact-from-scc]] -== How Can I Generate Pact, YAML, or X files from Spring Cloud Contract Contracts? - -Spring Cloud Contract comes with a `ToFileContractsTransformer` class that lets you dump -contracts as files for the given `ContractConverter`. It contains a `static void main` -method that lets you run the transformer as an executable. It takes the following -arguments: - -- argument 1 : `FQN`: Fully qualified name of the `ContractConverter` (for example, `PactContractConverter`). *REQUIRED*. -- argument 2 : `path`: Path where the dumped files should be stored. *OPTIONAL* -- defaults to `target/converted-contracts`. -- argument 3 : `path`: Path were the contracts should be searched for. *OPTIONAL* -- defaults to `src/test/resources/contracts`. - -After calling the transformer, the Spring Cloud Contract files are processed and, -depending on the provided FQN of the `ContractTransformer`, the contracts are transformed -to the required format and dumped to the provided folder. - -The following example shows how to configure Pact integration for both Maven and Gradle: - -==== -[source,xml,indent=0,role="primary"] -.Maven ----- - - org.codehaus.mojo - exec-maven-plugin - 1.6.0 - - - convert-dsl-to-pact - process-test-classes - - test - - org.springframework.cloud.contract.verifier.util.ToFileContractsTransformer - - - - org.springframework.cloud.contract.verifier.spec.pact.PactContractConverter - - ${project.basedir}/target/pacts - - ${project.basedir}/src/test/resources/contracts - - - - - java - - - - ----- - -[source,groovy,indent=0,role="secondary"] -.Gradle ----- -task convertContracts(type: JavaExec) { - main = "org.springframework.cloud.contract.verifier.util.ToFileContractsTransformer" - classpath = sourceSets.test.compileClasspath - args("org.springframework.cloud.contract.verifier.spec.pact.PactContractConverter", - "${project.rootDir}/build/pacts", "${project.rootDir}/src/test/resources/contracts") -} - -test.dependsOn("convertContracts") ----- -==== - -[[how-to-work-with-transitivie]] -== How Can I Work with Transitive Dependencies? - -The Spring Cloud Contract plugins add the tasks that create the stubs jar for you. One -problem that arises is that, when reusing the stubs, you can mistakenly import all of -that stub's dependencies. When building a Maven artifact, even though you have a couple -of different jars, all of them share one `pom.xml` file, as the following listing shows: - -==== -[source,bash,indent=0] ----- -├── producer-0.0.1.BUILD-20160903.075506-1-stubs.jar -├── producer-0.0.1.BUILD-20160903.075506-1-stubs.jar.sha1 -├── producer-0.0.1.BUILD-20160903.075655-2-stubs.jar -├── producer-0.0.1.BUILD-20160903.075655-2-stubs.jar.sha1 -├── producer-0.0.1.BUILD-SNAPSHOT.jar -├── producer-0.0.1.BUILD-SNAPSHOT.pom -├── producer-0.0.1.BUILD-SNAPSHOT-stubs.jar -├── ... -└── ... ----- -==== - -There are three possibilities of working with those dependencies so as not to have any -issues with transitive dependencies: - -* Mark all application dependencies as optional -* Create a separate `artifactid` for the stubs -* Exclude dependencies on the consumer side - -[[how-to-work-with-transitivie-optional]] -=== How Can I Mark All Application Dependencies as Optional? - -If, in the `producer` application, you mark all of your dependencies as optional, -when you include the `producer` stubs in another application (or when that -dependency gets downloaded by Stub Runner), then, since all of the dependencies are -optional, they do not get downloaded. - -[[how-to-work-with-transitivie-separate]] -=== How can I Create a Separate `artifactid` for the Stubs? - -If you create a separate `artifactid`, you can set it up in whatever way you wish. -For example, you might decide to have no dependencies at all. - -[[how-to-work-with-transitivie-exclude]] -=== How can I Exclude Dependencies on the Consumer Side? - -As a consumer, if you add the stub dependency to your classpath, you can explicitly exclude the unwanted dependencies. - -[[contract-dsl-rest-docs]] -== How Can I Generate Spring REST Docs Snippets from the Contracts? - -When you want to include the requests and responses of your API by using Spring REST Docs, -you only need to make some minor changes to your setup if you are using MockMvc and RestAssuredMockMvc. -To do so, include the following dependencies (if you have not already done so): - -==== -[source,xml,indent=0,subs="verbatim,attributes",role="primary"] -.maven ----- -include::{standalone_restdocs_path}/http-server/pom.xml[tags=dependencies,indent=0] ----- - -[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] -.gradle ----- -include::{standalone_restdocs_path}/http-server/build.gradle[tags=dependencies,indent=0] ----- -==== - -Next, you need to make some changes to your base class. The following examples use -`WebAppContext` and the standalone option with RestAssured: - -==== -[source,java,indent=0,subs="verbatim,attributes",role="primary"] -.WebAppContext ----- -include::{standalone_restdocs_path}/http-server/src/test/java/com/example/fraud/FraudBaseWithWebAppSetup.java[tags=base_class,indent=0] ----- - -[source,java,indent=0,subs="verbatim,attributes",role="secondary"] -.Standalone ----- -include::{standalone_restdocs_path}/http-server/src/test/java/com/example/fraud/FraudBaseWithStandaloneSetup.java[tags=base_class,indent=0] ----- -==== - -TIP: You need not specify the output directory for the generated snippets (since version 1.2.0.RELEASE of Spring REST Docs). - -[[how-to-use-stubs-from-a-location]] -== How Can I Use Stubs from a Location - -If you want to fetch contracts or stubs from a given location without cloning a repository or fetching a JAR, use the `stubs://` protocol when providing the repository root argument for Stub Runner or the Spring Cloud Contract plugin. You can read more about this in <> of the documentation. - -[[how-to-generate-stubs-at-runtime]] -== How Can I Generate Stubs at Runtime - -If you want to generate stubs at runtime for contracts, switch the `generateStubs` property in the `@AutoConfigureStubRunner` annotation, or call the `withGenerateStubs(true)` method on the JUnit Rule or Extension. You can read more about this in <> of the documentation. - -[[how-to-use-the-failonnostubs-feature]] -== How Can I Make The Build Pass if There Are No Contracts or Stubs - -If you want Stub Runner not to fail if no stubs were found, switch the `generateStubs` property in the `@AutoConfigureStubRunner` annotation or call the `withFailOnNoStubs(false)` method on the JUnit Rule or Extension. You can read more about this in <> of the documentation. - -If you want the plugins not to fail the build when no contracts were found, you can set the `failOnNoStubs` flag in Maven or call the `contractRepository { failOnNoStubs(false) }` closure in Gradle. - -[[how-to-mark-contract-in-progress]] -== How Can I Mark that a Contract Is in Progress - -If a contract is in progress, it means that the, on the producer side, tests are not generated, but the stub is generated. You can read more about this in <> of the documentation. - -In a CI build, before going to production, you would like to ensure that no in-progress contracts are on the classpath, because they may lead to false positives. For this reason, by default, in the Spring Cloud Contract plugin, we set the value of `failOnInProgress` to `true`. If you want to allow such contracts when tests are to be generated, set the flag to `false`. diff --git a/docs/modules/ROOT/pages/howto/contract-dsl-rest-docs.adoc b/docs/modules/ROOT/pages/howto/contract-dsl-rest-docs.adoc new file mode 100644 index 0000000000..8726df5a42 --- /dev/null +++ b/docs/modules/ROOT/pages/howto/contract-dsl-rest-docs.adoc @@ -0,0 +1,40 @@ +[[contract-dsl-rest-docs]] += How Can I Generate Spring REST Docs Snippets from the Contracts? + +When you want to include the requests and responses of your API by using Spring REST Docs, +you only need to make some minor changes to your setup if you are using MockMvc and RestAssuredMockMvc. +To do so, include the following dependencies (if you have not already done so): + +==== +[source,xml,indent=0,subs="verbatim,attributes",role="primary"] +.maven +---- +include:../:{standalone_restdocs_path}/http-server/pom.xml[tags=dependencies,indent=0] +---- + +[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"] +.gradle +---- +include:../:{standalone_restdocs_path}/http-server/build.gradle[tags=dependencies,indent=0] +---- +==== + +Next, you need to make some changes to your base class. The following examples use +`WebAppContext` and the standalone option with RestAssured: + +==== +[source,java,indent=0,subs="verbatim,attributes",role="primary"] +.WebAppContext +---- +include:../:{standalone_restdocs_path}/http-server/src/test/java/com/example/fraud/FraudBaseWithWebAppSetup.java[tags=base_class,indent=0] +---- + +[source,java,indent=0,subs="verbatim,attributes",role="secondary"] +.Standalone +---- +include:../:{standalone_restdocs_path}/http-server/src/test/java/com/example/fraud/FraudBaseWithStandaloneSetup.java[tags=base_class,indent=0] +---- +==== + +TIP: You need not specify the output directory for the generated snippets (since version 1.2.0.RELEASE of Spring REST Docs). + diff --git a/docs/modules/ROOT/pages/howto/how-to-common-repo-with-contracts.adoc b/docs/modules/ROOT/pages/howto/how-to-common-repo-with-contracts.adoc new file mode 100644 index 0000000000..343c325037 --- /dev/null +++ b/docs/modules/ROOT/pages/howto/how-to-common-repo-with-contracts.adoc @@ -0,0 +1,310 @@ +[[how-to-common-repo-with-contracts]] += How Can I use a Common Repository with Contracts Instead of Storing Them with the Producer? + +Another way of storing contracts, rather than having them with the producer, is to keep +them in a common place. This situation can be related to security issues (where the +consumers cannot clone the producer's code). Also, if you keep contracts in a single place, +then you, as a producer, know how many consumers you have and which consumer you may break +with your local changes. + +[[how-to-repo-structure]] +== Repo Structure + +Assume that we have a producer with coordinates of `com.example:server` and three +consumers: `client1`, `client2`, and `client3`. Then, in the repository with common +contracts, you could have the following setup (which you can check out +https://github.com/spring-cloud/spring-cloud-contract/tree/{github-tag}/samples/standalone/contracts[here]). +The following listing shows such a structure: + +==== +[source,bash,indent=0] +---- +├── com +│   └── example +│   └── server +│   ├── client1 +│   │   └── expectation.groovy +│   ├── client2 +│   │   └── expectation.groovy +│   ├── client3 +│   │   └── expectation.groovy +│   └── pom.xml +├── mvnw +├── mvnw.cmd +├── pom.xml +└── src + └── assembly + └── contracts.xml +---- +==== + +Under the slash-delimited `groupid/artifact id` folder (`com/example/server`), you have +expectations of the three consumers (`client1`, `client2`, and `client3`). Expectations are the standard Groovy DSL +contract files, as described throughout this documentation. This repository has to produce a JAR file that maps +one-to-one to the contents of the repository. + +The following example shows a `pom.xml` file inside the `server` folder: + +==== +[source,xml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/contracts/com/example/server/pom.xml[indent=0] +---- +==== + +There are no dependencies other than the Spring Cloud Contract Maven Plugin. +Those `pom.xml` files are necessary for the consumer side to run `mvn clean install -DskipTests` to locally install +the stubs of the producer project. + +The `pom.xml` file in the root folder can look like the following: + +==== +[source,xml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/contracts/pom.xml[indent=0] +---- +==== + +It uses the assembly plugin to build the JAR with all the contracts. The following example +shows such a setup: + +==== +[source,xml,indent=0] +---- +include:../:{introduction_url}/samples/standalone/contracts/src/assembly/contracts.xml[indent=0] +---- +==== + +[[how-to-workflow]] +== Workflow + +The workflow assumes that Spring Cloud Contract is set up both on the consumer and on the +producer side. There is also the proper plugin setup in the common repository with +contracts. The CI jobs are set for a common repository to build an artifact of all +contracts and upload it to Nexus or Artifactory. The following image shows the UML for this +workflow: + +[plantuml, how-to-common-repo, png] +---- +"API Consumer"->"Common repo": create a folder \nfor producer [API Producer] +"API Consumer"->"Common repo": under [API Producer] create a folder \nfor consumer \n[API Consumer] +"API Consumer"->"Common repo": define contracts under \n[API Consumer] folder +"API Consumer"->"Common repo": install stubs of [API Producer]\nin local storage +"Common repo"->"Common Repo\nSCC Plugin": install stubs \nin local storage. \nDon't generate tests. +"Common Repo\nSCC Plugin"->"Local storage": install stubs +"Local storage"->"Common Repo\nSCC Plugin": stubs installed +"API Consumer"->"API Consumer": write a SCC Stub Runner \nbased contract test +"API Consumer"->"API Consumer\nSCC Stub Runner": fetch the stubs\n of [API Producer] \nfrom local storage +"API Consumer\nSCC Stub Runner"->"Local storage": test asks for [API Producer] stubs +"Local storage"->"API Consumer\nSCC Stub Runner": [API Producer] stubs found +"API Consumer\nSCC Stub Runner"->"API Consumer\nSCC Stub Runner": run in memory\n HTTP server stubs +"API Consumer\nSCC Stub Runner"->"API Consumer": HTTP server stubs running,\n ready for tests +"API Consumer"->"API Consumer\nSCC Stub Runner": send a request \nto the HTTP server stub +"API Consumer\nSCC Stub Runner"->"API Consumer": communication is correct. \nTests are passing +"API Consumer"->"Common repo": file pull request \nwith contracts +"API Producer"->"Common repo": take over \nthe pull request +"API Producer"->"Common repo": install the JAR \nwith all contracts\n in local storage +"Common repo"->"Local storage": install the JAR +"Local storage"->"Common repo": contracts JAR installed +"API Producer"->"Producer Build": run the build \nand fetch contracts from \nlocal storage +"Producer Build"->"Producer\nSCC Plugin": generate \ntests, stubs and stubs \nartifact (e.g. stubs-jar) +"Producer\nSCC Plugin"->"Local storage": fetch contract definitions for [API Prodcer] +"Local storage"->"Producer\nSCC Plugin": contracts fetched +"Producer\nSCC Plugin"->"Producer Build": tests and stubs created +"Producer Build"->"Nexus / Artifactory": upload contracts \nand stubs and the project arifact +"Producer Build"->"API Producer": Build successful +"API Producer"->"Common repo": merge the pull request +"Common repo"->"Nexus / Artifactory": upload the fresh JAR \nwith contract definitions +"API Producer"->"API Producer": start fetching contract definitions \nfrom Nexus / Artifactory +---- + +[[how-to-workflow-consumer]] +== Consumer + +When the consumer wants to work on the contracts offline, instead of cloning the producer +code, the consumer team clones the common repository, goes to the required producer's +folder (for example, `com/example/server`) and runs `mvn clean install -DskipTests` to +locally install the stubs converted from the contracts. + +TIP: You need to have https://maven.apache.org/download.cgi[Maven installed locally]. + +[[how-to-workflow-producer]] +== Producer + +As a producer, you can alter the Spring Cloud Contract Verifier to provide the URL and +the dependency of the JAR that contains the contracts, as follows: + +==== +[source,xml,indent=0] +---- +include:../:{introduction_url}/spring-cloud-contract-tools/spring-cloud-contract-maven-plugin/src/test/projects/basic-remote-contracts/pom-with-repo.xml[tags=remote_config,indent=0] +---- +==== + +With this setup, the JAR with a `groupid` of `com.example.standalone` and an `artifactid` of +`contracts` is downloaded from `https://link/to/your/nexus/or/artifactory/or/sth`. It is +then unpacked in a local temporary folder, and the contracts present in +`com/example/server` are picked as the ones used to generate the tests and the stubs. Due +to this convention, the producer team can know which consumer teams are broken when +some incompatible changes are made. + +The rest of the flow looks the same. + +[[how-to-define-messaging-contracts-per-topic]] +== How Can I Define Messaging Contracts per Topic Rather than per Producer? + +To avoid messaging contracts duplication in the common repository, when a few producers write messages to one topic, +we could create a structure in which the REST contracts are placed in a folder per producer and messaging +contracts are placed in the folder per topic. + +[[how-to-define-messaging-contracts-per-topic-maven]] +=== For Maven Projects + +To make it possible to work on the producer side, we should specify an inclusion pattern for +filtering common repository jar files by messaging topics we are interested in. The +`includedFiles` property of the Maven Spring Cloud Contract plugin +lets us do so. Also, `contractsPath` need to be specified, since the default path would be +the common repository `groupid/artifactid`. The following example shows a Maven +plugin for Spring Cloud Contract: + +==== +[source,xml,indent=0] +---- + + org.springframework.cloud + spring-cloud-contract-maven-plugin + ${spring-cloud-contract.version} + + REMOTE + https://link/to/your/nexus/or/artifactory/or/sth + + com.example + common-repo-with-contracts + + + + / + + + .*messaging.* + com.example.services.MessagingBase + + + .*rest.* + com.example.services.TestBase + + + + **/${project.artifactId}/** + **/${first-topic}/** + **/${second-topic}/** + + + +---- +==== + +NOTE: Many of the values in the preceding Maven plugin can be changed. We included it for +illustration purposes rather than trying to provide a "`typical`" example. + +[[how-to-define-messaging-contracts-per-topic-gradle]] +=== For Gradle Projects + +To work with a Gradle project: + +. Add a custom configuration for the common repository dependency, as follows: ++ +==== +[source,groovy,indent=0] +---- +ext { + contractsGroupId = "com.example" + contractsArtifactId = "common-repo" + contractsVersion = "1.2.3" +} + +configurations { + contracts { + transitive = false + } +} +---- +==== + +. Add the common repository dependency to your classpath, as follows: ++ +==== +[source,groovy,indent=0] +---- +dependencies { + contracts "${contractsGroupId}:${contractsArtifactId}:${contractsVersion}" + testCompile "${contractsGroupId}:${contractsArtifactId}:${contractsVersion}" +} +---- +==== + +. Download the dependency to an appropriate folder, as follows: ++ +==== +[source,groovy,indent=0] +---- +task getContracts(type: Copy) { + from configurations.contracts + into new File(project.buildDir, "downloadedContracts") +} +---- +==== + +. Unzip the JAR, as follows: ++ +==== +[source,groovy,indent=0] +---- +task unzipContracts(type: Copy) { + def zipFile = new File(project.buildDir, "downloadedContracts/${contractsArtifactId}-${contractsVersion}.jar") + def outputDir = file("${buildDir}/unpackedContracts") + + from zipTree(zipFile) + into outputDir +} +---- +==== + +. Cleanup unused contracts, as follows: ++ +==== +[source,groovy,indent=0] +---- +task deleteUnwantedContracts(type: Delete) { + delete fileTree(dir: "${buildDir}/unpackedContracts", + include: "**/*", + excludes: [ + "**/${project.name}/**"", + "**/${first-topic}/**", + "**/${second-topic}/**"]) +} +---- +==== + +. Create task dependencies, as follows: ++ +==== +[source,groovy,indent=0] +---- +unzipContracts.dependsOn("getContracts") +deleteUnwantedContracts.dependsOn("unzipContracts") +build.dependsOn("deleteUnwantedContracts") +---- +==== + +. Configure the plugin by specifying the directory that contains the contracts, by setting +the `contractsDslDir` property, as follows: ++ +==== +[source,groovy,indent=0] +---- +contracts { + contractsDslDir = new File("${buildDir}/unpackedContracts") +} +---- +==== + diff --git a/docs/modules/ROOT/pages/howto/how-to-debug-wiremock.adoc b/docs/modules/ROOT/pages/howto/how-to-debug-wiremock.adoc new file mode 100644 index 0000000000..f44ef69450 --- /dev/null +++ b/docs/modules/ROOT/pages/howto/how-to-debug-wiremock.adoc @@ -0,0 +1,17 @@ +[[how-to-debug-wiremock]] += How Can I Debug the Mapping, Request, or Response Being Sent by WireMock? + +Starting from version `1.2.0`, we set WireMock logging to +`info` and set the WireMock notifier to being verbose. Now you can +exactly know what request was received by the WireMock server and which +matching response definition was picked. + +To turn off this feature, set WireMock logging to `ERROR`, as follows: + +==== +[source,properties,indent=0] +---- +logging.level.com.github.tomakehurst.wiremock=ERROR +---- +==== + diff --git a/docs/modules/ROOT/pages/howto/how-to-debug.adoc b/docs/modules/ROOT/pages/howto/how-to-debug.adoc new file mode 100644 index 0000000000..d2902a8bcb --- /dev/null +++ b/docs/modules/ROOT/pages/howto/how-to-debug.adoc @@ -0,0 +1,18 @@ +[[how-to-debug]] += How Can I Debug the Request/Response Being Sent by the Generated Tests Client? + +The generated tests all boil down to RestAssured in some form or fashion. RestAssured +relies on the https://hc.apache.org/httpcomponents-client-ga/[Apache HttpClient]. +HttpClient has a facility called +https://hc.apache.org/httpcomponents-client-ga/logging.html#Wire_Logging[wire logging], +which logs the entire request and response to HttpClient. Spring Boot has a logging +https://docs.spring.io/spring-boot/docs/current/reference/html/common-application-properties.html[common application property] +for doing this sort of thing. To use it, add it to your application properties, as follows: + +==== +[source,properties,indent=0] +---- +logging.level.org.apache.http.wire=DEBUG +---- +==== + diff --git a/docs/modules/ROOT/pages/howto/how-to-do-stubs-versioning.adoc b/docs/modules/ROOT/pages/howto/how-to-do-stubs-versioning.adoc new file mode 100644 index 0000000000..e17469209b --- /dev/null +++ b/docs/modules/ROOT/pages/howto/how-to-do-stubs-versioning.adoc @@ -0,0 +1,98 @@ +[[how-to-do-stubs-versioning]] += How to Do Stubs versioning? + +This section covers versioning of the stubs, which you can handle in a number of different ways: + +* <> +* <> +* <> + +[[how-to-api-versioning]] +== API Versioning + +What does versioning really mean? If you refer to the API version, there are +different approaches: + +- Use hypermedia links and do not version your API by any means +- Pass the version through headers and URLs + +We do not try to answer the question of which approach is better. You should pick whatever +suits your needs and lets you generate business value. + +Assume that you do version your API. In that case, you should provide as many contracts with as many versions as you support. +You can create a subfolder for every version or append it to the contract name -- whatever suits you best. + +[[how-to-jar-versioning]] +== JAR versioning + +If, by versioning, you mean the version of the JAR that contains the stubs, then there are essentially two main approaches. + +Assume that you do continuous delivery and deployment, which means that you generate a new version of +the jar each time you go through the pipeline and that the jar can go to production at any time. For example, your jar version +looks like the following (because it got built on the 20.10.2016 at 20:15:21) : + +==== +[source,groovy,indent=0] +---- +1.0.0.20161020-201521-RELEASE +---- +==== + +In that case, your generated stub jar should look like the following: + +==== +[source,groovy,indent=0] +---- +1.0.0.20161020-201521-RELEASE-stubs.jar +---- +==== + +In this case, you should, inside your `application.yml` or `@AutoConfigureStubRunner` when +referencing stubs, provide the latest version of the stubs. You can do that by passing the +`+` sign. the following example shows how to do so: + +==== +[source,java,indent=0] +---- +@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:8080"}) +---- +==== + +If the versioning, however, is fixed (for example, `1.0.4.RELEASE` or `2.1.1`), you have to set the concrete value of the jar +version. The following example shows how to do so for version 2.1.1: + +==== +[source,java,indent=0] +---- +@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:2.1.1:stubs:8080"}) +---- +==== + +[[how-to-dev-or-prod-stubs]] +== Development or Production Stubs + +You can manipulate the classifier to run the tests against the current development version +of the stubs of other services or the ones that were deployed to production. If you alter +your build to deploy the stubs with the `prod-stubs` classifier once you reach production +deployment, you can run tests in one case with development stubs and in another case with production stubs. + +The following example works for tests that use the development version of the stubs: + +==== +[source,java,indent=0] +---- +@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:8080"}) +---- +==== + +The following example works for tests that use the production version of stubs: + +==== +[source,java,indent=0] +---- +@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:prod-stubs:8080"}) +---- +==== + +You can also pass those values also in properties from your deployment pipeline. + diff --git a/docs/modules/ROOT/pages/howto/how-to-generate-pact-from-scc.adoc b/docs/modules/ROOT/pages/howto/how-to-generate-pact-from-scc.adoc new file mode 100644 index 0000000000..638560df08 --- /dev/null +++ b/docs/modules/ROOT/pages/howto/how-to-generate-pact-from-scc.adoc @@ -0,0 +1,67 @@ +[[how-to-generate-pact-from-scc]] += How Can I Generate Pact, YAML, or X files from Spring Cloud Contract Contracts? + +Spring Cloud Contract comes with a `ToFileContractsTransformer` class that lets you dump +contracts as files for the given `ContractConverter`. It contains a `static void main` +method that lets you run the transformer as an executable. It takes the following +arguments: + +- argument 1 : `FQN`: Fully qualified name of the `ContractConverter` (for example, `PactContractConverter`). *REQUIRED*. +- argument 2 : `path`: Path where the dumped files should be stored. *OPTIONAL* -- defaults to `target/converted-contracts`. +- argument 3 : `path`: Path were the contracts should be searched for. *OPTIONAL* -- defaults to `src/test/resources/contracts`. + +After calling the transformer, the Spring Cloud Contract files are processed and, +depending on the provided FQN of the `ContractTransformer`, the contracts are transformed +to the required format and dumped to the provided folder. + +The following example shows how to configure Pact integration for both Maven and Gradle: + +==== +[source,xml,indent=0,role="primary"] +.Maven +---- + + org.codehaus.mojo + exec-maven-plugin + 1.6.0 + + + convert-dsl-to-pact + process-test-classes + + test + + org.springframework.cloud.contract.verifier.util.ToFileContractsTransformer + + + + org.springframework.cloud.contract.verifier.spec.pact.PactContractConverter + + ${project.basedir}/target/pacts + + ${project.basedir}/src/test/resources/contracts + + + + + java + + + + +---- + +[source,groovy,indent=0,role="secondary"] +.Gradle +---- +task convertContracts(type: JavaExec) { + main = "org.springframework.cloud.contract.verifier.util.ToFileContractsTransformer" + classpath = sourceSets.test.compileClasspath + args("org.springframework.cloud.contract.verifier.spec.pact.PactContractConverter", + "${project.rootDir}/build/pacts", "${project.rootDir}/src/test/resources/contracts") +} + +test.dependsOn("convertContracts") +---- +==== + diff --git a/docs/modules/ROOT/pages/howto/how-to-generate-stubs-at-runtime.adoc b/docs/modules/ROOT/pages/howto/how-to-generate-stubs-at-runtime.adoc new file mode 100644 index 0000000000..f41ec2786c --- /dev/null +++ b/docs/modules/ROOT/pages/howto/how-to-generate-stubs-at-runtime.adoc @@ -0,0 +1,5 @@ +[[how-to-generate-stubs-at-runtime]] += How Can I Generate Stubs at Runtime + +If you want to generate stubs at runtime for contracts, switch the `generateStubs` property in the `@AutoConfigureStubRunner` annotation, or call the `withGenerateStubs(true)` method on the JUnit Rule or Extension. You can read more about this in <> of the documentation. + diff --git a/docs/modules/ROOT/pages/howto/how-to-mark-contract-in-progress.adoc b/docs/modules/ROOT/pages/howto/how-to-mark-contract-in-progress.adoc new file mode 100644 index 0000000000..9a4935f227 --- /dev/null +++ b/docs/modules/ROOT/pages/howto/how-to-mark-contract-in-progress.adoc @@ -0,0 +1,6 @@ +[[how-to-mark-contract-in-progress]] += How Can I Mark that a Contract Is in Progress + +If a contract is in progress, it means that the, on the producer side, tests are not generated, but the stub is generated. You can read more about this in <> of the documentation. + +In a CI build, before going to production, you would like to ensure that no in-progress contracts are on the classpath, because they may lead to false positives. For this reason, by default, in the Spring Cloud Contract plugin, we set the value of `failOnInProgress` to `true`. If you want to allow such contracts when tests are to be generated, set the flag to `false`. diff --git a/docs/modules/ROOT/pages/howto/how-to-not-write-contracts-in-groovy.adoc b/docs/modules/ROOT/pages/howto/how-to-not-write-contracts-in-groovy.adoc new file mode 100644 index 0000000000..ad09d0281c --- /dev/null +++ b/docs/modules/ROOT/pages/howto/how-to-not-write-contracts-in-groovy.adoc @@ -0,0 +1,7 @@ +[[how-to-not-write-contracts-in-groovy]] += How Can I Write Contracts in a Language Other than Groovy? + +You can write a contract in YAML. See <> for more information. + +We are working on allowing more ways of describing the contracts. You can check the {github-issues}[github-issues] for more information. + diff --git a/docs/modules/ROOT/pages/howto/how-to-provide-dynamic-values.adoc b/docs/modules/ROOT/pages/howto/how-to-provide-dynamic-values.adoc new file mode 100644 index 0000000000..e7cf3ea99e --- /dev/null +++ b/docs/modules/ROOT/pages/howto/how-to-provide-dynamic-values.adoc @@ -0,0 +1,106 @@ +[[how-to-provide-dynamic-values]] += How Can I Provide Dynamic Values to a Contract? + +One of the biggest challenges related to stubs is their reusability. Only if they can be widely used can they serve their purpose. +The hard-coded values (such as dates and IDs) of request and response elements generally make that difficult. +Consider the following JSON request: + +==== +[source,json,indent=0] +---- +{ + "time" : "2016-10-10 20:10:15", + "id" : "9febab1c-6f36-4a0b-88d6-3b6a6d81cd4a", + "body" : "foo" +} +---- +==== + +Now consider the following JSON response: + +==== +[source,json,indent=0] +---- +{ + "time" : "2016-10-10 21:10:15", + "id" : "c4231e1f-3ca9-48d3-b7e7-567d55f0d051", + "body" : "bar" +} +---- +==== + +Imagine the pain required to set the proper value of the `time` field (assume that this content is generated by the +database) by changing the clock in the system or by providing stub implementations of data providers. The same is related +to the `id` field. You could create a stubbed implementation of UUID generator, but doing so makes little sense. + +So, as a consumer, you want to send a request that matches any form of a time or any UUID. That way, your system +works as usual, generating data without you having to stub out anything. Assume that, in case of the aforementioned +JSON, the most important part is the `body` field. You can focus on that and provide matching for other fields. In other words, +you would like the stub to work as follows: + +==== +[source,json,indent=0] +---- +{ + "time" : "SOMETHING THAT MATCHES TIME", + "id" : "SOMETHING THAT MATCHES UUID", + "body" : "foo" +} +---- +==== + +As far as the response goes, as a consumer, you need a concrete value on which you can operate. +Consequently, the following JSON is valid: + +==== +[source,json,indent=0] +---- +{ + "time" : "2016-10-10 21:10:15", + "id" : "c4231e1f-3ca9-48d3-b7e7-567d55f0d051", + "body" : "bar" +} +---- +==== + +In the previous sections, we generated tests from contracts. So, from the producer's side, the situation looks +much different. We parse the provided contract, and, in the test, we want to send a real request to your endpoints. +So, for the case of a producer for the request, we cannot have any sort of matching. We need concrete values on which the +producer's backend can work. Consequently, the following JSON would be valid: + +==== +[source,json,indent=0] +---- +{ + "time" : "2016-10-10 20:10:15", + "id" : "9febab1c-6f36-4a0b-88d6-3b6a6d81cd4a", + "body" : "foo" +} +---- +==== + +On the other hand, from the point of view of the validity of the contract, the response does not necessarily have to +contain concrete values for `time` or `id`. Suppose you generate those on the producer side. Again, you +have to do a lot of stubbing to ensure that you always return the same values. That is why, from the producer's side, +you might want the following response: + +==== +[source,json,indent=0] +---- +{ + "time" : "SOMETHING THAT MATCHES TIME", + "id" : "SOMETHING THAT MATCHES UUID", + "body" : "bar" +} +---- +==== + +How can you then provide a matcher for the consumer and a concrete value for the producer (and the opposite at some other time)? +Spring Cloud Contract lets you provide a dynamic value. That means that it can differ for both +sides of the communication. + +You can read more about this in the <> section. + +IMPORTANT: Read the https://groovy-lang.org/json.html[Groovy docs related to JSON] to understand how to +properly structure the request and response bodies. + diff --git a/docs/modules/ROOT/pages/howto/how-to-reference-text-from-file.adoc b/docs/modules/ROOT/pages/howto/how-to-reference-text-from-file.adoc new file mode 100644 index 0000000000..a08d567027 --- /dev/null +++ b/docs/modules/ROOT/pages/howto/how-to-reference-text-from-file.adoc @@ -0,0 +1,7 @@ +[[how-to-reference-text-from-file]] += How Can I Reference Text from File? + +In version 1.2.0, we added this ability. You can call a `file(...)` method in the +DSL and provide a path relative to where the contract lies. +If you use YAML, you can use the `bodyFromFile` property. + diff --git a/docs/modules/ROOT/pages/howto/how-to-see-registered-stubs.adoc b/docs/modules/ROOT/pages/howto/how-to-see-registered-stubs.adoc new file mode 100644 index 0000000000..0a3fb04f7f --- /dev/null +++ b/docs/modules/ROOT/pages/howto/how-to-see-registered-stubs.adoc @@ -0,0 +1,7 @@ +[[how-to-see-registered-stubs]] += How Can I See What Got Registered in the HTTP Server Stub? + +You can use the `mappingsOutputFolder` property on `@AutoConfigureStubRunner`, `StubRunnerRule`, or +`StubRunnerExtension` to dump all mappings for each artifact ID. Also, the port at which the given stub server +was started is attached. + diff --git a/docs/modules/ROOT/pages/howto/how-to-use-git-as-storage.adoc b/docs/modules/ROOT/pages/howto/how-to-use-git-as-storage.adoc new file mode 100644 index 0000000000..0990ca7342 --- /dev/null +++ b/docs/modules/ROOT/pages/howto/how-to-use-git-as-storage.adoc @@ -0,0 +1,279 @@ +[[how-to-use-git-as-storage]] += How Can I Use Git as the Storage for Contracts and Stubs? + +In the polyglot world, there are languages that do not use binary storage, as +Artifactory and Nexus do. Starting from Spring Cloud Contract version 2.0.0, we provide +mechanisms to store contracts and stubs in a SCM (Source Control Management) repository. Currently, the +only supported SCM is Git. + +The repository would have to have the following setup +(which you can checkout from https://github.com/spring-cloud-samples/spring-cloud-contract-samples/tree/{samples_branch}/contracts_git/[here]): + +==== +[source,indent=0] +---- +. +└── META-INF + └── com.example + └── beer-api-producer-git + └── 0.0.1-SNAPSHOT + ├── contracts + │   └── beer-api-consumer + │   ├── messaging + │   │   ├── shouldSendAcceptedVerification.groovy + │   │   └── shouldSendRejectedVerification.groovy + │   └── rest + │   ├── shouldGrantABeerIfOldEnough.groovy + │   └── shouldRejectABeerIfTooYoung.groovy + └── mappings + └── beer-api-consumer + └── rest + ├── shouldGrantABeerIfOldEnough.json + └── shouldRejectABeerIfTooYoung.json +---- +==== + +Under the `META-INF` folder: + +* We group applications by `groupId` (such as `com.example`). +* Each application is represented by its `artifactId` (for example, `beer-api-producer-git`). +* Next, each application is organized by its version (such as `0.0.1-SNAPSHOT`). Starting +from Spring Cloud Contract version `2.1.0`, you can specify the versions as follows +(assuming that your versions follow semantic versioning): +** `+` or `latest`: To find the latest version of your stubs (assuming that the snapshots +are always the latest artifact for a given revision number). That means: +*** If you have `1.0.0.RELEASE`, `2.0.0.BUILD-SNAPSHOT`, and `2.0.0.RELEASE`, we assume +that the latest is `2.0.0.BUILD-SNAPSHOT`. +*** If you have `1.0.0.RELEASE` and `2.0.0.RELEASE`, we assume that the latest is `2.0.0.RELEASE`. +*** If you have a version called `latest` or `+`, we will pick that folder. +** `release`: To find the latest release version of your stubs. That means: +*** If you have `1.0.0.RELEASE`, `2.0.0.BUILD-SNAPSHOT`, and `2.0.0.RELEASE` we assume +that the latest is `2.0.0.RELEASE`. +*** If you have a version called `release`, we pick that folder. + +Finally, there are two folders: + +* `contracts`: The good practice is to store the contracts required by each +consumer in the folder with the consumer name (such as `beer-api-consumer`). That way, you +can use the `stubs-per-consumer` feature. Further directory structure is arbitrary. +* `mappings`: The Maven or Gradle Spring Cloud Contract plugins push +the stub server mappings in this folder. On the consumer side, Stub Runner scans this folder +to start stub servers with stub definitions. The folder structure is a copy +of the one created in the `contracts` subfolder. + +[[how-to-protocol-convention]] +== Protocol Convention + +To control the type and location of the source of contracts (whether +binary storage or an SCM repository), you can use the protocol in the URL of +the repository. Spring Cloud Contract iterates over registered protocol resolvers +and tries to fetch the contracts (by using a plugin) or stubs (from Stub Runner). + +For the SCM functionality, currently, we support the Git repository. To use it, +in the property where the repository URL needs to be placed, you have to prefix +the connection URL with `git://`. The following listing shows some examples: + +==== +[source,indent=0] +---- +git://file:///foo/bar +git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git +git://git@github.com:spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git +---- +==== + +[[how-to-protocol-convention-producer]] +== Producer + +For the producer, to use the SCM (Source Control Management) approach, we can reuse the +same mechanism we use for external contracts. We route Spring Cloud Contract +to use the SCM implementation from the URL that starts with +the `git://` protocol. + +IMPORTANT: You have to manually add the `pushStubsToScm` +goal in Maven or use (bind) the `pushStubsToScm` task in +Gradle. We do not push stubs to the `origin` of your git +repository. + +The following listing includes the relevant parts both Maven and Gradle build files: + +==== +[source,xml,indent=0,role="primary"] +.Maven +---- + + org.springframework.cloud + spring-cloud-contract-maven-plugin + ${spring-cloud-contract.version} + true + + + + + git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git + + + + ${project.groupId} + ${project.artifactId} + ${project.version} + + + + REMOTE + + + + package + + + pushStubsToScm + + + + +---- + +[source,groovy,indent=0,role="secondary"] +.Gradle +---- +contracts { + // We want to pick contracts from a Git repository + contractDependency { + stringNotation = "${project.group}:${project.name}:${project.version}" + } + /* + We reuse the contract dependency section to set up the path + to the folder that contains the contract definitions. In our case the + path will be /groupId/artifactId/version/contracts + */ + contractRepository { + repositoryUrl = "git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git" + } + // The mode can't be classpath + contractsMode = "REMOTE" + // Base class mappings etc. +} + +/* +In this scenario we want to publish stubs to SCM whenever +the `publish` task is invoked +*/ +publish.dependsOn("publishStubsToScm") +---- +==== + +You can also further customize the `publishStubsToScm` gradle task. In the following example, +the task is customized to pick contracts from a local git repository: + +==== +[source,groovy,indent=0] +.gradle +---- +publishStubsToScm { + // We want to modify the default set up of the plugin when publish stubs to scm is called + // We want to pick contracts from a Git repository + contractDependency { + stringNotation = "${project.group}:${project.name}:${project.version}" + } + /* + We reuse the contract dependency section to set up the path + to the folder that contains the contract definitions. In our case the + path will be /groupId/artifactId/version/contracts + */ + contractRepository { + repositoryUrl = "git://file://${new File(project.rootDir, "../target")}/contract_empty_git/" + } + // We set the contracts mode to `LOCAL` + contractsMode = "LOCAL" + } +---- +==== + +IMPORTANT:: Starting with the `2.3.0.RELEASE`, the `customize{}` closure previously used for the +`publishStubsToScm` customization is no longer available. The settings should be applied directly +within the `publishStubsToScm` closure, as in the preceding example. + +With such a setup: + +* A git project is cloned to a temporary directory +* The SCM stub downloader goes to the `META-INF/groupId/artifactId/version/contracts` folder +to find contracts. For example, for `com.example:foo:1.0.0`, the path would be +`META-INF/com.example/foo/1.0.0/contracts`. +* Tests are generated from the contracts. +* Stubs are created from the contracts. +* Once the tests pass, the stubs are committed in the cloned repository. +* Finally, a push is sent to that repo's `origin`. + +[[how-to-protocol-convention-producer-with-contracts-stored-locally]] +== Producer with Contracts Stored Locally + +Another option to use the SCM as the destination for stubs and contracts is to store the +contracts locally, with the producer, and only push the contracts and the stubs to SCM. +The following listing shows the setup required to achieve this with Maven and Gradle: + +==== +[source,xml,indent=0,role="primary"] +.Maven +---- +include:../:{samples_url}/producer_with_empty_git/pom.xml[tags=plugin,indent=0] +---- + +[source,groovy,indent=0,role="secondary"] +.Gradle +---- +include:../:{samples_url}/producer_with_empty_git/build.gradle[tags=plugin,indent=0] +---- +==== + +With such a setup: + +* Contracts from the default `src/test/resources/contracts` directory are picked. +* Tests are generated from the contracts. +* Stubs are created from the contracts. +* Once the tests pass: +** The git project is cloned to a temporary directory. +** The stubs and contracts are committed in the cloned repository. +* Finally, a push is done to that repository's `origin`. + +[[how-to-protocol-convention-contracts-producer-stubs-external]] +== Keeping Contracts with the Producer and Stubs in an External Repository + +You can also keep the contracts in the producer repository but keep the stubs in an external git repository. +This is most useful when you want to use the base consumer-producer collaboration flow but cannot +use an artifact repository to store the stubs. + +To do so, use the usual producer setup and then add the `pushStubsToScm` goal and set +`contractsRepositoryUrl` to the repository where you want to keep the stubs. + +[[how-to-protocol-convention-contracts-producer-stubs-external-consumer]] +== Consumer + +On the consumer side, when passing the `repositoryRoot` parameter, +either from the `@AutoConfigureStubRunner` annotation, the +JUnit 4 rule, JUnit 5 extension, or properties, you can pass the URL of the +SCM repository, prefixed with the `git://` protocol. The following example shows how to do so: + +==== +[source,java,indent=0] +---- +@AutoConfigureStubRunner( + stubsMode="REMOTE", + repositoryRoot="git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git", + ids="com.example:bookstore:0.0.1.RELEASE" +) +---- +==== + +With such a setup: + +* The git project is cloned to a temporary directory. +* The SCM stub downloader goes to the `META-INF/groupId/artifactId/version/` folder +to find stub definitions and contracts. For example, for `com.example:foo:1.0.0`, the path would be +`META-INF/com.example/foo/1.0.0/`. +* Stub servers are started and fed with mappings. +* Messaging definitions are read and used in the messaging tests. + diff --git a/docs/modules/ROOT/pages/howto/how-to-use-stubs-from-a-location.adoc b/docs/modules/ROOT/pages/howto/how-to-use-stubs-from-a-location.adoc new file mode 100644 index 0000000000..6138651fda --- /dev/null +++ b/docs/modules/ROOT/pages/howto/how-to-use-stubs-from-a-location.adoc @@ -0,0 +1,5 @@ +[[how-to-use-stubs-from-a-location]] += How Can I Use Stubs from a Location + +If you want to fetch contracts or stubs from a given location without cloning a repository or fetching a JAR, use the `stubs://` protocol when providing the repository root argument for Stub Runner or the Spring Cloud Contract plugin. You can read more about this in <> of the documentation. + diff --git a/docs/modules/ROOT/pages/howto/how-to-use-the-failonnostubs-feature.adoc b/docs/modules/ROOT/pages/howto/how-to-use-the-failonnostubs-feature.adoc new file mode 100644 index 0000000000..29eb58debc --- /dev/null +++ b/docs/modules/ROOT/pages/howto/how-to-use-the-failonnostubs-feature.adoc @@ -0,0 +1,7 @@ +[[how-to-use-the-failonnostubs-feature]] += How Can I Make The Build Pass if There Are No Contracts or Stubs + +If you want Stub Runner not to fail if no stubs were found, switch the `generateStubs` property in the `@AutoConfigureStubRunner` annotation or call the `withFailOnNoStubs(false)` method on the JUnit Rule or Extension. You can read more about this in <> of the documentation. + +If you want the plugins not to fail the build when no contracts were found, you can set the `failOnNoStubs` flag in Maven or call the `contractRepository { failOnNoStubs(false) }` closure in Gradle. + diff --git a/docs/modules/ROOT/pages/howto/how-to-work-with-transitivie.adoc b/docs/modules/ROOT/pages/howto/how-to-work-with-transitivie.adoc new file mode 100644 index 0000000000..0ac9564dec --- /dev/null +++ b/docs/modules/ROOT/pages/howto/how-to-work-with-transitivie.adoc @@ -0,0 +1,49 @@ +[[how-to-work-with-transitivie]] += How Can I Work with Transitive Dependencies? + +The Spring Cloud Contract plugins add the tasks that create the stubs jar for you. One +problem that arises is that, when reusing the stubs, you can mistakenly import all of +that stub's dependencies. When building a Maven artifact, even though you have a couple +of different jars, all of them share one `pom.xml` file, as the following listing shows: + +==== +[source,bash,indent=0] +---- +├── producer-0.0.1.BUILD-20160903.075506-1-stubs.jar +├── producer-0.0.1.BUILD-20160903.075506-1-stubs.jar.sha1 +├── producer-0.0.1.BUILD-20160903.075655-2-stubs.jar +├── producer-0.0.1.BUILD-20160903.075655-2-stubs.jar.sha1 +├── producer-0.0.1.BUILD-SNAPSHOT.jar +├── producer-0.0.1.BUILD-SNAPSHOT.pom +├── producer-0.0.1.BUILD-SNAPSHOT-stubs.jar +├── ... +└── ... +---- +==== + +There are three possibilities of working with those dependencies so as not to have any +issues with transitive dependencies: + +* Mark all application dependencies as optional +* Create a separate `artifactid` for the stubs +* Exclude dependencies on the consumer side + +[[how-to-work-with-transitivie-optional]] +== How Can I Mark All Application Dependencies as Optional? + +If, in the `producer` application, you mark all of your dependencies as optional, +when you include the `producer` stubs in another application (or when that +dependency gets downloaded by Stub Runner), then, since all of the dependencies are +optional, they do not get downloaded. + +[[how-to-work-with-transitivie-separate]] +== How can I Create a Separate `artifactid` for the Stubs? + +If you create a separate `artifactid`, you can set it up in whatever way you wish. +For example, you might decide to have no dependencies at all. + +[[how-to-work-with-transitivie-exclude]] +== How can I Exclude Dependencies on the Consumer Side? + +As a consumer, if you add the stub dependency to your classpath, you can explicitly exclude the unwanted dependencies. + diff --git a/docs/modules/ROOT/pages/howto/why-spring-cloud-contract.adoc b/docs/modules/ROOT/pages/howto/why-spring-cloud-contract.adoc new file mode 100644 index 0000000000..e1ac69de5c --- /dev/null +++ b/docs/modules/ROOT/pages/howto/why-spring-cloud-contract.adoc @@ -0,0 +1,16 @@ +[[why-spring-cloud-contract]] += Why use Spring Cloud Contract? + +Spring Cloud Contract works great in a polyglot environment. This project has a lot of +really interesting features. Quite a few of these features definitely make +Spring Cloud Contract Verifier stand out on the market of Consumer Driven Contract +(CDC) tooling. The most interesting features include the following: + +- Ability to do CDC with messaging. +- Clear and easy to use, statically typed DSL. +- Ability to copy-paste your current JSON file to the contract and edit only its elements. +- Automatic generation of tests from the defined contract. +- Stub Runner functionality: The stubs are automatically downloaded at runtime from Nexus or Artifactory. +- Spring Cloud integration: No discovery service is needed for integration tests. +- Ability to add support for any language & framework through Docker. +