We’re publishing a spring-cloud/spring-cloud-contract-stub-runner Docker image
that will start the standalone version of Stub Runner.
If you want to learn more about the basics of Maven, artifact ids, -group ids, classifiers and Artifact Managers, just click here Section 4.6, “Docker Project”.
Just execute the docker image. You can pass any of the Section 6.8.1, “Common Properties for JUnit and Spring” +group ids, classifiers and Artifact Managers, just click here Section 4.5, “Docker Project”.
Just execute the docker image. You can pass any of the Section 6.8.1, “Common Properties for JUnit and Spring”
as environment variables. The convention is that all the
letters should be upper case. The camel case notation should
and the dot (.) should be separated via underscore (_). E.g.
the stubrunner.repositoryRoot property should be represented
- as a STUBRUNNER_REPOSITORY_ROOT environment variable.
We’d like to use the stubs created in this Section 4.6.4, “Server side (nodejs)” step.
+ as a STUBRUNNER_REPOSITORY_ROOT environment variable.
We’d like to use the stubs created in this Section 4.5.4, “Server side (nodejs)” step.
Let’s assume that we want to run the stubs on port 9876. The NodeJS code
is available here:
$ git clone https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs
$ cd bookstoreLet’s run the Stub Runner Boot application with the stubs.
# Provide the Spring Cloud Contract Docker version diff --git a/multi/multi__spring_cloud_contract_verifier_setup.html b/multi/multi__spring_cloud_contract_verifier_setup.html index b677a642fa..da38d9dc95 100644 --- a/multi/multi__spring_cloud_contract_verifier_setup.html +++ b/multi/multi__spring_cloud_contract_verifier_setup.html @@ -1,6 +1,6 @@ -4. Spring Cloud Contract Verifier Setup You can set up Spring Cloud Contract Verifier in the following ways:
To learn how to set up the Gradle project for Spring Cloud Contract Verifier, read the +
4. Spring Cloud Contract Verifier Setup You can set up Spring Cloud Contract Verifier in the following ways:
To learn how to set up the Gradle project for Spring Cloud Contract Verifier, read the following sections:
- Section 4.1.1, “Prerequisites”
- Section 4.1.2, “Add Gradle Plugin with Dependencies”
- Section 4.1.3, “Gradle and Rest Assured 2.0”
- Section 4.1.4, “Snapshot Versions for Gradle”
- Section 4.1.5, “Add stubs”
- Section 4.1.7, “Default Setup”
- Section 4.1.8, “Configure Plugin”
- Section 4.1.9, “Configuration Options”
- Section 4.1.10, “Single Base Class for All Tests”
- Section 4.1.11, “Different Base Classes for Contracts”
- Section 4.1.12, “Invoking Generated Tests”
- Section 4.1.13, “Pushing stubs to SCM”
- Section 4.1.14, “Spring Cloud Contract Verifier on the Consumer Side”
In order to use Spring Cloud Contract Verifier with WireMock, you muse use either a Gradle or a Maven plugin.
Warning If you want to use Spock in your projects, you must add separately the
spock-coreandspock-springmodules. Check Spock @@ -140,8 +140,7 @@ containing the contracts:
- contractsPath: Specifies the path to the jar. If contract dependencies are downloaded, the path defaults to
groupid/artifactidwheregroupidis slash separated. Otherwise, it scans contracts under the provided directory.- contractsMode: Specifies the mode of downloading contracts (whether the -JAR is available offline, remotely etc.)
- contractsSnapshotCheckSkip: If set to
truewill not assert whether the -downloaded stubs / contract JAR was downloaded from a remote location or a local one(only applicable to Maven repos, not Git or Pact).- deleteStubsAfterTest: If set to
falsewill not remove any downloaded +JAR is available offline, remotely etc.)- deleteStubsAfterTest: If set to
falsewill not remove any downloaded contracts from temporary directoriesWhen using Spring Cloud Contract Verifier in default MockMvc, you need to create a base specification for all generated acceptance tests. In this class, you need to point to an endpoint, which should be verified.
abstract class BaseMockMvcSpec extends Specification { @@ -381,8 +380,7 @@ extendscom.example.base.BaseClass. This setting ta packageWithBaseClasses and baseClassForTests.contractsProperties: a map containing properties to be passed to Spring Cloud Contract components. Those properties might be used by e.g. inbuilt or custom Stub Downloaders. If you want to download your contract definitions from a Maven repository, you can use the following options:
- contractDependency: The contract dependency that contains all the packaged contracts.
- contractsPath: The path to the concrete contracts in the JAR with packaged contracts. -Defaults to
groupid/artifactidwheregropuidis slash separated.- contractsMode: Picks the mode in which stubs will be found and registered
- contractsSnapshotCheckSkip: If
truethen will not assert whether a stub / contract -JAR was downloaded from local or remote location- deleteStubsAfterTest: If set to
falsewill not remove any downloaded +Defaults togroupid/artifactidwheregropuidis slash separated.- contractsMode: Picks the mode in which stubs will be found and registered
- deleteStubsAfterTest: If set to
falsewill not remove any downloaded contracts from temporary directories- contractsRepositoryUrl: URL to a repo with the artifacts that have contracts. If it is not provided, use the current Maven ones.
- contractsRepositoryUsername: The user name to be used to connect to the repo with contracts.
- contractsRepositoryPassword: The password to be used to connect to the repo with contracts.
- contractsRepositoryProxyHost: The proxy host to be used to connect to the repo with contracts.
- contractsRepositoryProxyPort: The proxy port to be used to connect to the repo with contracts.
We cache only non-snapshot, explicitly provided versions (for example
+or1.0.0.BUILD-SNAPSHOTwon’t get cached). By default, this feature is turned on.When using Spring Cloud Contract Verifier in default MockMvc, you need to create a base @@ -594,15 +592,7 @@ when you include the
github-webhookstubs in anothe dependency gets downloaded by Stub Runner) then, since all of the dependencies are optional, they will not get downloaded.Create a separate
artifactidfor the stubsIf you create a separate
artifactid, then you can set it up in whatever way you wish. For example, you might decide to have no dependencies at all.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.
When fetching stubs / contracts in a CI, shared environment, what might happen is that -both the producer and the consumer reuse the same local Maven repository. Due to this, -the framework, responsible for downloading a stub JAR from remote location, -can’t decide which JAR should be picked, local or remote one. That caused -the
"The artifact was found in the local repository but you have explicitly -stated that it should be downloaded from a remote one"exception -and failed the build.For such cases we’re introducing the property and plugin setup mechanism:
- via
stubrunner.snapshot-check-skipsystem property- via
STUBRUNNER_SNAPSHOT_CHECK_SKIPenvironment variableif either of these values is set to
true, then the stub downloader will not -verify the origin of the downloaded JAR.For the plugins you need to set the
contractsSnapshotCheckSkipproperty -totrue.You can handle scenarios with Spring Cloud Contract Verifier. All you need to do is to +exclude the unwanted dependencies.
You can handle scenarios with Spring Cloud Contract Verifier. All you need to do is to stick to the proper naming convention while creating your contracts. The convention requires including an order number followed by an underscore. This will work regardles of whether you’re working with YAML or Groovy. Example:
my_contracts_dir\ @@ -611,10 +601,10 @@ requires including an order number followed by an underscore. This will work reg 2_showCart.groovy 3_logout.groovySuch a tree causes Spring Cloud Contract Verifier to generate WireMock’s scenario with a name of
scenario1and the three following steps:
- login marked as
Startedpointing to…- showCart marked as
Step1pointing to…- logout marked as
Step2which will close the scenario.More details about WireMock scenarios can be found at -http://wiremock.org/docs/stateful-behaviour/
Spring Cloud Contract Verifier also generates tests with a guaranteed order of execution.
We’re publishing a
springcloud/spring-cloud-contractDocker image +http://wiremock.org/docs/stateful-behaviour/Spring Cloud Contract Verifier also generates tests with a guaranteed order of execution.
We’re publishing a
springcloud/spring-cloud-contractDocker image that contains a project that will generate tests and execute them inEXPLICITmode against a running application.
Tip The
EXPLICITmode means that the tests generated from contracts will send -real requests and not the mocked ones.Since the Docker image can be used by non JVM projects, it’s good to explain the basic terms behind Spring Cloud Contract packaging defaults.
Part of the following definitions were taken from the Maven Glossary
Project: Maven thinks in terms of projects. Everything that you will build are projects. Those projects follow a well defined “Project Object Model”. Projects can depend on other projects, @@ -641,7 +631,7 @@ like them to be available for others to download / reference or reuse. In case of the JVM world those artifacts would be JARs, for Ruby these are gems and for Docker those would be Docker images. You can store those artifacts in a manager. Examples of such managers can be Artifactory -or Nexus.The image searches for contracts under the
/contractsfolder. +or Nexus.The image searches for contracts under the
/contractsfolder. The output from running the tests will be available under/spring-cloud-contract/buildfolder (it’s useful for debugging purposes).It’s enough for you to mount your contracts, pass the environment variables @@ -656,8 +646,8 @@ for group id
foo.barand artifact id.m2. Mount your local.m2as a volume available at the container’s/root/.m2path. You must not set bothEXTERNAL_CONTRACTS_WORK_OFFLINEandEXTERNAL_CONTRACTS_REPO_WITH_BINARIES_URL.These environment variables are used when tests are executed:
APPLICATION_BASE_URL- url against which tests should be executed. Remember that it has to be accessible from the Docker container (e.g.localhost-will not work)APPLICATION_USERNAME- (optional) username for basic authentication to your applicationAPPLICATION_PASSWORD- (optional) password for basic authentication to your applicationLet’s take a look at a simple MVC application
$ git clone https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs -$ cd bookstoreThe contracts are available under
/contractsfolder.Since we want to run tests, we could just execute:
$ npm testhowever, for learning purposes, let’s split it into pieces:
# Stop docker infra (nodejs, artifactory) +will not work)APPLICATION_USERNAME- (optional) username for basic authentication to your applicationAPPLICATION_PASSWORD- (optional) password for basic authentication to your applicationLet’s take a look at a simple MVC application
$ git clone https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs +$ cd bookstoreThe contracts are available under
/contractsfolder.Since we want to run tests, we could just execute:
$ npm testhowever, for learning purposes, let’s split it into pieces:
# Stop docker infra (nodejs, artifactory) $ ./stop_infra.sh # Start docker infra (nodejs, artifactory) $ ./setup_infra.sh diff --git a/multi/multi__using_the_pluggable_architecture.html b/multi/multi__using_the_pluggable_architecture.html index fb9a00cd1e..36bc274fcf 100644 --- a/multi/multi__using_the_pluggable_architecture.html +++ b/multi/multi__using_the_pluggable_architecture.html @@ -421,7 +421,7 @@ to clone the repository and use it as a source of contracts to generate tests or stubs.Either via environment variables, system properties, properties set inside the plugin or contracts repository configuration you can tweak the downloader’s behaviour. Below you can find the list of -properties
Table 10.1. SCM Stub Downloader properties
Type of a property
Name of the property
Description
*
git.branch(plugin prop) +propertiesTable 10.1. SCM Stub Downloader properties
Type of a property
Name of the property
Description
*
git.branch(plugin prop)*
stubrunner.properties.git.branch(system prop)*
STUBRUNNER_PROPERTIES_GIT_BRANCH(env prop)master
Which branch to checkout
*
git.username(plugin prop)*
stubrunner.properties.git.username(system prop) @@ -437,7 +437,7 @@ to fetch the Pact contract definitions from the Pact Broker. Whatever is set afterpact://will be parsed as the Pact Broker URL.Either via environment variables, system properties, properties set inside the plugin or contracts repository configuration you can tweak the downloader’s behaviour. Below you can find the list of -properties
Table 10.2. SCM Stub Downloader properties
Name of a property
Default
Description
*
pactbroker.host(plugin prop) +propertiesTable 10.2. SCM Stub Downloader properties
Name of a property
Default
Description
*
pactbroker.host(plugin prop)*
stubrunner.properties.pactbroker.host(system prop)*
STUBRUNNER_PROPERTIES_PACTBROKER_HOST(env prop)Host from URL passed to
repositoryRootWhat is the URL of Pact Broker
*
pactbroker.port(plugin prop)*
-stubrunner.properties.pactbroker.port(system prop) diff --git a/multi/multi_spring-cloud-contract.html b/multi/multi_spring-cloud-contract.html index 83e3f906f9..a39faeda28 100644 --- a/multi/multi_spring-cloud-contract.html +++ b/multi/multi_spring-cloud-contract.html @@ -1,3 +1,3 @@Spring Cloud Contract \ No newline at end of file +Table of Contents
- 1. Spring Cloud Contract
- 2. Spring Cloud Contract Verifier Introduction
- 3. Spring Cloud Contract FAQ
- 3.1. Why use Spring Cloud Contract Verifier and not X ?
- 3.2. I don’t want to write a contract in Groovy!
- 3.3. What is this value(consumer(), producer()) ?
- 3.4. How to do Stubs versioning?
- 3.5. Common repo with contracts
- 3.6. Do I need a Binary Storage? Can’t I use Git?
- 3.7. Can I use the Pact Broker?
- 3.8. How can I debug the request/response being sent by the generated tests client?
- 4. Spring Cloud Contract Verifier Setup
- 4.1. Gradle Project
- 4.1.1. Prerequisites
- 4.1.2. Add Gradle Plugin with Dependencies
- 4.1.3. Gradle and Rest Assured 2.0
- 4.1.4. Snapshot Versions for Gradle
- 4.1.5. Add stubs
- 4.1.6. Run the Plugin
- 4.1.7. Default Setup
- 4.1.8. Configure Plugin
- 4.1.9. Configuration Options
- 4.1.10. Single Base Class for All Tests
- 4.1.11. Different Base Classes for Contracts
- 4.1.12. Invoking Generated Tests
- 4.1.13. Pushing stubs to SCM
- 4.1.14. Spring Cloud Contract Verifier on the Consumer Side
- 4.2. Maven Project
- 4.2.1. Add maven plugin
- 4.2.2. Maven and Rest Assured 2.0
- 4.2.3. Snapshot versions for Maven
- 4.2.4. Add stubs
- 4.2.5. Run plugin
- 4.2.6. Configure plugin
- 4.2.7. Configuration Options
- 4.2.8. Single Base Class for All Tests
- 4.2.9. Different base classes for contracts
- 4.2.10. Invoking generated tests
- 4.2.11. Pushing stubs to SCM
- 4.2.12. Maven Plugin and STS
- 4.3. Stubs and Transitive Dependencies
- 4.4. CI Server setup
- 4.5. Scenarios
- 4.6. Docker Project
- 5. Spring Cloud Contract Verifier Messaging
- 6. Spring Cloud Contract Stub Runner
- 7. Stub Runner for Messaging
- 8. Contract DSL
- 8.1. Limitations
- 8.2. Common Top-Level elements
- 8.3. Request
- 8.4. Response
- 8.5. Dynamic properties
- 8.6. JAX-RS Support
- 8.7. Async Support
- 8.8. Working with Context Paths
- 8.9. Working with Web Flux
- 8.10. Messaging Top-Level Elements
- 8.11. Multiple Contracts in One File
- 8.12. Generating Spring REST Docs snippets from the contracts
- 9. Customization
- 10. Using the Pluggable Architecture
- 11. Spring Cloud Contract WireMock
- 11.1. Registering Stubs Automatically
- 11.2. Using Files to Specify the Stub Bodies
- 11.3. Alternative: Using JUnit Rules
- 11.4. Relaxed SSL Validation for Rest Template
- 11.5. WireMock and Spring MVC Mocks
- 11.6. Customization of WireMock configuration
- 11.7. Generating Stubs using REST Docs
- 11.8. Generating Contracts by Using REST Docs
- 12. Migrations
- 13. Links
Spring Cloud Contract \ No newline at end of file diff --git a/single/spring-cloud-contract.html b/single/spring-cloud-contract.html index 25a24c1ace..9c7997b6b3 100644 --- a/single/spring-cloud-contract.html +++ b/single/spring-cloud-contract.html @@ -1,6 +1,6 @@ -Table of Contents
- 1. Spring Cloud Contract
- 2. Spring Cloud Contract Verifier Introduction
- 3. Spring Cloud Contract FAQ
- 3.1. Why use Spring Cloud Contract Verifier and not X ?
- 3.2. I don’t want to write a contract in Groovy!
- 3.3. What is this value(consumer(), producer()) ?
- 3.4. How to do Stubs versioning?
- 3.5. Common repo with contracts
- 3.6. Do I need a Binary Storage? Can’t I use Git?
- 3.7. Can I use the Pact Broker?
- 3.8. How can I debug the request/response being sent by the generated tests client?
- 4. Spring Cloud Contract Verifier Setup
- 4.1. Gradle Project
- 4.1.1. Prerequisites
- 4.1.2. Add Gradle Plugin with Dependencies
- 4.1.3. Gradle and Rest Assured 2.0
- 4.1.4. Snapshot Versions for Gradle
- 4.1.5. Add stubs
- 4.1.6. Run the Plugin
- 4.1.7. Default Setup
- 4.1.8. Configure Plugin
- 4.1.9. Configuration Options
- 4.1.10. Single Base Class for All Tests
- 4.1.11. Different Base Classes for Contracts
- 4.1.12. Invoking Generated Tests
- 4.1.13. Pushing stubs to SCM
- 4.1.14. Spring Cloud Contract Verifier on the Consumer Side
- 4.2. Maven Project
- 4.2.1. Add maven plugin
- 4.2.2. Maven and Rest Assured 2.0
- 4.2.3. Snapshot versions for Maven
- 4.2.4. Add stubs
- 4.2.5. Run plugin
- 4.2.6. Configure plugin
- 4.2.7. Configuration Options
- 4.2.8. Single Base Class for All Tests
- 4.2.9. Different base classes for contracts
- 4.2.10. Invoking generated tests
- 4.2.11. Pushing stubs to SCM
- 4.2.12. Maven Plugin and STS
- 4.3. Stubs and Transitive Dependencies
- 4.4. Scenarios
- 4.5. Docker Project
- 5. Spring Cloud Contract Verifier Messaging
- 6. Spring Cloud Contract Stub Runner
- 7. Stub Runner for Messaging
- 8. Contract DSL
- 8.1. Limitations
- 8.2. Common Top-Level elements
- 8.3. Request
- 8.4. Response
- 8.5. Dynamic properties
- 8.6. JAX-RS Support
- 8.7. Async Support
- 8.8. Working with Context Paths
- 8.9. Working with Web Flux
- 8.10. Messaging Top-Level Elements
- 8.11. Multiple Contracts in One File
- 8.12. Generating Spring REST Docs snippets from the contracts
- 9. Customization
- 10. Using the Pluggable Architecture
- 11. Spring Cloud Contract WireMock
- 11.1. Registering Stubs Automatically
- 11.2. Using Files to Specify the Stub Bodies
- 11.3. Alternative: Using JUnit Rules
- 11.4. Relaxed SSL Validation for Rest Template
- 11.5. WireMock and Spring MVC Mocks
- 11.6. Customization of WireMock configuration
- 11.7. Generating Stubs using REST Docs
- 11.8. Generating Contracts by Using REST Docs
- 12. Migrations
- 13. Links
Spring Cloud Contract Table of Contents
- 1. Spring Cloud Contract
- 2. Spring Cloud Contract Verifier Introduction
- 3. Spring Cloud Contract FAQ
- 3.1. Why use Spring Cloud Contract Verifier and not X ?
- 3.2. I don’t want to write a contract in Groovy!
- 3.3. What is this value(consumer(), producer()) ?
- 3.4. How to do Stubs versioning?
- 3.5. Common repo with contracts
- 3.6. Do I need a Binary Storage? Can’t I use Git?
- 3.7. Can I use the Pact Broker?
- 3.8. How can I debug the request/response being sent by the generated tests client?
- 4. Spring Cloud Contract Verifier Setup
- 4.1. Gradle Project
- 4.1.1. Prerequisites
- 4.1.2. Add Gradle Plugin with Dependencies
- 4.1.3. Gradle and Rest Assured 2.0
- 4.1.4. Snapshot Versions for Gradle
- 4.1.5. Add stubs
- 4.1.6. Run the Plugin
- 4.1.7. Default Setup
- 4.1.8. Configure Plugin
- 4.1.9. Configuration Options
- 4.1.10. Single Base Class for All Tests
- 4.1.11. Different Base Classes for Contracts
- 4.1.12. Invoking Generated Tests
- 4.1.13. Pushing stubs to SCM
- 4.1.14. Spring Cloud Contract Verifier on the Consumer Side
- 4.2. Maven Project
- 4.2.1. Add maven plugin
- 4.2.2. Maven and Rest Assured 2.0
- 4.2.3. Snapshot versions for Maven
- 4.2.4. Add stubs
- 4.2.5. Run plugin
- 4.2.6. Configure plugin
- 4.2.7. Configuration Options
- 4.2.8. Single Base Class for All Tests
- 4.2.9. Different base classes for contracts
- 4.2.10. Invoking generated tests
- 4.2.11. Pushing stubs to SCM
- 4.2.12. Maven Plugin and STS
- 4.3. Stubs and Transitive Dependencies
- 4.4. CI Server setup
- 4.5. Scenarios
- 4.6. Docker Project
- 5. Spring Cloud Contract Verifier Messaging
- 6. Spring Cloud Contract Stub Runner
- 7. Stub Runner for Messaging
- 8. Contract DSL
- 8.1. Limitations
- 8.2. Common Top-Level elements
- 8.3. Request
- 8.4. Response
- 8.5. Dynamic properties
- 8.6. JAX-RS Support
- 8.7. Async Support
- 8.8. Working with Context Paths
- 8.9. Working with Web Flux
- 8.10. Messaging Top-Level Elements
- 8.11. Multiple Contracts in One File
- 8.12. Generating Spring REST Docs snippets from the contracts
- 9. Customization
- 10. Using the Pluggable Architecture
- 11. Spring Cloud Contract WireMock
- 11.1. Registering Stubs Automatically
- 11.2. Using Files to Specify the Stub Bodies
- 11.3. Alternative: Using JUnit Rules
- 11.4. Relaxed SSL Validation for Rest Template
- 11.5. WireMock and Spring MVC Mocks
- 11.6. Customization of WireMock configuration
- 11.7. Generating Stubs using REST Docs
- 11.8. Generating Contracts by Using REST Docs
- 12. Migrations
- 13. Links
Documentation Authors: Adam Dudczak, Mathias Düsterhöft, Marcin Grzejszczak, Dennis Kieselhorst, Jakub Kubryński, Karol Lassak, +
Spring Cloud Contract Table of Contents
- 1. Spring Cloud Contract
- 2. Spring Cloud Contract Verifier Introduction
- 3. Spring Cloud Contract FAQ
- 3.1. Why use Spring Cloud Contract Verifier and not X ?
- 3.2. I don’t want to write a contract in Groovy!
- 3.3. What is this value(consumer(), producer()) ?
- 3.4. How to do Stubs versioning?
- 3.5. Common repo with contracts
- 3.6. Do I need a Binary Storage? Can’t I use Git?
- 3.7. Can I use the Pact Broker?
- 3.8. How can I debug the request/response being sent by the generated tests client?
- 4. Spring Cloud Contract Verifier Setup
- 4.1. Gradle Project
- 4.1.1. Prerequisites
- 4.1.2. Add Gradle Plugin with Dependencies
- 4.1.3. Gradle and Rest Assured 2.0
- 4.1.4. Snapshot Versions for Gradle
- 4.1.5. Add stubs
- 4.1.6. Run the Plugin
- 4.1.7. Default Setup
- 4.1.8. Configure Plugin
- 4.1.9. Configuration Options
- 4.1.10. Single Base Class for All Tests
- 4.1.11. Different Base Classes for Contracts
- 4.1.12. Invoking Generated Tests
- 4.1.13. Pushing stubs to SCM
- 4.1.14. Spring Cloud Contract Verifier on the Consumer Side
- 4.2. Maven Project
- 4.2.1. Add maven plugin
- 4.2.2. Maven and Rest Assured 2.0
- 4.2.3. Snapshot versions for Maven
- 4.2.4. Add stubs
- 4.2.5. Run plugin
- 4.2.6. Configure plugin
- 4.2.7. Configuration Options
- 4.2.8. Single Base Class for All Tests
- 4.2.9. Different base classes for contracts
- 4.2.10. Invoking generated tests
- 4.2.11. Pushing stubs to SCM
- 4.2.12. Maven Plugin and STS
- 4.3. Stubs and Transitive Dependencies
- 4.4. Scenarios
- 4.5. Docker Project
- 5. Spring Cloud Contract Verifier Messaging
- 6. Spring Cloud Contract Stub Runner
- 7. Stub Runner for Messaging
- 8. Contract DSL
- 8.1. Limitations
- 8.2. Common Top-Level elements
- 8.3. Request
- 8.4. Response
- 8.5. Dynamic properties
- 8.6. JAX-RS Support
- 8.7. Async Support
- 8.8. Working with Context Paths
- 8.9. Working with Web Flux
- 8.10. Messaging Top-Level Elements
- 8.11. Multiple Contracts in One File
- 8.12. Generating Spring REST Docs snippets from the contracts
- 9. Customization
- 10. Using the Pluggable Architecture
- 11. Spring Cloud Contract WireMock
- 11.1. Registering Stubs Automatically
- 11.2. Using Files to Specify the Stub Bodies
- 11.3. Alternative: Using JUnit Rules
- 11.4. Relaxed SSL Validation for Rest Template
- 11.5. WireMock and Spring MVC Mocks
- 11.6. Customization of WireMock configuration
- 11.7. Generating Stubs using REST Docs
- 11.8. Generating Contracts by Using REST Docs
- 12. Migrations
- 13. Links
Documentation Authors: Adam Dudczak, Mathias Düsterhöft, Marcin Grzejszczak, Dennis Kieselhorst, Jakub Kubryński, Karol Lassak, Olga Maciaszek-Sharma, Mariusz Smykuła, Dave Syer, Jay Bryant
2.1.0.BUILD-SNAPSHOT
You need confidence when pushing new features to a new application or service in a distributed system. This project provides support for Consumer Driven Contracts and service schemas in Spring applications (for both HTTP and message-based interactions), @@ -1380,7 +1380,7 @@ matching response definition was picked.
To turn off this feature just bum to dump all mappings per artifact id. Also the port at which the given stub server was started will be attached.
You can set up Spring Cloud Contract Verifier in the following ways:
You can set up Spring Cloud Contract Verifier in the following ways:
To learn how to set up the Gradle project for Spring Cloud Contract Verifier, read the following sections:
- Section 4.1.1, “Prerequisites”
- Section 4.1.2, “Add Gradle Plugin with Dependencies”
- Section 4.1.3, “Gradle and Rest Assured 2.0”
- Section 4.1.4, “Snapshot Versions for Gradle”
- Section 4.1.5, “Add stubs”
- Section 4.1.7, “Default Setup”
- Section 4.1.8, “Configure Plugin”
- Section 4.1.9, “Configuration Options”
- Section 4.1.10, “Single Base Class for All Tests”
- Section 4.1.11, “Different Base Classes for Contracts”
- Section 4.1.12, “Invoking Generated Tests”
- Section 4.1.13, “Pushing stubs to SCM”
- Section 4.1.14, “Spring Cloud Contract Verifier on the Consumer Side”
In order to use Spring Cloud Contract Verifier with WireMock, you muse use either a Gradle or a Maven plugin.
Warning If you want to use Spock in your projects, you must add separately the
spock-coreandspock-springmodules. Check Spock @@ -1520,8 +1520,7 @@ containing the contracts:
- contractsPath: Specifies the path to the jar. If contract dependencies are downloaded, the path defaults to
groupid/artifactidwheregroupidis slash separated. Otherwise, it scans contracts under the provided directory.- contractsMode: Specifies the mode of downloading contracts (whether the -JAR is available offline, remotely etc.)
- contractsSnapshotCheckSkip: If set to
truewill not assert whether the -downloaded stubs / contract JAR was downloaded from a remote location or a local one(only applicable to Maven repos, not Git or Pact).- deleteStubsAfterTest: If set to
falsewill not remove any downloaded +JAR is available offline, remotely etc.)- deleteStubsAfterTest: If set to
falsewill not remove any downloaded contracts from temporary directoriesWhen using Spring Cloud Contract Verifier in default MockMvc, you need to create a base specification for all generated acceptance tests. In this class, you need to point to an endpoint, which should be verified.
abstract class BaseMockMvcSpec extends Specification { @@ -1761,8 +1760,7 @@ extendscom.example.base.BaseClass. This setting ta packageWithBaseClasses and baseClassForTests.contractsProperties: a map containing properties to be passed to Spring Cloud Contract components. Those properties might be used by e.g. inbuilt or custom Stub Downloaders. If you want to download your contract definitions from a Maven repository, you can use the following options:
- contractDependency: The contract dependency that contains all the packaged contracts.
- contractsPath: The path to the concrete contracts in the JAR with packaged contracts. -Defaults to
groupid/artifactidwheregropuidis slash separated.- contractsMode: Picks the mode in which stubs will be found and registered
- contractsSnapshotCheckSkip: If
truethen will not assert whether a stub / contract -JAR was downloaded from local or remote location- deleteStubsAfterTest: If set to
falsewill not remove any downloaded +Defaults togroupid/artifactidwheregropuidis slash separated.- contractsMode: Picks the mode in which stubs will be found and registered
- deleteStubsAfterTest: If set to
falsewill not remove any downloaded contracts from temporary directories- contractsRepositoryUrl: URL to a repo with the artifacts that have contracts. If it is not provided, use the current Maven ones.
- contractsRepositoryUsername: The user name to be used to connect to the repo with contracts.
- contractsRepositoryPassword: The password to be used to connect to the repo with contracts.
- contractsRepositoryProxyHost: The proxy host to be used to connect to the repo with contracts.
- contractsRepositoryProxyPort: The proxy port to be used to connect to the repo with contracts.
We cache only non-snapshot, explicitly provided versions (for example
+or1.0.0.BUILD-SNAPSHOTwon’t get cached). By default, this feature is turned on.When using Spring Cloud Contract Verifier in default MockMvc, you need to create a base @@ -1974,15 +1972,7 @@ when you include the
github-webhookstubs in anothe dependency gets downloaded by Stub Runner) then, since all of the dependencies are optional, they will not get downloaded.Create a separate
artifactidfor the stubsIf you create a separate
artifactid, then you can set it up in whatever way you wish. For example, you might decide to have no dependencies at all.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.
When fetching stubs / contracts in a CI, shared environment, what might happen is that -both the producer and the consumer reuse the same local Maven repository. Due to this, -the framework, responsible for downloading a stub JAR from remote location, -can’t decide which JAR should be picked, local or remote one. That caused -the
"The artifact was found in the local repository but you have explicitly -stated that it should be downloaded from a remote one"exception -and failed the build.For such cases we’re introducing the property and plugin setup mechanism:
- via
stubrunner.snapshot-check-skipsystem property- via
STUBRUNNER_SNAPSHOT_CHECK_SKIPenvironment variableif either of these values is set to
true, then the stub downloader will not -verify the origin of the downloaded JAR.For the plugins you need to set the
contractsSnapshotCheckSkipproperty -totrue.You can handle scenarios with Spring Cloud Contract Verifier. All you need to do is to +exclude the unwanted dependencies.
You can handle scenarios with Spring Cloud Contract Verifier. All you need to do is to stick to the proper naming convention while creating your contracts. The convention requires including an order number followed by an underscore. This will work regardles of whether you’re working with YAML or Groovy. Example:
my_contracts_dir\ @@ -1991,10 +1981,10 @@ requires including an order number followed by an underscore. This will work reg 2_showCart.groovy 3_logout.groovySuch a tree causes Spring Cloud Contract Verifier to generate WireMock’s scenario with a name of
scenario1and the three following steps:
- login marked as
Startedpointing to…- showCart marked as
Step1pointing to…- logout marked as
Step2which will close the scenario.More details about WireMock scenarios can be found at -http://wiremock.org/docs/stateful-behaviour/
Spring Cloud Contract Verifier also generates tests with a guaranteed order of execution.
We’re publishing a
springcloud/spring-cloud-contractDocker image +http://wiremock.org/docs/stateful-behaviour/Spring Cloud Contract Verifier also generates tests with a guaranteed order of execution.
We’re publishing a
springcloud/spring-cloud-contractDocker image that contains a project that will generate tests and execute them inEXPLICITmode against a running application.
Tip The
EXPLICITmode means that the tests generated from contracts will send -real requests and not the mocked ones.Since the Docker image can be used by non JVM projects, it’s good to explain the basic terms behind Spring Cloud Contract packaging defaults.
Part of the following definitions were taken from the Maven Glossary
Project: Maven thinks in terms of projects. Everything that you will build are projects. Those projects follow a well defined “Project Object Model”. Projects can depend on other projects, @@ -2021,7 +2011,7 @@ like them to be available for others to download / reference or reuse. In case of the JVM world those artifacts would be JARs, for Ruby these are gems and for Docker those would be Docker images. You can store those artifacts in a manager. Examples of such managers can be Artifactory -or Nexus.The image searches for contracts under the
/contractsfolder. +or Nexus.The image searches for contracts under the
/contractsfolder. The output from running the tests will be available under/spring-cloud-contract/buildfolder (it’s useful for debugging purposes).It’s enough for you to mount your contracts, pass the environment variables @@ -2036,8 +2026,8 @@ for group id
foo.barand artifact id.m2. Mount your local.m2as a volume available at the container’s/root/.m2path. You must not set bothEXTERNAL_CONTRACTS_WORK_OFFLINEandEXTERNAL_CONTRACTS_REPO_WITH_BINARIES_URL.These environment variables are used when tests are executed:
APPLICATION_BASE_URL- url against which tests should be executed. Remember that it has to be accessible from the Docker container (e.g.localhost-will not work)APPLICATION_USERNAME- (optional) username for basic authentication to your applicationAPPLICATION_PASSWORD- (optional) password for basic authentication to your applicationLet’s take a look at a simple MVC application
$ git clone https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs -$ cd bookstoreThe contracts are available under
/contractsfolder.Since we want to run tests, we could just execute:
$ npm testhowever, for learning purposes, let’s split it into pieces:
# Stop docker infra (nodejs, artifactory) +will not work)APPLICATION_USERNAME- (optional) username for basic authentication to your applicationAPPLICATION_PASSWORD- (optional) password for basic authentication to your applicationLet’s take a look at a simple MVC application
$ git clone https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs +$ cd bookstoreThe contracts are available under
/contractsfolder.Since we want to run tests, we could just execute:
$ npm testhowever, for learning purposes, let’s split it into pieces:
# Stop docker infra (nodejs, artifactory) $ ./stop_infra.sh # Start docker infra (nodejs, artifactory) $ ./setup_infra.sh @@ -3033,12 +3023,12 @@ would like the Stub Runner to take into consideration. You can read more about t Aether versioning ranges here.We’re publishing a
spring-cloud/spring-cloud-contract-stub-runnerDocker image that will start the standalone version of Stub Runner.If you want to learn more about the basics of Maven, artifact ids, -group ids, classifiers and Artifact Managers, just click here Section 4.6, “Docker Project”.
Just execute the docker image. You can pass any of the Section 6.8.1, “Common Properties for JUnit and Spring” +group ids, classifiers and Artifact Managers, just click here Section 4.5, “Docker Project”.
Just execute the docker image. You can pass any of the Section 6.8.1, “Common Properties for JUnit and Spring” as environment variables. The convention is that all the letters should be upper case. The camel case notation should and the dot (
.) should be separated via underscore (_). E.g. thestubrunner.repositoryRootproperty should be represented - as aSTUBRUNNER_REPOSITORY_ROOTenvironment variable.We’d like to use the stubs created in this Section 4.6.4, “Server side (nodejs)” step. + as a
STUBRUNNER_REPOSITORY_ROOTenvironment variable.We’d like to use the stubs created in this Section 4.5.4, “Server side (nodejs)” step. Let’s assume that we want to run the stubs on port
9876. The NodeJS code is available here:$ git clone https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs $ cd bookstoreLet’s run the Stub Runner Boot application with the stubs.
# Provide the Spring Cloud Contract Docker version @@ -5930,7 +5920,7 @@ to clone the repository and use it as a source of contracts to generate tests or stubs.Either via environment variables, system properties, properties set inside the plugin or contracts repository configuration you can tweak the downloader’s behaviour. Below you can find the list of -properties
Table 10.1. SCM Stub Downloader properties
![[Warning]](images/warning.png)
![[Tip]](images/tip.png)