s
You can disable Stub Runner support by providing: stubrunner.cloud.enabled equal to false![[Tip]](images/tip.png)
Tip By default all service discovery will be stubbed. That means that regardless of the fact if you have
an existing DiscoveryClient its results will be ignored. However, if you want to reuse it, just set
stubrunner.cloud.delegate.enabled to true and then your existing DiscoveryClient results will be
- merged with the stubbed ones.
Spring Cloud Contract Stub Runner Boot is a Spring Boot application that exposes REST endpoints to
+ merged with the stubbed ones.
The default Maven configuration used by Stub Runner can be tweaked either
+via the following system properties or environment variables
maven.repo.local - path to the custom maven local repository locationorg.apache.maven.user-settings - path to custom maven user settings locationorg.apache.maven.global-settings - path to maven global settings location
Spring Cloud Contract Stub Runner Boot is a Spring Boot application that exposes REST endpoints to
trigger the messaging labels and to access started WireMock servers.
One of the use-cases is to run some smoke (end to end) tests on a deployed application.
You can check out the Spring Cloud Pipelines
-project for more information.
Just add the
compile "org.springframework.cloud:spring-cloud-starter-stub-runner"Annotate a class with @EnableStubRunnerServer, build a fat-jar and you’re ready to go!
For the properties check the Stub Runner Spring section.
Starting from 1.4.0.RELEASE version of the Spring Cloud CLI
+project for more information.
Just add the
compile "org.springframework.cloud:spring-cloud-starter-stub-runner"Annotate a class with @EnableStubRunnerServer, build a fat-jar and you’re ready to go!
For the properties check the Stub Runner Spring section.
You can download a standalone JAR from Maven (for example, for version 1.2.3.RELEASE), as follows:
$ wget -O stub-runner.jar 'https://search.maven.org/remote_content?g=org.springframework.cloud&a=spring-cloud-contract-stub-runner-boot&v=1.2.3.RELEASE'
+$ java -jar stub-runner.jar --stubrunner.ids=... --stubrunner.repositoryRoot=...Starting from 1.4.0.RELEASE version of the Spring Cloud CLI
project you can start Stub Runner Boot by executing spring cloud stubrunner.
In order to pass the configuration just create a stubrunner.yml file in the current working directory
or a subdirectory called config or in ~/.spring-cloud. The file could look like this
(example for running stubs installed locally)
stubrunner.yml.
@@ -687,12 +689,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-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.5, “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.6, “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.5.4, “Server side (nodejs)” step.
+ 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.
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/1.2.x/multi/multi__spring_cloud_contract_verifier_introduction.html b/1.2.x/multi/multi__spring_cloud_contract_verifier_introduction.html
index 310fb42260..871cb10cd3 100644
--- a/1.2.x/multi/multi__spring_cloud_contract_verifier_introduction.html
+++ b/1.2.x/multi/multi__spring_cloud_contract_verifier_introduction.html
@@ -9,14 +9,14 @@ produced by Spring Cloud Contract Verifier.Messaging r
Integration, Spring Cloud Stream, Spring AMQP, and Apache Camel. You can also set your
own integrations. Acceptance tests (in JUnit or Spock) are used to verify if server-side implementation
of the API is compliant with the contract (server tests). A full test is generated by
-Spring Cloud Contract Verifier. Assume that we have a system consisting of multiple microservices:
If we wanted to test the application in top left corner to determine whether it can
+Spring Cloud Contract Verifier.
Assume that we have a system consisting of multiple microservices:
If we wanted to test the application in top left corner 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/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 6 microservices, a couple of databases,
etc.
- 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/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 Verifier with Stub Runner 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.
Spring Cloud Contract Verifier gives you the certainty that the stubs that you use were
+are those that your application directly uses.
Spring Cloud Contract Verifier gives you the certainty that the stubs that you use were
created by the service that you’re calling. Also, if you can use them, it means that they
were tested against the producer’s side. In short, you can trust those stubs.
The main purposes of Spring Cloud Contract Verifier with Stub Runner are:
- To ensure that WireMock/Messaging stubs (used when developing the client) do exactly
what the actual server-side implementation does.
- To promote ATDD method and Microservices architectural style.
- To provide a way to publish changes in contracts that are immediately visible on both
@@ -176,8 +176,8 @@ us. The current implementation of our system grants loans to everybody.
As
sprint, we must develop a new feature: if a client wants to borrow too much money, then
we mark the client as a fraud.
Technical remark - Fraud Detection has an artifact-id of http-server, while Loan
Issuance has an artifact-id of http-client, and both have a group-id of com.example.
Social remark - both client and 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 here and the
+discuss changes while going through the process. CDC is all about communication.
The server
+side code is available here and the
client code here.
Tip In this case, the producer owns the contracts. Physically, all the contract are
in the producer’s repository.
If using the SNAPSHOT / Milestone / Release Candidate versions please add the
following section to your build:
Maven.
diff --git a/1.2.x/multi/multi__spring_cloud_contract_verifier_setup.html b/1.2.x/multi/multi__spring_cloud_contract_verifier_setup.html
index 3d266193d4..7153cbeda4 100644
--- a/1.2.x/multi/multi__spring_cloud_contract_verifier_setup.html
+++ b/1.2.x/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, “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]](images/warning.png)
Warning If you want to use Spock in your projects, you must add separately the
spock-core and spock-spring modules. Check Spock
@@ -206,7 +206,7 @@ WireMock JSON stubs using:
./gradlew generateClie
}
}
LoanApplication makes a call to FraudDetection service. This request is handled by a
WireMock server configured with stubs generated by Spring Cloud Contract Verifier.
To learn how to set up the Maven project for Spring Cloud Contract Verifier, read the
-following sections:
- Section 4.2.1, “Add maven plugin”
- Section 4.2.2, “Maven and Rest Assured 2.0”
- Section 4.2.3, “Snapshot versions for Maven”
- Section 4.2.4, “Add stubs”
- Section 4.2.5, “Run plugin”
- Section 4.2.6, “Configure plugin”
- Section 4.2.7, “Configuration Options”
- Section 4.2.8, “Single Base Class for All Tests”
- Section 4.2.9, “Different base classes for contracts”
- Section 4.2.10, “Invoking generated tests”
- Section 4.2.11, “Maven Plugin and STS”
- Section 4.2.12, “Spring Cloud Contract Verifier on the Consumer Side”
Add the Spring Cloud Contract BOM in a fashion similar to this:
<dependencyManagement>
+following sections:- Section 4.2.1, “Add maven plugin”
- Section 4.2.2, “Maven and Rest Assured 2.0”
- Section 4.2.3, “Snapshot versions for Maven”
- Section 4.2.4, “Add stubs”
- Section 4.2.5, “Run plugin”
- Section 4.2.6, “Configure plugin”
- Section 4.2.7, “Configuration Options”
- Section 4.2.8, “Single Base Class for All Tests”
- Section 4.2.9, “Different base classes for contracts”
- Section 4.2.10, “Invoking generated tests”
- Section 4.2.11, “Maven Plugin and STS”
Add the Spring Cloud Contract BOM in a fashion similar to this:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
@@ -455,7 +455,7 @@ goal.For Groovy Spock code, use the following:
</testSources>
</configuration>
</plugin>
To ensure that provider side is compliant with defined contracts, you need to invoke
-mvn generateTest test.
If you see the following exception while using STS:
When you click on the error marker you should see something like this:
plugin:1.1.0.M1:convert:default-convert:process-test-resources) org.apache.maven.plugin.PluginExecutionException: Execution default-convert of goal org.springframework.cloud:spring-
+mvn generateTest test.
If you see the following exception while using STS:
When you click on the error marker you should see something like this:
plugin:1.1.0.M1:convert:default-convert:process-test-resources) org.apache.maven.plugin.PluginExecutionException: Execution default-convert of goal org.springframework.cloud:spring-
cloud-contract-maven-plugin:1.1.0.M1:convert failed. at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:145) at
org.eclipse.m2e.core.internal.embedder.MavenImpl.execute(MavenImpl.java:331) at org.eclipse.m2e.core.internal.embedder.MavenImpl$11.call(MavenImpl.java:1362) at
...
@@ -492,48 +492,7 @@ goal.For Groovy Spock code, use the following:
</plugin>
</plugins>
</pluginManagement>
-</build>
You can also use the Spring Cloud Contract Verifier for the consumer side. To do so, use
-the plugin so that it only converts the contracts and generates the stubs. To achieve
-that, you need to configure Spring Cloud Contract Verifier plugin in exactly the same way
-as you would for a provider. You need to copy contracts stored in
-src/test/resources/contracts and generate WireMock JSON stubs using the
-mvn generateStubs command. By default, the generated WireMock mapping is stored in a
-directory named target/mappings. From these generated mappings, your project should
-create additional artifacts with a classifier of stubs for easy deployment to the maven
-repository.
Here is a sample configuration:
<plugin>
- <groupId>org.springframework.cloud</groupId>
- <artifactId>spring-cloud-contract-maven-plugin</artifactId>
- <version>${verifier-plugin.version}</version>
- <executions>
- <execution>
- <goals>
- <goal>convert</goal>
- <goal>generateStubs</goal>
- </goals>
- </execution>
- </executions>
-</plugin>
When present, JSON stubs can be used in consumer automated tests, as shown here:
@RunWith(SpringTestRunner.class)
-@SpringBootTest
-@AutoConfigureStubRunner
-public class LoanApplicationServiceTests {
-
- @Autowired
- LoanApplicationService service;
-
- @Test
- public void shouldSuccessfullyApplyForLoan() {
- //given:
- LoanApplication application =
- new LoanApplication(new Client("12345678901"), 123.123);
- //when:
- LoanApplicationResult loanApplication = service.loanApplication(application);
- // then:
- assertThat(loanApplication.loanApplicationStatus).isEqualTo(LoanApplicationStatus.LOAN_APPLIED);
- assertThat(loanApplication.rejectionReason).isNull();
- }
-}
LoanApplication makes a call to the FraudDetection service. This request is handled
-by a WireMock server configured with stubs generated by the Spring Cloud Contract
-Verifier.
The Maven and Gradle plugin that 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:
├── github-webhook-0.0.1.BUILD-20160903.075506-1-stubs.jar
@@ -550,7 +509,14 @@ when you include the github-webhook stubs in anothe
dependency gets downloaded by Stub Runner) then, since all of the dependencies are
optional, they will not get downloaded.Create a separate artifactid for the stubs
If 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.
You can handle scenarios with Spring Cloud Contract Verifier. All you need to do is to
+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 mechanism:
- via
stubrunner.snapshot-check-skip system property - via
STUBRUNNER_SNAPSHOT_CHECK_SKIP environment variable
if either of these values is set to true, then the stub downloader will not
+verify the origin of the downloaded JAR.
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\
@@ -559,10 +525,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 scenario1 and the three following steps:
- login marked as
Started pointing to… - showCart marked as
Step1 pointing to… - logout marked as
Step2 which will close the scenario.
More details about WireMock scenarios can be found at
-http://wiremock.org/stateful-behaviour.html
Spring Cloud Contract Verifier also generates tests with a guaranteed order of execution.
We’re publishing a springcloud/spring-cloud-contract Docker image
+http://wiremock.org/stateful-behaviour.html
Spring Cloud Contract Verifier also generates tests with a guaranteed order of execution.
We’re publishing a springcloud/spring-cloud-contract Docker image
that contains a project that will generate tests and execute them in EXPLICIT mode
against a running application.
Tip The EXPLICIT mode 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,
@@ -589,16 +555,23 @@ 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 /contracts folder.
+or Nexus.
The image searches for contracts under the /contracts folder.
The output from running the tests will be available under
/spring-cloud-contract/build folder (it’s useful for debugging
purposes).
It’s enough for you to mount your contracts, pass the environment variables
and the image will:
- generate the contract tests
- execute the tests against the provided URL
- generate the WireMock stubs
- (optional - turned on by default) publish the stubs to a Artifact Manager
The Docker image requires some environment variables to point to
-your running application, to the Artifact manager instance etc.
PROJECT_GROUP - your project’s group id. Defaults to com.example.PROJECT_VERSION - your project’s version. Defaults to 0.0.1-SNAPSHOTPROJECT_NAME - artifact id. Defaults to exampleREPO_WITH_BINARIES_URL - URL of your Artifact Manager. Defaults to http://localhost:8081/artifactory/libs-release-local
-which is the default URL of Artifactory running locallyREPO_WITH_BINARIES_USERNAME - (optional) username when the Artifact Manager is securedREPO_WITH_BINARIES_PASSWORD - (optional) password when the Artifact Manager is securedPUBLISH_ARTIFACTS - if set to true then will publish artifact to binary storage. Defaults to true.
These environment variables are used when tests are executed:
APPLICATION_BASE_URL - url against which tests should be executed.
+your running application, to the Artifact manager instance etc.PROJECT_GROUP - your project’s group id. Defaults to com.examplePROJECT_VERSION - your project’s version. Defaults to 0.0.1-SNAPSHOTPROJECT_NAME - artifact id. Defaults to exampleREPO_WITH_BINARIES_URL - URL of your Artifact Manager. Defaults to http://localhost:8081/artifactory/libs-release-local
+which is the default URL of Artifactory running locallyREPO_WITH_BINARIES_USERNAME - (optional) username when the Artifact Manager is securedREPO_WITH_BINARIES_PASSWORD - (optional) password when the Artifact Manager is securedPUBLISH_ARTIFACTS - if set to true then will publish artifact to binary storage. Defaults to true.
These environment variables are used when contracts lay in an external repository. To enable
+this feature you must set the EXTERNAL_CONTRACTS_ARTIFACT_ID environment variable.
EXTERNAL_CONTRACTS_GROUP_ID - group id of the project with contracts. Defaults to com.exampleEXTERNAL_CONTRACTS_ARTIFACT_ID- artifact id of the project with contracts.EXTERNAL_CONTRACTS_CLASSIFIER- classifier of the project with contracts. Empty by defaultEXTERNAL_CONTRACTS_VERSION - version of the project with contracts. Defaults to +, equivalent to picking the latestEXTERNAL_CONTRACTS_REPO_WITH_BINARIES_URL - URL of your Artifact Manager. Defaults to value of REPO_WITH_BINARIES_URL env var.
+If that’s not set, defaults to http://localhost:8081/artifactory/libs-release-local
+which is the default URL of Artifactory running locallyEXTERNAL_CONTRACTS_PATH - path to contracts for the given project, inside the project with contracts.
+Defaults to slash separated EXTERNAL_CONTRACTS_GROUP_ID concatenated with / and EXTERNAL_CONTRACTS_ARTIFACT_ID. E.g.
+for group id foo.bar and artifact id baz, would result in foo/bar/baz contracts path.EXTERNAL_CONTRACTS_WORK_OFFLINE - if set to true then will retrieve artifact with contracts
+from the container’s .m2. Mount your local .m2 as a volume available at the container’s /root/.m2 path.
+You must not set both EXTERNAL_CONTRACTS_WORK_OFFLINE and EXTERNAL_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 application
Let’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 /contracts folder.
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 /contracts folder.
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/1.2.x/multi/multi__spring_cloud_contract_wiremock.html b/1.2.x/multi/multi__spring_cloud_contract_wiremock.html
index 4ede2d2731..77939c3d15 100644
--- a/1.2.x/multi/multi__spring_cloud_contract_wiremock.html
+++ b/1.2.x/multi/multi__spring_cloud_contract_wiremock.html
@@ -2,10 +2,10 @@
11. Spring Cloud Contract WireMock The Spring Cloud Contract WireMock modules let you use WireMock in a
Spring Boot application. Check out the
-samples
+samples
for more details.
If you have a Spring Boot application that uses Tomcat as an embedded server (which is
the default with spring-boot-starter-web), you can add
-spring-cloud-contract-wiremock to your classpath and add @AutoConfigureWireMock in
+spring-cloud-starter-contract-stub-runner to your classpath and add @AutoConfigureWireMock in
order to be able to use Wiremock in your tests. Wiremock runs as a stub server and you
can register stub behavior using a Java API or via static JSON declarations as part of
your test. The following code shows an example:
@RunWith(SpringRunner.class)
diff --git a/1.2.x/multi/multi_spring-cloud-contract.html b/1.2.x/multi/multi_spring-cloud-contract.html
index f9f246c198..94bff9a593 100644
--- a/1.2.x/multi/multi_spring-cloud-contract.html
+++ b/1.2.x/multi/multi_spring-cloud-contract.html
@@ -1,3 +1,3 @@
- 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. Can I have multiple base classes for tests?
- 3.7. 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. 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. Maven Plugin and STS
- 4.2.12. Spring Cloud Contract Verifier on the Consumer Side
- 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
- 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
\ No newline at end of file
+ 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. Can I have multiple base classes for tests?
- 3.7. 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. 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. 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
- 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
\ No newline at end of file
diff --git a/1.2.x/single/images/callouts/1.png b/1.2.x/single/images/callouts/1.png
new file mode 100644
index 0000000000..7d473430b7
Binary files /dev/null and b/1.2.x/single/images/callouts/1.png differ
diff --git a/1.2.x/single/images/callouts/2.png b/1.2.x/single/images/callouts/2.png
new file mode 100644
index 0000000000..5d09341b2f
Binary files /dev/null and b/1.2.x/single/images/callouts/2.png differ
diff --git a/1.2.x/single/images/callouts/3.png b/1.2.x/single/images/callouts/3.png
new file mode 100644
index 0000000000..ef7b700471
Binary files /dev/null and b/1.2.x/single/images/callouts/3.png differ
diff --git a/1.2.x/single/spring-cloud-contract.html b/1.2.x/single/spring-cloud-contract.html
index 161e6b1c68..c3ea32daa1 100644
--- a/1.2.x/single/spring-cloud-contract.html
+++ b/1.2.x/single/spring-cloud-contract.html
@@ -1,6 +1,6 @@
- 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. Can I have multiple base classes for tests?
- 3.7. 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. 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. Maven Plugin and STS
- 4.2.12. Spring Cloud Contract Verifier on the Consumer Side
- 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
- 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. Can I have multiple base classes for tests?
- 3.7. 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. 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. 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
- 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
1.2.4.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),
@@ -14,14 +14,14 @@ produced by Spring Cloud Contract Verifier.
- Messaging r
Integration, Spring Cloud Stream, Spring AMQP, and Apache Camel. You can also set your
own integrations.
- Acceptance tests (in JUnit or Spock) are used to verify if server-side implementation
of the API is compliant with the contract (server tests). A full test is generated by
-Spring Cloud Contract Verifier.
Assume that we have a system consisting of multiple microservices:
If we wanted to test the application in top left corner to determine whether it can
+Spring Cloud Contract Verifier.
Assume that we have a system consisting of multiple microservices:
If we wanted to test the application in top left corner 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/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 6 microservices, a couple of databases,
etc.
- 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/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 Verifier with Stub Runner 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.
Spring Cloud Contract Verifier gives you the certainty that the stubs that you use were
+are those that your application directly uses.
Spring Cloud Contract Verifier gives you the certainty that the stubs that you use were
created by the service that you’re calling. Also, if you can use them, it means that they
were tested against the producer’s side. In short, you can trust those stubs.
The main purposes of Spring Cloud Contract Verifier with Stub Runner are:
- To ensure that WireMock/Messaging stubs (used when developing the client) do exactly
what the actual server-side implementation does.
- To promote ATDD method and Microservices architectural style.
- To provide a way to publish changes in contracts that are immediately visible on both
@@ -181,8 +181,8 @@ us. The current implementation of our system grants loans to everybody.
As
sprint, we must develop a new feature: if a client wants to borrow too much money, then
we mark the client as a fraud.
Technical remark - Fraud Detection has an artifact-id of http-server, while Loan
Issuance has an artifact-id of http-client, and both have a group-id of com.example.
Social remark - both client and 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 here and the
+discuss changes while going through the process. CDC is all about communication.
The server
+side code is available here and the
client code here.
Tip In this case, the producer owns the contracts. Physically, all the contract are
in the producer’s repository.
If using the SNAPSHOT / Milestone / Release Candidate versions please add the
following section to your build:
Maven.
@@ -678,15 +678,15 @@ one to one to the contents of the repo.
Example of a <parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
- <version>2.0.0.BUILD-SNAPSHOT</version>
+ <version>1.5.10.RELEASE</version>
<relativePath />
</parent>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<java.version>1.8</java.version>
- <spring-cloud-contract.version>2.0.0.BUILD-SNAPSHOT</spring-cloud-contract.version>
- <spring-cloud-dependencies.version>Finchley.BUILD-SNAPSHOT</spring-cloud-dependencies.version>
+ <spring-cloud-contract.version>1.2.4.BUILD-SNAPSHOT</spring-cloud-contract.version>
+ <spring-cloud-dependencies.version>Edgware.BUILD-SNAPSHOT</spring-cloud-dependencies.version>
<excludeBuildFolders>true</excludeBuildFolders>
</properties>
@@ -843,7 +843,6 @@ of the JAR containing the contracts:
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-contract-maven-plugin</artifactId>
<configuration>
- <stubsMode>REMOTE</stubsMode>
<contractsRepositoryUrl>http://link/to/your/nexus/or/artifactory/or/sth</contractsRepositoryUrl>
<contractDependency>
<groupId>com.example.standalone</groupId>
@@ -863,7 +862,7 @@ to dump all mappings per artifact id. Also the port at which the given stub serv
started will be attached.
Yes! With version 1.1.0 we’ve added such a possibility. On the HTTP stub server side we’re providing support
for this for WireMock. In case of other HTTP server stubs you’ll have to implement the approach yourself.
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, “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-core and spock-spring modules. Check Spock
@@ -1069,7 +1068,7 @@ WireMock JSON stubs using:
./gradlew generateClie
}
}
LoanApplication makes a call to FraudDetection service. This request is handled by a
WireMock server configured with stubs generated by Spring Cloud Contract Verifier.
To learn how to set up the Maven project for Spring Cloud Contract Verifier, read the
-following sections:
- Section 4.2.1, “Add maven plugin”
- Section 4.2.2, “Maven and Rest Assured 2.0”
- Section 4.2.3, “Snapshot versions for Maven”
- Section 4.2.4, “Add stubs”
- Section 4.2.5, “Run plugin”
- Section 4.2.6, “Configure plugin”
- Section 4.2.7, “Configuration Options”
- Section 4.2.8, “Single Base Class for All Tests”
- Section 4.2.9, “Different base classes for contracts”
- Section 4.2.10, “Invoking generated tests”
- Section 4.2.11, “Maven Plugin and STS”
- Section 4.2.12, “Spring Cloud Contract Verifier on the Consumer Side”
Add the Spring Cloud Contract BOM in a fashion similar to this:
<dependencyManagement>
+following sections:- Section 4.2.1, “Add maven plugin”
- Section 4.2.2, “Maven and Rest Assured 2.0”
- Section 4.2.3, “Snapshot versions for Maven”
- Section 4.2.4, “Add stubs”
- Section 4.2.5, “Run plugin”
- Section 4.2.6, “Configure plugin”
- Section 4.2.7, “Configuration Options”
- Section 4.2.8, “Single Base Class for All Tests”
- Section 4.2.9, “Different base classes for contracts”
- Section 4.2.10, “Invoking generated tests”
- Section 4.2.11, “Maven Plugin and STS”
Add the Spring Cloud Contract BOM in a fashion similar to this:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
@@ -1318,7 +1317,7 @@ goal.For Groovy Spock code, use the following:
</testSources>
</configuration>
</plugin>
To ensure that provider side is compliant with defined contracts, you need to invoke
-mvn generateTest test.
If you see the following exception while using STS:
When you click on the error marker you should see something like this:
plugin:1.1.0.M1:convert:default-convert:process-test-resources) org.apache.maven.plugin.PluginExecutionException: Execution default-convert of goal org.springframework.cloud:spring-
+mvn generateTest test.
If you see the following exception while using STS:
When you click on the error marker you should see something like this:
plugin:1.1.0.M1:convert:default-convert:process-test-resources) org.apache.maven.plugin.PluginExecutionException: Execution default-convert of goal org.springframework.cloud:spring-
cloud-contract-maven-plugin:1.1.0.M1:convert failed. at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:145) at
org.eclipse.m2e.core.internal.embedder.MavenImpl.execute(MavenImpl.java:331) at org.eclipse.m2e.core.internal.embedder.MavenImpl$11.call(MavenImpl.java:1362) at
...
@@ -1355,48 +1354,7 @@ goal.For Groovy Spock code, use the following:
</plugin>
</plugins>
</pluginManagement>
-</build>
You can also use the Spring Cloud Contract Verifier for the consumer side. To do so, use
-the plugin so that it only converts the contracts and generates the stubs. To achieve
-that, you need to configure Spring Cloud Contract Verifier plugin in exactly the same way
-as you would for a provider. You need to copy contracts stored in
-src/test/resources/contracts and generate WireMock JSON stubs using the
-mvn generateStubs command. By default, the generated WireMock mapping is stored in a
-directory named target/mappings. From these generated mappings, your project should
-create additional artifacts with a classifier of stubs for easy deployment to the maven
-repository.
Here is a sample configuration:
<plugin>
- <groupId>org.springframework.cloud</groupId>
- <artifactId>spring-cloud-contract-maven-plugin</artifactId>
- <version>${verifier-plugin.version}</version>
- <executions>
- <execution>
- <goals>
- <goal>convert</goal>
- <goal>generateStubs</goal>
- </goals>
- </execution>
- </executions>
-</plugin>
When present, JSON stubs can be used in consumer automated tests, as shown here:
@RunWith(SpringTestRunner.class)
-@SpringBootTest
-@AutoConfigureStubRunner
-public class LoanApplicationServiceTests {
-
- @Autowired
- LoanApplicationService service;
-
- @Test
- public void shouldSuccessfullyApplyForLoan() {
- //given:
- LoanApplication application =
- new LoanApplication(new Client("12345678901"), 123.123);
- //when:
- LoanApplicationResult loanApplication = service.loanApplication(application);
- // then:
- assertThat(loanApplication.loanApplicationStatus).isEqualTo(LoanApplicationStatus.LOAN_APPLIED);
- assertThat(loanApplication.rejectionReason).isNull();
- }
-}
LoanApplication makes a call to the FraudDetection service. This request is handled
-by a WireMock server configured with stubs generated by the Spring Cloud Contract
-Verifier.
The Maven and Gradle plugin that 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:
├── github-webhook-0.0.1.BUILD-20160903.075506-1-stubs.jar
@@ -1413,7 +1371,14 @@ when you include the github-webhook stubs in anothe
dependency gets downloaded by Stub Runner) then, since all of the dependencies are
optional, they will not get downloaded.Create a separate artifactid for the stubs
If 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.
You can handle scenarios with Spring Cloud Contract Verifier. All you need to do is to
+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 mechanism:
- via
stubrunner.snapshot-check-skip system property - via
STUBRUNNER_SNAPSHOT_CHECK_SKIP environment variable
if either of these values is set to true, then the stub downloader will not
+verify the origin of the downloaded JAR.
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\
@@ -1422,10 +1387,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 scenario1 and the three following steps:
- login marked as
Started pointing to… - showCart marked as
Step1 pointing to… - logout marked as
Step2 which will close the scenario.
More details about WireMock scenarios can be found at
-http://wiremock.org/stateful-behaviour.html
Spring Cloud Contract Verifier also generates tests with a guaranteed order of execution.
We’re publishing a springcloud/spring-cloud-contract Docker image
+http://wiremock.org/stateful-behaviour.html
Spring Cloud Contract Verifier also generates tests with a guaranteed order of execution.
We’re publishing a springcloud/spring-cloud-contract Docker image
that contains a project that will generate tests and execute them in EXPLICIT mode
against a running application.
Tip The EXPLICIT mode 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,
@@ -1452,16 +1417,23 @@ 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 /contracts folder.
+or Nexus.
The image searches for contracts under the /contracts folder.
The output from running the tests will be available under
/spring-cloud-contract/build folder (it’s useful for debugging
purposes).
It’s enough for you to mount your contracts, pass the environment variables
and the image will:
- generate the contract tests
- execute the tests against the provided URL
- generate the WireMock stubs
- (optional - turned on by default) publish the stubs to a Artifact Manager
The Docker image requires some environment variables to point to
-your running application, to the Artifact manager instance etc.
PROJECT_GROUP - your project’s group id. Defaults to com.example.PROJECT_VERSION - your project’s version. Defaults to 0.0.1-SNAPSHOTPROJECT_NAME - artifact id. Defaults to exampleREPO_WITH_BINARIES_URL - URL of your Artifact Manager. Defaults to http://localhost:8081/artifactory/libs-release-local
-which is the default URL of Artifactory running locallyREPO_WITH_BINARIES_USERNAME - (optional) username when the Artifact Manager is securedREPO_WITH_BINARIES_PASSWORD - (optional) password when the Artifact Manager is securedPUBLISH_ARTIFACTS - if set to true then will publish artifact to binary storage. Defaults to true.
These environment variables are used when tests are executed:
APPLICATION_BASE_URL - url against which tests should be executed.
+your running application, to the Artifact manager instance etc.PROJECT_GROUP - your project’s group id. Defaults to com.examplePROJECT_VERSION - your project’s version. Defaults to 0.0.1-SNAPSHOTPROJECT_NAME - artifact id. Defaults to exampleREPO_WITH_BINARIES_URL - URL of your Artifact Manager. Defaults to http://localhost:8081/artifactory/libs-release-local
+which is the default URL of Artifactory running locallyREPO_WITH_BINARIES_USERNAME - (optional) username when the Artifact Manager is securedREPO_WITH_BINARIES_PASSWORD - (optional) password when the Artifact Manager is securedPUBLISH_ARTIFACTS - if set to true then will publish artifact to binary storage. Defaults to true.
These environment variables are used when contracts lay in an external repository. To enable
+this feature you must set the EXTERNAL_CONTRACTS_ARTIFACT_ID environment variable.
EXTERNAL_CONTRACTS_GROUP_ID - group id of the project with contracts. Defaults to com.exampleEXTERNAL_CONTRACTS_ARTIFACT_ID- artifact id of the project with contracts.EXTERNAL_CONTRACTS_CLASSIFIER- classifier of the project with contracts. Empty by defaultEXTERNAL_CONTRACTS_VERSION - version of the project with contracts. Defaults to +, equivalent to picking the latestEXTERNAL_CONTRACTS_REPO_WITH_BINARIES_URL - URL of your Artifact Manager. Defaults to value of REPO_WITH_BINARIES_URL env var.
+If that’s not set, defaults to http://localhost:8081/artifactory/libs-release-local
+which is the default URL of Artifactory running locallyEXTERNAL_CONTRACTS_PATH - path to contracts for the given project, inside the project with contracts.
+Defaults to slash separated EXTERNAL_CONTRACTS_GROUP_ID concatenated with / and EXTERNAL_CONTRACTS_ARTIFACT_ID. E.g.
+for group id foo.bar and artifact id baz, would result in foo/bar/baz contracts path.EXTERNAL_CONTRACTS_WORK_OFFLINE - if set to true then will retrieve artifact with contracts
+from the container’s .m2. Mount your local .m2 as a volume available at the container’s /root/.m2 path.
+You must not set both EXTERNAL_CONTRACTS_WORK_OFFLINE and EXTERNAL_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 application
Let’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 /contracts folder.
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 /contracts folder.
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
@@ -2241,10 +2213,12 @@ You can disable Stub Runner Ribbon support by providing: s
You can disable Stub Runner support by providing: stubrunner.cloud.enabled equal to falseTip By default all service discovery will be stubbed. That means that regardless of the fact if you have
an existing DiscoveryClient its results will be ignored. However, if you want to reuse it, just set
stubrunner.cloud.delegate.enabled to true and then your existing DiscoveryClient results will be
- merged with the stubbed ones.
Spring Cloud Contract Stub Runner Boot is a Spring Boot application that exposes REST endpoints to
+ merged with the stubbed ones.
The default Maven configuration used by Stub Runner can be tweaked either
+via the following system properties or environment variables
maven.repo.local - path to the custom maven local repository locationorg.apache.maven.user-settings - path to custom maven user settings locationorg.apache.maven.global-settings - path to maven global settings location
Spring Cloud Contract Stub Runner Boot is a Spring Boot application that exposes REST endpoints to
trigger the messaging labels and to access started WireMock servers.
One of the use-cases is to run some smoke (end to end) tests on a deployed application.
You can check out the Spring Cloud Pipelines
-project for more information.
Just add the
compile "org.springframework.cloud:spring-cloud-starter-stub-runner"Annotate a class with @EnableStubRunnerServer, build a fat-jar and you’re ready to go!
For the properties check the Stub Runner Spring section.
Starting from 1.4.0.RELEASE version of the Spring Cloud CLI
+project for more information.
Just add the
compile "org.springframework.cloud:spring-cloud-starter-stub-runner"Annotate a class with @EnableStubRunnerServer, build a fat-jar and you’re ready to go!
For the properties check the Stub Runner Spring section.
You can download a standalone JAR from Maven (for example, for version 1.2.3.RELEASE), as follows:
$ wget -O stub-runner.jar 'https://search.maven.org/remote_content?g=org.springframework.cloud&a=spring-cloud-contract-stub-runner-boot&v=1.2.3.RELEASE'
+$ java -jar stub-runner.jar --stubrunner.ids=... --stubrunner.repositoryRoot=...Starting from 1.4.0.RELEASE version of the Spring Cloud CLI
project you can start Stub Runner Boot by executing spring cloud stubrunner.
In order to pass the configuration just create a stubrunner.yml file in the current working directory
or a subdirectory called config or in ~/.spring-cloud. The file could look like this
(example for running stubs installed locally)
stubrunner.yml.
@@ -2439,12 +2413,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-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.5, “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.6, “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.5.4, “Server side (nodejs)” step.
+ 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.
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
@@ -5109,10 +5083,10 @@ implementation that downloads stubs from a remote repository is used. If you do
provide these values, the ClasspathStubProvider (which will scan the classpath) is
used. If you provide more than one, then the first one on the list is used.
The Spring Cloud Contract WireMock modules let you use WireMock in a
Spring Boot application. Check out the
-samples
+samples
for more details.
If you have a Spring Boot application that uses Tomcat as an embedded server (which is
the default with spring-boot-starter-web), you can add
-spring-cloud-contract-wiremock to your classpath and add @AutoConfigureWireMock in
+spring-cloud-starter-contract-stub-runner to your classpath and add @AutoConfigureWireMock in
order to be able to use Wiremock in your tests. Wiremock runs as a stub server and you
can register stub behavior using a Java API or via static JSON declarations as part of
your test. The following code shows an example:
@RunWith(SpringRunner.class)
diff --git a/1.2.x/spring-cloud-contract-maven-plugin/checkstyle.html b/1.2.x/spring-cloud-contract-maven-plugin/checkstyle.html
index abbf10a494..0b428fc4be 100644
--- a/1.2.x/spring-cloud-contract-maven-plugin/checkstyle.html
+++ b/1.2.x/spring-cloud-contract-maven-plugin/checkstyle.html
@@ -1,13 +1,13 @@
-
+
Spring Cloud Contract Maven Plugin – Checkstyle Results
@@ -146,7 +146,7 @@