From 66a71e72a4990db709dbe3a6a737b79a7aa27b2b Mon Sep 17 00:00:00 2001 From: Marcin Grzejszczak Date: Wed, 24 Jul 2019 13:58:20 +0200 Subject: [PATCH] WIP: --- README.adoc | 16 +- .../main/asciidoc/_verifier_how_it_works.adoc | 6 +- .../main/asciidoc/_verifier_introduction.adoc | 4 +- docs/src/main/asciidoc/docker-project.adoc | 2 + .../main/asciidoc/documentation-overview.adoc | 73 ++--- docs/src/main/asciidoc/gradle-project.adoc | 26 +- docs/src/main/asciidoc/howto.adoc | 49 ++- docs/src/main/asciidoc/index.htmladoc | 3 +- docs/src/main/asciidoc/maven-project.adoc | 282 +----------------- 9 files changed, 88 insertions(+), 373 deletions(-) diff --git a/README.adoc b/README.adoc index 3bc6dfc1bc..dc5a173a58 100644 --- a/README.adoc +++ b/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! diff --git a/docs/src/main/asciidoc/_verifier_how_it_works.adoc b/docs/src/main/asciidoc/_verifier_how_it_works.adoc index eeff07d9c6..ca5b39e898 100644 --- a/docs/src/main/asciidoc/_verifier_how_it_works.adoc +++ b/docs/src/main/asciidoc/_verifier_how_it_works.adoc @@ -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! \ No newline at end of file diff --git a/docs/src/main/asciidoc/_verifier_introduction.adoc b/docs/src/main/asciidoc/_verifier_introduction.adoc index 466d8ad150..75bf483d32 100644 --- a/docs/src/main/asciidoc/_verifier_introduction.adoc +++ b/docs/src/main/asciidoc/_verifier_introduction.adoc @@ -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 diff --git a/docs/src/main/asciidoc/docker-project.adoc b/docs/src/main/asciidoc/docker-project.adoc index 4eca6a5220..2547579835 100644 --- a/docs/src/main/asciidoc/docker-project.adoc +++ b/docs/src/main/asciidoc/docker-project.adoc @@ -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 <> section. diff --git a/docs/src/main/asciidoc/documentation-overview.adoc b/docs/src/main/asciidoc/documentation-overview.adoc index 81fc6b99bb..05741c891d 100644 --- a/docs/src/main/asciidoc/documentation-overview.adoc +++ b/docs/src/main/asciidoc/documentation-overview.adoc @@ -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}? <>: -* *Build systems:* -<> | -<> | -<> | -<> -* *Best practices:* -<> | -<> | -<> | -<> -* *Running your code:* -<> | -<> | -<> | -<> -* *Packaging your app:* -<> -* *{project-full-name} CLI:* -<<{project-name}-cli.adoc#cli, Using the CLI>> +* *Provider contract testing:* + +** <> +** <> +** <> +** <> +** <> + +* *Consumer-Driven contract testing:* +** <> +** <> +** <> == 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>>: +<>: * *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 -<> that you might like: - -* *Management endpoints:* -<> | -<> -* *Connection options:* -<> | -<> -* *Monitoring:* -<> | -<> | -<> | -<> +* *Build tools:* +link:maven-project.html[Maven] | +link:gradle-project.html[Gradle] | +link:docker-project.html[Docker] diff --git a/docs/src/main/asciidoc/gradle-project.adoc b/docs/src/main/asciidoc/gradle-project.adoc index 8d03c5b3e8..75b89045fa 100644 --- a/docs/src/main/asciidoc/gradle-project.adoc +++ b/docs/src/main/asciidoc/gradle-project.adoc @@ -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' } ---- diff --git a/docs/src/main/asciidoc/howto.adoc b/docs/src/main/asciidoc/howto.adoc index 1e31e36b0f..bea57644cd 100644 --- a/docs/src/main/asciidoc/howto.adoc +++ b/docs/src/main/asciidoc/howto.adoc @@ -1001,4 +1001,51 @@ task convertContracts(type: JavaExec) { test.dependsOn("convertContracts") ---- -==== \ No newline at end of file +==== + +[[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. \ No newline at end of file diff --git a/docs/src/main/asciidoc/index.htmladoc b/docs/src/main/asciidoc/index.htmladoc index 8e7c3bcbd1..cc009df9f7 100644 --- a/docs/src/main/asciidoc/index.htmladoc +++ b/docs/src/main/asciidoc/index.htmladoc @@ -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 information. <> :: About the Documentation, Getting Help, First Steps, and more. <> :: Introducing {project-full-name}, System Requirements, Developing Your First {project-full-name} based Application -<> :: Build Systems, Structuring Your Code, Configuration, Spring Beans and Dependency Injection, and more. +<> :: {project-full-name} usage examples and workflows <> :: Profiles, Logging, Security, Caching, Spring Integration, Testing, and more. <> :: Monitoring, Metrics, Auditing, and more. <> :: Maven Plugin, Gradle Plugin. diff --git a/docs/src/main/asciidoc/maven-project.adoc b/docs/src/main/asciidoc/maven-project.adoc index 5b21e7c4ad..ffc5e36735 100644 --- a/docs/src/main/asciidoc/maven-project.adoc +++ b/docs/src/main/asciidoc/maven-project.adoc @@ -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 <> section. +---- \ No newline at end of file