WIP:
This commit is contained in:
Marcin Grzejszczak
16
README.adoc
16
README.adoc
@@ -59,7 +59,7 @@ The `0.1.0` release took place on 26 Jan 2015 and it became stable with `1.0.0`
|
||||
|
||||
Assume that we have a system consisting of multiple microservices:
|
||||
|
||||
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/{branch}/docs/src/main/asciidoc/images/Deps.png[Microservices Architecture]
|
||||
image::{github-raw}/docs/src/main/asciidoc/images/Deps.png[Microservices Architecture]
|
||||
|
||||
==== Testing issues
|
||||
|
||||
@@ -106,7 +106,7 @@ To solve the aforementioned issues, Spring Cloud Contract was created. The main
|
||||
whole world of microservices. If you work on stubs, then the only applications you need
|
||||
are those that your application directly uses.
|
||||
|
||||
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/{branch}/docs/src/main/asciidoc/images/Stubs2.png[Stubbed Services]
|
||||
image::{github-raw}/docs/src/main/asciidoc/images/Stubs2.png[Stubbed Services]
|
||||
|
||||
Spring Cloud Contract 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
|
||||
@@ -243,9 +243,7 @@ Stub Runner` properties, as shown in the following example:
|
||||
+
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
stubrunner:
|
||||
ids: 'com.example:http-server-dsl:+:stubs:8080'
|
||||
repositoryRoot: https://repo.spring.io/libs-snapshot
|
||||
Unresolved directive in _verifier_how_it_works.adoc - include::{github-raw}/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[]
|
||||
----
|
||||
|
||||
Now you can annotate your test class with `@AutoConfigureStubRunner`. In the annotation,
|
||||
@@ -552,9 +550,7 @@ Runner` properties, as shown in the following example:
|
||||
+
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
stubrunner:
|
||||
ids: 'com.example:http-server-dsl:+:stubs:8080'
|
||||
repositoryRoot: https://repo.spring.io/libs-snapshot
|
||||
Unresolved directive in _verifier_how_it_works.adoc - include::{github-raw}/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[]
|
||||
----
|
||||
|
||||
Now you can annotate your test class with `@AutoConfigureStubRunner`. In the annotation,
|
||||
@@ -1083,9 +1079,7 @@ achieving the same thing by changing the properties.
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
stubrunner:
|
||||
ids: 'com.example:http-server-dsl:+:stubs:8080'
|
||||
repositoryRoot: https://repo.spring.io/libs-snapshot
|
||||
Unresolved directive in _verifier_how_it_works.adoc - include::{github-raw}/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[]
|
||||
----
|
||||
|
||||
That's it!
|
||||
|
||||
@@ -110,7 +110,7 @@ Stub Runner` properties, as shown in the following example:
|
||||
+
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/{branch}/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[]
|
||||
include::{github-raw}/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[]
|
||||
----
|
||||
|
||||
Now you can annotate your test class with `@AutoConfigureStubRunner`. In the annotation,
|
||||
@@ -417,7 +417,7 @@ Runner` properties, as shown in the following example:
|
||||
+
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/{branch}/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[]
|
||||
include::{github-raw}/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[]
|
||||
----
|
||||
|
||||
Now you can annotate your test class with `@AutoConfigureStubRunner`. In the annotation,
|
||||
@@ -946,7 +946,7 @@ achieving the same thing by changing the properties.
|
||||
|
||||
[source,yaml,indent=0]
|
||||
----
|
||||
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/{branch}/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[]
|
||||
include::{github-raw}/samples/standalone/dsl/http-client/src/test/resources/application-test-repo.yaml[]
|
||||
----
|
||||
|
||||
That's it!
|
||||
@@ -14,7 +14,7 @@ The `0.1.0` release took place on 26 Jan 2015 and it became stable with `1.0.0`
|
||||
|
||||
Assume that we have a system consisting of multiple microservices:
|
||||
|
||||
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/{branch}/docs/src/main/asciidoc/images/Deps.png[Microservices Architecture]
|
||||
image::{github-raw}/docs/src/main/asciidoc/images/Deps.png[Microservices Architecture]
|
||||
|
||||
==== Testing issues
|
||||
|
||||
@@ -61,7 +61,7 @@ To solve the aforementioned issues, Spring Cloud Contract was created. The main
|
||||
whole world of microservices. If you work on stubs, then the only applications you need
|
||||
are those that your application directly uses.
|
||||
|
||||
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/{branch}/docs/src/main/asciidoc/images/Stubs2.png[Stubbed Services]
|
||||
image::{github-raw}/docs/src/main/asciidoc/images/Stubs2.png[Stubbed Services]
|
||||
|
||||
Spring Cloud Contract 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
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
= Docker Project
|
||||
include::_attributes.adoc[]
|
||||
|
||||
We're publishing a `springcloud/spring-cloud-contract` Docker image
|
||||
that contains a project that will generate tests and execute them in `EXPLICIT` mode
|
||||
@@ -177,4 +178,5 @@ will be executed against the running application
|
||||
under http://localhost:8081/artifactory/libs-release-local/com/example/bookstore/0.0.1.RELEASE/ .
|
||||
The stubs will be here http://localhost:8081/artifactory/libs-release-local/com/example/bookstore/0.0.1.RELEASE/bookstore-0.0.1.RELEASE-stubs.jar.
|
||||
|
||||
// TODO: Fix the link
|
||||
To see how the client side looks like check out the <<stubrunner-docker>> section.
|
||||
|
||||
@@ -60,73 +60,34 @@ If you are getting started with {project-full-name} or 'Spring' in general, star
|
||||
Ready to actually start using {project-full-name}? <<using.adoc#using, We have
|
||||
you covered>>:
|
||||
|
||||
* *Build systems:*
|
||||
<<using-{project-name}.adoc#using-contract-maven, Maven>> |
|
||||
<<using-{project-name}.adoc#using-contract-gradle, Gradle>> |
|
||||
<<using-{project-name}.adoc#using-contract-ant, Ant>> |
|
||||
<<using-{project-name}.adoc#using-contract-starter, Starters>>
|
||||
* *Best practices:*
|
||||
<<using-{project-name}.adoc#using-contract-structuring-your-code, Code Structure>> |
|
||||
<<using-{project-name}.adoc#using-contract-configuration-classes, @Configuration>> |
|
||||
<<using-{project-name}.adoc#using-contract-auto-configuration, @EnableAutoConfiguration>> |
|
||||
<<using-{project-name}.adoc#using-contract-spring-beans-and-dependency-injection, Beans and
|
||||
Dependency Injection>>
|
||||
* *Running your code:*
|
||||
<<using-{project-name}.adoc#using-contract-running-from-an-ide, IDE>> |
|
||||
<<using-{project-name}.adoc#using-contract-running-as-a-packaged-application, Packaged>> |
|
||||
<<using-{project-name}.adoc#using-contract-running-with-the-maven-plugin, Maven>> |
|
||||
<<using-{project-name}.adoc#using-contract-running-with-the-gradle-plugin, Gradle>>
|
||||
* *Packaging your app:*
|
||||
<<using-{project-name}.adoc#using-contract-packaging-for-production, Production jars>>
|
||||
* *{project-full-name} CLI:*
|
||||
<<{project-name}-cli.adoc#cli, Using the CLI>>
|
||||
* *Provider contract testing:*
|
||||
|
||||
** <<using.adoc#flows-provider-nexus,Provider contract testing with stubs in Nexus / Artifactory>>
|
||||
** <<using.adoc#flows-provider-git,Provider contract testing with stubs in Git>>
|
||||
** <<using.adoc#flows-provider-non-spring,Provider contract testing with stubs in Artifactory for a non Spring application>>
|
||||
** <<using.adoc#flows-provider-non-jvm,Provider contract testing with stubs in Artifactory in non JVM world>>
|
||||
** <<using.adoc#flows-provider-rest-docs,Provider contract testing with REST Docs and stubs in Nexus / Artifactory>>
|
||||
|
||||
* *Consumer-Driven contract testing:*
|
||||
** <<using.adoc#flows-cdc-contracts-producer,Consumer Driven Contracts with contracts on the producer side>>
|
||||
** <<using.adoc#flows-cdc-contracts-external,Consumer Driven Contracts with contracts in external repo>>
|
||||
** <<using.adoc#flows-cdc-contracts-stubs-git,Consumer Driven Contracts with contracts on the producer side, pushed to git>>
|
||||
|
||||
|
||||
|
||||
== Learning about {project-full-name} Features
|
||||
Need more details about {project-full-name}'s core features?
|
||||
<<{project-name}-features.adoc#contract-features, The following content is for you>>:
|
||||
<<project-features.adoc#features, The following content is for you>>:
|
||||
|
||||
* *Core Features:*
|
||||
<<{project-name}-features.adoc#contract-features-spring-application, SpringApplication>> |
|
||||
<<{project-name}-features.adoc#contract-features-external-config, External Configuration>> |
|
||||
<<{project-name}-features.adoc#contract-features-profiles, Profiles>> |
|
||||
<<{project-name}-features.adoc#contract-features-logging, Logging>>
|
||||
* *Web Applications:*
|
||||
<<{project-name}-features.adoc#contract-features-spring-mvc, MVC>> |
|
||||
<<{project-name}-features.adoc#contract-features-embedded-container, Embedded Containers>>
|
||||
* *Working with data:*
|
||||
<<{project-name}-features.adoc#contract-features-sql, SQL>> |
|
||||
<<{project-name}-features.adoc#contract-features-nosql, NO-SQL>>
|
||||
* *Messaging:*
|
||||
<<{project-name}-features.adoc#contract-features-messaging, Overview>> |
|
||||
<<{project-name}-features.adoc#contract-features-jms, JMS>>
|
||||
* *Testing:*
|
||||
<<{project-name}-features.adoc#contract-features-testing, Overview>> |
|
||||
<<{project-name}-features.adoc#contract-features-testing-{project-name}-applications, Boot
|
||||
Applications>> |
|
||||
<<{project-name}-features.adoc#contract-features-test-utilities, Utils>>
|
||||
* *Extending:*
|
||||
<<{project-name}-features.adoc#contract-features-developing-auto-configuration, Auto-configuration>> |
|
||||
<<{project-name}-features.adoc#contract-features-condition-annotations, @Conditions>>
|
||||
|
||||
|
||||
|
||||
== Moving to Production
|
||||
When you are ready to push your {project-full-name} application to production, we have
|
||||
<<production-ready-features.adoc#production-ready, some tricks>> that you might like:
|
||||
|
||||
* *Management endpoints:*
|
||||
<<production-ready-features.adoc#production-ready-endpoints, Overview>> |
|
||||
<<production-ready-features.adoc#production-ready-customizing-endpoints, Customization>>
|
||||
* *Connection options:*
|
||||
<<production-ready-features.adoc#production-ready-monitoring, HTTP>> |
|
||||
<<production-ready-features.adoc#production-ready-jmx, JMX>>
|
||||
* *Monitoring:*
|
||||
<<production-ready-features.adoc#production-ready-metrics, Metrics>> |
|
||||
<<production-ready-features.adoc#production-ready-auditing, Auditing>> |
|
||||
<<production-ready-features.adoc#production-ready-tracing, Tracing>> |
|
||||
<<production-ready-features.adoc#production-ready-process-monitoring, Process>>
|
||||
* *Build tools:*
|
||||
link:maven-project.html[Maven] |
|
||||
link:gradle-project.html[Gradle] |
|
||||
link:docker-project.html[Docker]
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,23 +1,5 @@
|
||||
:branch: master
|
||||
:core_path: ../../..
|
||||
:plugins_path: ../../../spring-cloud-contract-tools
|
||||
:converters_path: {plugins_path}/spring-cloud-contract-converters
|
||||
:verifier_root_path: {core_path}/spring-cloud-contract-verifier
|
||||
:contract_spec_path: {core_path}/specs/spring-cloud-contract-spec-java
|
||||
:contract_spec_tests_path: {core_path}/specs/spring-cloud-contract-spec
|
||||
:samples_path: {core_path}/samples
|
||||
:verifier_core_path: {verifier_root_path}
|
||||
:stubrunner_core_path: {core_path}/spring-cloud-contract-stub-runner
|
||||
:standalone_samples_path: {samples_path}/standalone/dsl
|
||||
:standalone_messaging_samples_path: {samples_path}/standalone/messaging
|
||||
:standalone_pact_path: {samples_path}/standalone/pact
|
||||
:standalone_restdocs_path: {samples_path}/standalone/restdocs
|
||||
:tests_path: {core_path}/tests
|
||||
:samples_branch: 2.2.x
|
||||
:samples_url: https://raw.githubusercontent.com/spring-cloud-samples/spring-cloud-contract-samples/{samples_branch}
|
||||
:introduction_url: ${core_path}/../../
|
||||
|
||||
= Gradle Project
|
||||
include::_attributes.adoc[]
|
||||
|
||||
To learn how to set up the Gradle project for Spring Cloud Contract Verifier, read the
|
||||
following sections:
|
||||
@@ -73,10 +55,10 @@ dependencyManagement {
|
||||
}
|
||||
|
||||
dependencies {
|
||||
testCompile 'org.codehaus.groovy:groovy-all:2.4.6'
|
||||
testCompile "org.codehaus.groovy:groovy-all:${groovyVersion}"
|
||||
// example with adding Spock core and Spock Spring
|
||||
testCompile 'org.spockframework:spock-core:1.0-groovy-2.4'
|
||||
testCompile 'org.spockframework:spock-spring:1.0-groovy-2.4'
|
||||
testCompile "org.spockframework:spock-core:${spockVersion}"
|
||||
testCompile "org.spockframework:spock-spring:${spockVersion}"
|
||||
testCompile 'org.springframework.cloud:spring-cloud-starter-contract-verifier'
|
||||
}
|
||||
----
|
||||
|
||||
@@ -1001,4 +1001,51 @@ task convertContracts(type: JavaExec) {
|
||||
|
||||
test.dependsOn("convertContracts")
|
||||
----
|
||||
====
|
||||
====
|
||||
|
||||
[[how-to-work-with-transitivie]]
|
||||
== How can I work with transitive dependencies?
|
||||
|
||||
The Spring Cloud Contract plugins add the tasks that create the stubs jar for you. One
|
||||
problem that arises is that, when reusing the stubs, you can mistakenly import all of
|
||||
that stub's dependencies. When building a Maven artifact, even though you have a couple
|
||||
of different jars, all of them share one pom:
|
||||
|
||||
[source,bash,indent=0]
|
||||
----
|
||||
├── producer-0.0.1.BUILD-20160903.075506-1-stubs.jar
|
||||
├── producer-0.0.1.BUILD-20160903.075506-1-stubs.jar.sha1
|
||||
├── producer-0.0.1.BUILD-20160903.075655-2-stubs.jar
|
||||
├── producer-0.0.1.BUILD-20160903.075655-2-stubs.jar.sha1
|
||||
├── producer-0.0.1.BUILD-SNAPSHOT.jar
|
||||
├── producer-0.0.1.BUILD-SNAPSHOT.pom
|
||||
├── producer-0.0.1.BUILD-SNAPSHOT-stubs.jar
|
||||
├── ...
|
||||
└── ...
|
||||
----
|
||||
|
||||
There are three possibilities of working with those dependencies so as not to have any
|
||||
issues with transitive dependencies:
|
||||
|
||||
* Mark all application dependencies as optional
|
||||
* Create a separate artifactid for the stubs
|
||||
* Exclude dependencies on the consumer side
|
||||
|
||||
[[how-to-work-with-transitivie-optional]]
|
||||
=== Mark all application dependencies as optional
|
||||
|
||||
If, in the `producer` application, you mark all of your dependencies as optional,
|
||||
when you include the `producer` stubs in another application (or when that
|
||||
dependency gets downloaded by Stub Runner) then, since all of the dependencies are
|
||||
optional, they will not get downloaded.
|
||||
|
||||
[[how-to-work-with-transitivie-separate]]
|
||||
=== 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.
|
||||
|
||||
[[how-to-work-with-transitivie-exclude]]
|
||||
=== 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.
|
||||
@@ -2,6 +2,7 @@
|
||||
= Spring Cloud Contract Reference Documentation
|
||||
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
|
||||
:docinfo: shared
|
||||
include::_attributes.adoc[]
|
||||
|
||||
The reference documentation consists of the following sections:
|
||||
|
||||
@@ -9,7 +10,7 @@ The reference documentation consists of the following sections:
|
||||
<<legal.adoc#legal-information,Legal>> :: Legal information.
|
||||
<<documentation-overview.adoc#contract-documentation,Documentation Overview>> :: About the Documentation, Getting Help, First Steps, and more.
|
||||
<<getting-started.adoc#getting-started,Getting Started>> :: Introducing {project-full-name}, System Requirements, Developing Your First {project-full-name} based Application
|
||||
<<using.adoc#using,Using {project-full-name}>> :: Build Systems, Structuring Your Code, Configuration, Spring Beans and Dependency Injection, and more.
|
||||
<<using.adoc#using,Using {project-full-name}>> :: {project-full-name} usage examples and workflows
|
||||
<<project-features.adoc#features,{project-full-name} Features>> :: Profiles, Logging, Security, Caching, Spring Integration, Testing, and more.
|
||||
<<production-ready-features.adoc#production-ready,Spring Boot Actuator>> :: Monitoring, Metrics, Auditing, and more.
|
||||
<<build-tool-plugins.adoc#build-tool-plugins,Build Tool Plugins>> :: Maven Plugin, Gradle Plugin.
|
||||
|
||||
@@ -1,23 +1,5 @@
|
||||
:branch: master
|
||||
:core_path: ../../..
|
||||
:plugins_path: ../../../spring-cloud-contract-tools
|
||||
:converters_path: {plugins_path}/spring-cloud-contract-converters
|
||||
:verifier_root_path: {core_path}/spring-cloud-contract-verifier
|
||||
:contract_spec_path: {core_path}/specs/spring-cloud-contract-spec-java
|
||||
:contract_spec_tests_path: {core_path}/specs/spring-cloud-contract-spec
|
||||
:samples_path: {core_path}/samples
|
||||
:verifier_core_path: {verifier_root_path}
|
||||
:stubrunner_core_path: {core_path}/spring-cloud-contract-stub-runner
|
||||
:standalone_samples_path: {samples_path}/standalone/dsl
|
||||
:standalone_messaging_samples_path: {samples_path}/standalone/messaging
|
||||
:standalone_pact_path: {samples_path}/standalone/pact
|
||||
:standalone_restdocs_path: {samples_path}/standalone/restdocs
|
||||
:tests_path: {core_path}/tests
|
||||
:samples_branch: 2.2.x
|
||||
:samples_url: https://raw.githubusercontent.com/spring-cloud-samples/spring-cloud-contract-samples/{samples_branch}
|
||||
:introduction_url: ${core_path}/../../
|
||||
|
||||
= Maven Project
|
||||
include::_attributes.adoc[]
|
||||
|
||||
To learn how to set up the Maven project for Spring Cloud Contract Verifier, read the
|
||||
following sections:
|
||||
@@ -53,8 +35,8 @@ include::{standalone_samples_path}/http-server/pom.xml[tags=contract_maven_plugi
|
||||
----
|
||||
|
||||
You can read more in the
|
||||
https://cloud.spring.io/spring-cloud-static/spring-cloud-contract/2.0.0.RELEASE/spring-cloud-contract-maven-plugin/[Spring
|
||||
Cloud Contract Maven Plugin Documentation (example for `2.0.0.RELEASE` version)].
|
||||
spring-cloud-contract-maven-plugin/index.html[Spring
|
||||
Cloud Contract Maven Plugin Documentation.
|
||||
|
||||
[[maven-rest-assured]]
|
||||
== Maven and Rest Assured 2.0
|
||||
@@ -469,7 +451,7 @@ or an environment variable.
|
||||
|
||||
If you see the following exception while using STS:
|
||||
|
||||
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/{branch}/docs/src/main/asciidoc/images/sts_exception.png[STS Exception]
|
||||
image::{github-raw}/docs/src/main/asciidoc/images/sts_exception.png[STS Exception]
|
||||
|
||||
When you click on the error marker you should see something like this:
|
||||
|
||||
@@ -544,258 +526,4 @@ Surefire plugin setup, like in the following example:
|
||||
[source,xml,indent=0]
|
||||
----
|
||||
include::{samples_url}/producer_with_spock/pom.xml[tags=spock-surefire-setup,indent=0]
|
||||
----
|
||||
|
||||
= Stubs and Transitive Dependencies
|
||||
|
||||
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:
|
||||
|
||||
[source,bash,indent=0]
|
||||
----
|
||||
├── github-webhook-0.0.1.BUILD-20160903.075506-1-stubs.jar
|
||||
├── github-webhook-0.0.1.BUILD-20160903.075506-1-stubs.jar.sha1
|
||||
├── github-webhook-0.0.1.BUILD-20160903.075655-2-stubs.jar
|
||||
├── github-webhook-0.0.1.BUILD-20160903.075655-2-stubs.jar.sha1
|
||||
├── github-webhook-0.0.1.BUILD-SNAPSHOT.jar
|
||||
├── github-webhook-0.0.1.BUILD-SNAPSHOT.pom
|
||||
├── github-webhook-0.0.1.BUILD-SNAPSHOT-stubs.jar
|
||||
├── ...
|
||||
└── ...
|
||||
----
|
||||
|
||||
There are three possibilities of working with those dependencies so as not to have any
|
||||
issues with transitive dependencies:
|
||||
|
||||
* Mark all application dependencies as optional
|
||||
* Create a separate artifactid for the stubs
|
||||
* Exclude dependencies on the consumer side
|
||||
|
||||
*Mark all application dependencies as optional*
|
||||
|
||||
If, in the `github-webhook` application, you mark all of your dependencies as optional,
|
||||
when you include the `github-webhook` stubs in another application (or when that
|
||||
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.
|
||||
|
||||
= Scenarios
|
||||
|
||||
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:
|
||||
|
||||
[source,indent=0]
|
||||
----
|
||||
my_contracts_dir\
|
||||
scenario1\
|
||||
1_login.groovy
|
||||
2_showCart.groovy
|
||||
3_logout.groovy
|
||||
----
|
||||
|
||||
Such a tree causes Spring Cloud Contract Verifier to generate WireMock's scenario with a
|
||||
name of `scenario1` and the three following steps:
|
||||
|
||||
. login marked as `Started` pointing to...
|
||||
. showCart marked as `Step1` pointing to...
|
||||
. logout marked as `Step2` which will close the scenario.
|
||||
|
||||
More details about WireMock scenarios can be found at
|
||||
https://wiremock.org/docs/stateful-behaviour/[https://wiremock.org/docs/stateful-behaviour/]
|
||||
|
||||
Spring Cloud Contract Verifier also generates tests with a guaranteed order of execution.
|
||||
|
||||
[[docker-project]]
|
||||
= Docker Project
|
||||
|
||||
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.
|
||||
|
||||
== Short intro to Maven, JARs and Binary storage
|
||||
|
||||
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 https://maven.apache.org/glossary.html[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,
|
||||
in which case the latter are called “dependencies”. A project may
|
||||
consistent of several subprojects, however these subprojects are still
|
||||
treated equally as projects.
|
||||
- `Artifact`: An artifact is something that is either produced or used
|
||||
by a project. Examples of artifacts produced by Maven for a project
|
||||
include: JARs, source and binary distributions. Each artifact
|
||||
is uniquely identified by a group id and an artifact ID which is
|
||||
unique within a group.
|
||||
- `JAR`: JAR stands for Java ARchive. It's a format based on
|
||||
the ZIP file format. Spring Cloud Contract packages the contracts and generated
|
||||
stubs in a JAR file.
|
||||
- `GroupId`: A group ID is a universally unique identifier for a project.
|
||||
While this is often just the project name (eg. commons-collections),
|
||||
it is helpful to use a fully-qualified package name to distinguish it
|
||||
from other projects with a similar name (eg. org.apache.maven).
|
||||
Typically, when published to the Artifact Manager, the `GroupId` will get
|
||||
slash separated and form part of the URL. E.g. for group id `com.example`
|
||||
and artifact id `application` would be `/com/example/application/`.
|
||||
- `Classifier`: The Maven dependency notation looks as follows:
|
||||
`groupId:artifactId:version:classifier`. The classifier is additional suffix
|
||||
passed to the dependency. E.g. `stubs`, `sources`. The same dependency
|
||||
e.g. `com.example:application` can produce multiple artifacts that
|
||||
differ from each other with the classifier.
|
||||
- `Artifact manager`: When you generate binaries / sources / packages, you would
|
||||
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 https://jfrog.com/artifactory/[Artifactory]
|
||||
or https://www.sonatype.org/nexus/[Nexus].
|
||||
|
||||
== How it works
|
||||
|
||||
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 https://github.com/tomakehurst/wiremock[WireMock] stubs
|
||||
- (optional - turned on by default) publish the stubs to a Artifact Manager
|
||||
|
||||
=== Environment Variables
|
||||
|
||||
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-SNAPSHOT`
|
||||
- `PROJECT_NAME` - artifact id. Defaults to `example`
|
||||
- `PRODUCER_STUBS_CLASSIFIER` - archive classifier used for generated producer stubs, defaults to `stubs`.
|
||||
- `REPO_WITH_BINARIES_URL` - URL of your Artifact Manager. Defaults to `http://localhost:8081/artifactory/libs-release-local`
|
||||
which is the default URL of https://jfrog.com/artifactory/[Artifactory] running locally
|
||||
- `REPO_WITH_BINARIES_USERNAME` - (optional) username when the Artifact Manager is secured, defaults to `admin`.
|
||||
- `REPO_WITH_BINARIES_PASSWORD` - (optional) password when the Artifact Manager is secured, defaults to `password`.
|
||||
- `PUBLISH_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.example`
|
||||
- `EXTERNAL_CONTRACTS_ARTIFACT_ID`- artifact id of the project with contracts.
|
||||
- `EXTERNAL_CONTRACTS_CLASSIFIER`- classifier of the project with contracts. Empty by default
|
||||
- `EXTERNAL_CONTRACTS_VERSION` - version of the project with contracts. Defaults to `+`, equivalent to picking the latest
|
||||
- `EXTERNAL_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 https://jfrog.com/artifactory/[Artifactory] running locally
|
||||
- `EXTERNAL_CONTRACTS_REPO_WITH_BINARIES_USERNAME` - (optional) username if the `EXTERNAL_CONTRACTS_REPO_WITH_BINARIES_URL`
|
||||
requires authentication, defaults to `REPO_WITH_BINARIES_USERNAME`. If that's not set defaults to `admin`.
|
||||
- `EXTERNAL_CONTRACTS_REPO_WITH_BINARIES_PASSWORD` - (optional) password if the `EXTERNAL_CONTRACTS_REPO_WITH_BINARIES_URL`
|
||||
requires authentication, defaults to `REPO_WITH_BINARIES_PASSWORD`. If that's not set defaults to `password`.
|
||||
- `EXTERNAL_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 application
|
||||
- `APPLICATION_PASSWORD` - (optional) password for basic authentication to your application
|
||||
|
||||
== Example of usage
|
||||
|
||||
Let's take a look at a simple MVC application
|
||||
|
||||
```bash
|
||||
$ git clone https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs
|
||||
$ cd bookstore
|
||||
```
|
||||
|
||||
The contracts are available under `/contracts` folder.
|
||||
|
||||
[[docker-server-side]]
|
||||
== Server side (nodejs)
|
||||
|
||||
Since we want to run tests, we could just execute:
|
||||
|
||||
```bash
|
||||
$ npm test
|
||||
```
|
||||
|
||||
however, for learning purposes, let's split it into pieces:
|
||||
|
||||
```bash
|
||||
# Stop docker infra (nodejs, artifactory)
|
||||
$ ./stop_infra.sh
|
||||
# Start docker infra (nodejs, artifactory)
|
||||
$ ./setup_infra.sh
|
||||
|
||||
# Kill & Run app
|
||||
$ pkill -f "node app"
|
||||
$ nohup node app &
|
||||
|
||||
# Prepare environment variables
|
||||
$ SC_CONTRACT_DOCKER_VERSION="..."
|
||||
$ APP_IP="192.168.0.100"
|
||||
$ APP_PORT="3000"
|
||||
$ ARTIFACTORY_PORT="8081"
|
||||
$ APPLICATION_BASE_URL="http://${APP_IP}:${APP_PORT}"
|
||||
$ ARTIFACTORY_URL="http://${APP_IP}:${ARTIFACTORY_PORT}/artifactory/libs-release-local"
|
||||
$ CURRENT_DIR="$( pwd )"
|
||||
$ CURRENT_FOLDER_NAME=${PWD##*/}
|
||||
$ PROJECT_VERSION="0.0.1.RELEASE"
|
||||
|
||||
# Execute contract tests
|
||||
$ docker run --rm -e "APPLICATION_BASE_URL=${APPLICATION_BASE_URL}" -e "PUBLISH_ARTIFACTS=true" -e "PROJECT_NAME=${CURRENT_FOLDER_NAME}" -e "REPO_WITH_BINARIES_URL=${ARTIFACTORY_URL}" -e "PROJECT_VERSION=${PROJECT_VERSION}" -v "${CURRENT_DIR}/contracts/:/contracts:ro" -v "${CURRENT_DIR}/node_modules/spring-cloud-contract/output:/spring-cloud-contract-output/" springcloud/spring-cloud-contract:"${SC_CONTRACT_DOCKER_VERSION}"
|
||||
|
||||
# Kill app
|
||||
$ pkill -f "node app"
|
||||
```
|
||||
|
||||
What will happen is that via bash scripts:
|
||||
|
||||
- infrastructure will be set up (MongoDb, Artifactory).
|
||||
In real life scenario you would just run the NodeJS application
|
||||
with mocked database. In this example we want to show how we can
|
||||
benefit from Spring Cloud Contract in no time.
|
||||
- due to those constraints the contracts also represent the
|
||||
stateful situation
|
||||
** first request is a `POST` that causes data to get inserted to the database
|
||||
** second request is a `GET` that returns a list of data with 1 previously inserted element
|
||||
- the NodeJS application will be started (on port `3000`)
|
||||
- contract tests will be generated via Docker and tests
|
||||
will be executed against the running application
|
||||
** the contracts will be taken from `/contracts` folder.
|
||||
** the output of the test execution is available under
|
||||
`node_modules/spring-cloud-contract/output`.
|
||||
- the stubs will be uploaded to Artifactory. You can check them out
|
||||
under http://localhost:8081/artifactory/libs-release-local/com/example/bookstore/0.0.1.RELEASE/ .
|
||||
The stubs will be here http://localhost:8081/artifactory/libs-release-local/com/example/bookstore/0.0.1.RELEASE/bookstore-0.0.1.RELEASE-stubs.jar.
|
||||
|
||||
To see how the client side looks like check out the <<stubrunner-docker>> section.
|
||||
----
|
||||
Reference in New Issue
Block a user