SpringCloud/spring-cloud-contract
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Rebranding (#287)

Browse Source
This commit is contained in:
Marcin Grzejszczak
2016-06-19 23:55:09 +02:00
committed by GitHub
parent a562775980
commit 817c232d3f
747 changed files with 13363 additions and 6399 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/build.gradle
View File

@@ -1,14 +1,53 @@
/*
* Copyright 2013-2016 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
plugins {
id 'org.ajoberstar.github-pages' version '1.1.0'
id 'org.asciidoctor.gradle.asciidoctor' version '1.5.1'
id 'org.asciidoctor.convert' version '1.5.3'
id 'com.github.jruby-gradle.base' version '1.2.1'
}
apply plugin: 'org.asciidoctor.gradle.asciidoctor'
apply plugin: 'com.github.jruby-gradle.base'
dependencies {
gems group: 'rubygems', name: 'asciidoctor', version: '1.5.3'
}
asciidoctorj {
version = '1.5.4'
}
task generateReadme(type: com.github.jrubygradle.JRubyExec) {
dependsOn jrubyPrepare
description "Generates an output README.adoc"
script "${projectDir}/src/main/ruby/generate_readme.sh"
scriptArgs "-o${new File(project.rootDir, 'README.adoc')}"
gemWorkDir jrubyPrepare.outputDir
}
asciidoctor {
dependsOn jrubyPrepare
sourceDir 'src/main/asciidoc'
setSourceDocumentName file('spring-cloud-contract-verifier.adoc')
backends 'html'
attributes 'build-gradle': file('build.gradle'),
'endpoint-url': 'https://Codearte.github.io/accurest',
'source-highlighter': 'coderay',
@@ -18,9 +57,13 @@ asciidoctor {
'setanchors': 'true',
'idprefix': '',
'idseparator': '-',
'docinfo1': 'true'
'docinfo1': 'true',
'doctype' : 'article'
gemPath = jrubyPrepare.outputDir
}
generateReadme.dependsOn asciidoctor
publishGhPages.dependsOn asciidoctor
githubPages {

19
docs/src/docs/asciidoc/index.adoc
View File

@@ -1,19 +0,0 @@
:messaging_version: 1.1.0
= Accurest
_Adam Dudczak, Marcin Grzejszczak, Jakub Kubryński, Karol Lassak, Olga Maciaszek-Sharma, Mariusz Smykuła_
include::introduction.adoc[]
include::contract.adoc[]
include::rest.adoc[]
include::messaging.adoc[]
include::stubrunner.adoc[]
include::stubrunner_msg.adoc[]
include::migration.adoc[]

148
docs/src/docs/asciidoc/messaging.adoc
View File

@@ -1,148 +0,0 @@
== Accurest Messaging
WARNING: Feature available since {messaging_version}
Accurest allows you to verify your application that uses messaging as means of communication.
All of our integrations are working with Spring but you can also set one yourself.
=== Integrations
You can use one of the three integration configurations:
- Apache Camel
- Spring Integration
- Spring Cloud Stream
If you're using Spring Boot, the aforementioned test configurations will be appended automatically.
You have to provide as a dependency one of the Accurest Messaging modules. Example for Gradle:
[source,groovy,indent=0]
----
// for Apache Camel
testCompile "io.codearte.accurest:accurest-messaging-camel:${accurestVersion}"
// for Spring Integration
testCompile "io.codearte.accurest:accurest-messaging-integration:${accurestVersion}"
// for Spring Cloud Stream
testCompile "io.codearte.accurest:accurest-messaging-stream:${accurestVersion}"
----
=== Manual Integration
The `accurest-messaging-core` module contains 3 main interfaces:
- `AccurestMessage` - describes a message received / sent to a channel / queue / topic etc.
- `AccurestMessageBuilder` - describes how to build a message
- `AccurestMessaging` - class that allows you to build, send and receive messages
- `AccurestFilter` - interface to filter out the messages that do not follow the pattern from the DSL
In the generated test the `AccurestMessaging` is injected via `@Inject` annotation thus you can use other injection
frameworks than Spring.
You have to provide as a dependency the `accurest-messaging-core` module. Example for Gradle:
[source,groovy,indent=0]
----
testCompile "io.codearte.accurest:accurest-messaging-core:${accurestVersion}"
----
=== Publisher side test generation
Having the `input` or `outputMessage` sections in your DSL will result in creation of tests on the publisher's side. By default
JUnit tests will be created, however there is also a possibility to create Spock tests.
There are 3 main scenarios that we should take into consideration:
- Scenario 1: there is no input message that produces an output one. The output message is triggered by a component
inside the application (e.g. scheduler)
- Scenario 2: the input message triggers an output message
- Scenario 3: the input message is consumed and there is no output message
==== Scenario 1 (no input message)
For the given contract:
[source,groovy]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_method_dsl]
----
The following JUnit test will be created:
[source,groovy]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_method_junit_test]
----
And the following Spock test would be created:
[source,groovy]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_method_test]
----
==== Scenario 2 (output triggered by input)
For the given contract:
[source,groovy]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_message_dsl]
----
The following JUnit test will be created:
[source,groovy]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_message_junit]
----
And the following Spock test would be created:
[source,groovy]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_message_spock]
----
==== Scenario 3 (no output message)
For the given contract:
[source,groovy]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_no_output_dsl]
----
The following JUnit test will be created:
[source,groovy]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_no_output_junit]
----
And the following Spock test would be created:
[source,groovy]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_no_output_spock]
----
=== Consumer Stub Side generation
Unlike the HTTP part - in Messaging we need to publish the Groovy DSL inside the JAR with a stub. Then it's parsed on the consumer side
and proper stubbed routes are created.
For more infromation please consult the Stub Runner Messaging sections.
==== Gradle Setup
Example of Accurest Gradle setup:
[source,groovy,indent=0]
----
include::../../../../accurest-gradle-plugin/src/test/resources/functionalTest/scenarioProject/build.gradle[tags=jar_setup,indent=0]
----
==== Maven Setup
Example of Maven can be found in the https://github.com/Codearte/accurest-maven-plugin/=publishing-wiremock-stubs-projectf-stubsjar[Accurest Maven Plugin README]

23
docs/src/docs/asciidoc/migration.adoc
View File

@@ -1,23 +0,0 @@
== Migration Guide
=== Migration to 0.4.7
- in 0.4.7 we've fixed package name (coderate to codearte) so you've to do the same in your projects. This means replacing ```io.coderate.accurest.dsl.GroovyDsl``` with ```io.codearte.accurest.dsl.GroovyDsl```
=== Migration to 1.0.0-RC1
- from 1.0.0 we're distinguish ignored contracts from excluded contracts:
- `excludedFiles` pattern tells Accurest to skip processing those files at all
- `ignoredFiles` pattern tells Accurest to generate contracts and tests, but tests will be marked as `@Ignore`
- from 1.0.0 the `basePackageForTests` behaviour has changed
- prior to the change all DSL files had to be under `contractsDslDir`/`basePackageForTests`/*subpackage* resulting in `basePackageForTests`.*subpackage* test package creation
- now all DSL files have to be under `contractsDslDir`/*subpackage* resulting in `basePackageForTests`.*subpackage* test package creation
- If you don't migrate to the new approach you will have your tests under `contractsDslDir`.`contractsDslDir`.*subpackage*
=== Migration to {messaging_version}
- from {messaging_version} we're setting JUnit as a default testing utility. You have to pass the following option to keep Spock
as your first choice:
[source,groovy]
----
include::../../../../accurest-gradle-plugin/src/test/resources/functionalTest/scenarioProject/build.gradle[tags=target_framework,indent=0]
----

58
docs/src/docs/asciidoc/stubrunner_msg.adoc
View File

@@ -1,58 +0,0 @@
== Stub Runner for Messaging
WARNING: Feature available since {messaging_version}
Stub Runner has the functionality to run the published stubs in memory. It can integrate with the following frameworks out of the box
- Spring Integration
- Spring Cloud Stream
- Apache Camel
It also provides points of entry to integrate with any other solution on the market.
=== Stub triggering
To trigger a message it's enough to use the `StubTigger` interface:
[source,groovy]
----
include::../../../../stub-runner/stub-runner/src/main/groovy/io/codearte/accurest/stubrunner/StubTrigger.groovy[]
----
For convenience the `StubFinder` interface extends `StubTrigger` so it's enough to use only one in your tests.
`StubTrigger` gives you the following options to trigger a message:
==== Trigger by label
[source,groovy]
----
include::../../../../stub-runner/stub-runner-messaging/stub-runner-messaging-camel/src/test/groovy/io/codearte/accurest/stubrunner/messaging/camel/CamelStubRunnerSpec.groovy[tags=client_trigger,indent=0]
----
===== Trigger by group and artifact ids
[source,groovy]
----
include::../../../../stub-runner/stub-runner-messaging/stub-runner-messaging-camel/src/test/groovy/io/codearte/accurest/stubrunner/messaging/camel/CamelStubRunnerSpec.groovy[tags=trigger_group_artifact,indent=0]
----
===== Trigger by artifact ids
[source,groovy]
----
include::../../../../stub-runner/stub-runner-messaging/stub-runner-messaging-camel/src/test/groovy/io/codearte/accurest/stubrunner/messaging/camel/CamelStubRunnerSpec.groovy[tags=trigger_artifact,indent=0]
----
===== Trigger all messages
[source,groovy]
----
include::../../../../stub-runner/stub-runner-messaging/stub-runner-messaging-camel/src/test/groovy/io/codearte/accurest/stubrunner/messaging/camel/CamelStubRunnerSpec.groovy[tags=trigger_all,indent=0]
----
include::../../../../stub-runner/stub-runner-messaging/stub-runner-messaging-camel/README.adoc[]
include::../../../../stub-runner/stub-runner-messaging/stub-runner-messaging-integration/README.adoc[]
include::../../../../stub-runner/stub-runner-messaging/stub-runner-messaging-stream/README.adoc[]

17
docs/src/main/asciidoc/README.adoc Normal file
View File

@@ -0,0 +1,17 @@
:core_path: ../../../..
:verifier_root_path: {core_path}/spring-cloud-contract-verifier
:verifier_core_path: {verifier_root_path}/spring-cloud-contract-verifier-core
:stubrunner_core_path: {core_path}/spring-cloud-contract-stub-runner
:documentation_url: http://codearte.github.io/accurest
= Spring Cloud Contract Verifier
include::introduction.adoc[]
== Documentation
You can read more about Spring Cloud Contract Verifier by reading the {documentation_url}[docs]
== Contributing
include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing.adoc[]

58
docs/src/docs/asciidoc/contract.adoc → docs/src/main/asciidoc/contract.adoc
View File

@@ -1,27 +1,29 @@
:core_path: ../../../..
:verifier_root_path: {core_path}/spring-cloud-contract-verifier
:verifier_core_path: {verifier_root_path}/spring-cloud-contract-verifier-core
== Contract DSL
Contract DSL in Accurest is written in Groovy, but don't be alarmed if you didn't use Groovy before. Knowledge of the language is not really needed as our DSL uses only
a tiny subset of it (namely literals, method calls and closures). What's more, Accurest's DSL is designed to be programmer-readable without any knowledge of the DSL itself -
Contract DSL is written in Groovy, but don't be alarmed if you didn't use Groovy before. Knowledge of the language is not really needed as our DSL uses only
a tiny subset of it (namely literals, method calls and closures). What's more the DSL is designed to be programmer-readable without any knowledge of the DSL itself -
it's statically typed.
TIP: Since {messaging_version} you can use the `io.codearte.accurest.dsl.Accurest` class in your DSL files.
Let's look at full example of a contract definition.
[source,groovy,indent=0]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/MockMvcMethodBodyBuilderSpec.groovy[tags=dsl_example,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MockMvcMethodBodyBuilderSpec.groovy[tags=dsl_example,indent=0]
----
Not all features of the DSL are used in example above. If you didn't find what you are looking for, please check next paragraphs on this page.
> You can easily compile Accurest Contracts to WireMock stubs mapping using standalone maven command: `mvn io.codearte.accurest:accurest-maven-plugin:convert`.
> You can easily compile Contracts to WireMock stubs mapping using standalone maven command: `mvn org.springframework.cloud.contract:spring-cloud-contract-verifier-maven-plugin:convert`.
=== Limitations
WARNING: Accurest doesn't support XML properly. Please use JSON or help us implement this feature.
WARNING: Spring Cloud Contract Verifier doesn't support XML properly. Please use JSON or help us implement this feature.
WARNING: Accurest supports equality check on text response. Regular expressions are not yet available.
WARNING: Spring Cloud Contract Verifier supports equality check on text response. Regular expressions are not yet available.
=== HTTP Top-Level Elements
@@ -29,23 +31,23 @@ Following methods can be called in the top-level closure of a contract definitio
[source,groovy,indent=0]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/ContractHttpDocsSpec.groovy[tags=http_dsl,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=http_dsl,indent=0]
----
=== Request
HTTP protocol requires only **method and address** to be specified in a request. The same information is mandatory in request definition of Accurest contract.
HTTP protocol requires only **method and address** to be specified in a request. The same information is mandatory in request definition of the Contract.
[source,groovy,indent=0]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/ContractHttpDocsSpec.groovy[tags=request,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=request,indent=0]
----
It is possible to specify whole `url` instead of just path, but `urlPath` is the recommended way as it makes the tests **host-independent**.
[source,groovy,indent=0]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/ContractHttpDocsSpec.groovy[tags=url,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=url,indent=0]
----
@@ -53,28 +55,28 @@ Request may contain **query parameters**, which are specified in a closure neste
[source,groovy,indent=0]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/ContractHttpDocsSpec.groovy[tags=urlpath,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=urlpath,indent=0]
----
It may contain additional **request headers**...
[source,groovy,indent=0]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/ContractHttpDocsSpec.groovy[tags=headers,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=headers,indent=0]
----
...and a **request body**.
[source,groovy,indent=0]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/ContractHttpDocsSpec.groovy[tags=body,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=body,indent=0]
----
**Body's format** can also be specified explicitly by invoking one of format functions.
[source,groovy,indent=0]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/ContractHttpDocsSpec.groovy[tags=bodyAsXml,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=bodyAsXml,indent=0]
----
=== Response
@@ -83,7 +85,7 @@ Minimal response must contain **HTTP status code**.
[source,groovy,indent=0]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/ContractHttpDocsSpec.groovy[tags=response,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=response,indent=0]
----
Besides status response may contain **headers** and **body**, which are specified the same way as in the request (see previous paragraph).
@@ -97,7 +99,7 @@ Please see the example below:
[source,groovy,indent=0]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/ContractHttpDocsSpec.groovy[tags=regex,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=regex,indent=0]
----
=== Passing optional parameters
@@ -111,7 +113,7 @@ Example:
[source,groovy,indent=0]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/ContractHttpDocsSpec.groovy[tags=optionals,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=optionals,indent=0]
----
By wrapping a part of the body with the `optional()` method you are in fact creating a regular expression that should be present 0 or more times.
@@ -120,14 +122,14 @@ That way for the example above the following test would be generated if you pick
[source,groovy,indent=0]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/ContractHttpDocsSpec.groovy[tags=optionals_test,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=optionals_test,indent=0]
----
and the following stub:
[source,javascript,indent=0]
----
include::../../../../accurest-converters/src/test/groovy/io/codearte/accurest/wiremock/DslToWireMockClientConverterSpec.groovy[tags=wiremock,indent=0]
include::{verifier_root_path}/spring-cloud-contract-verifier-converters/src/test/groovy/org/springframework/cloud/contract/verifier/wiremock/DslToWireMockClientConverterSpec.groovy[tags=wiremock,indent=0]
----
=== Executing custom methods on server side
@@ -138,14 +140,14 @@ in the configuration. Please see the examples below:
[source,groovy,indent=0]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/ContractHttpDocsSpec.groovy[tags=method,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/ContractHttpDocsSpec.groovy[tags=method,indent=0]
----
==== Base Mock Spec
[source,groovy,indent=0]
----
include::../../../../accurest-gradle-plugin/src/test/resources/functionalTest/bootSimple/src/test/groovy/com/ofg/twitter/places/BaseMockMvcSpec.groovy[tags=base_class,indent=0]
include::{verifier_root_path}/spring-cloud-contract-verifier-gradle-plugin/src/test/resources/functionalTest/bootSimple/src/test/groovy/org/springframework/cloud/twitter/places/BaseMockMvcSpec.groovy[tags=base_class,indent=0]
----
=== JAX-RS support
@@ -164,13 +166,11 @@ Example of a test API generated:
[source,groovy,indent=0]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/JaxRsClientMethodBuilderSpec.groovy[tags=jaxrs,indent=0]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/JaxRsClientMethodBuilderSpec.groovy[tags=jaxrs,indent=0]
----
=== Messaging Top-Level Elements
WARNING: Feature available since {messaging_version}
The DSL for messaging looks a little bit different than the one that focuses on HTTP.
==== Output triggered by a method
@@ -179,7 +179,7 @@ The output message can be triggered by calling a method (e.g. a Scheduler was st
[source,groovy]
----
include::../../../../samples/messaging-integration/src/test/groovy/io/codearte/accurest/samples/messaging/IntegrationMessagingApplicationSpec.groovy[tags=method_trigger,indent=0]
include::../../../../samples/messaging-integration/src/test/groovy/org/springframework/cloud/contract/verifier/samples/messaging/IntegrationMessagingApplicationSpec.groovy[tags=method_trigger,indent=0]
----
In this case the output message will be sent to `output` if a method called `bookReturnedTriggered` will be executed. In the message *publisher's* side
@@ -191,7 +191,7 @@ The output message can be triggered by receiving a message.
[source,groovy]
----
include::../../../../samples/messaging-integration/src/test/groovy/io/codearte/accurest/samples/messaging/IntegrationMessagingApplicationSpec.groovy[tags=message_trigger,indent=0]
include::../../../../samples/messaging-integration/src/test/groovy/org/springframework/cloud/contract/verifier/samples/messaging/IntegrationMessagingApplicationSpec.groovy[tags=message_trigger,indent=0]
----
In this case the output message will be sent to `output` if a proper message will be received on the `input` destination. In the message *publisher's* side
@@ -205,5 +205,5 @@ as presented below (note you can use either `$` or `value` methods to provide `c
[source,groovy]
----
include::../../../../accurest-core/src/test/groovy/io/codearte/accurest/builder/MessagingMethodBodyBuilderSpec.groovy[tags=consumer_producer]
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=consumer_producer]
----

0
docs/src/docs/asciidoc/images/Deps.png → docs/src/main/asciidoc/images/Deps.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 36 KiB

0
docs/src/docs/asciidoc/images/Stubs1.png → docs/src/main/asciidoc/images/Stubs1.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 34 KiB

After

Width:  |  Height:  |  Size: 34 KiB

0
docs/src/docs/asciidoc/images/Stubs2.png → docs/src/main/asciidoc/images/Stubs2.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 18 KiB

1
docs/src/main/asciidoc/index.adoc Symbolic link
View File

@@ -0,0 +1 @@
spring-cloud-contract-verifier.adoc

25
docs/src/docs/asciidoc/introduction.adoc → docs/src/main/asciidoc/introduction.adoc
View File

@@ -1,14 +1,15 @@
== Introduction
Just to make long story short - Accurest is a tool that enables Consumer Driven Contract (CDC) development of JVM-based applications. It is shipped
with __Contract Definition Language__ (DSL). Contract definitions are used by Accurest to produce following resources:
Just to make long story short - Spring Cloud Contract Verifier is a tool that enables Consumer Driven Contract (CDC) development of JVM-based applications. It is shipped
with __Contract Definition Language__ (DSL). Contract definitions are used to produce following resources:
* JSON stub definitions to be used by Wiremock when doing integration testing on the client code (__client tests__).
Test code must still be written by hand, test data is produced by Accurest.
Test code must still be written by hand, test data is produced by Spring Cloud Contract Verifier.
* Messaging routes if you're using one. We're integrating with Spring Integration, Spring Cloud Stream and Apache Camel. You can however set your own integrations if you want to
* Acceptance tests (in JUnit or Spock) used to verify if server-side implementation of the API is compliant with the contract (__server tests__). Full test is generated by Accurest.
* Acceptance tests (in JUnit or Spock) used to verify if server-side implementation of the API is compliant with the contract (__server tests__).
Full test is generated by Spring Cloud Contract Verifier.
Accurest moves TDD to the level of software architecture.
Spring Cloud Contract Verifier moves TDD to the level of software architecture.
=== Why?
@@ -52,7 +53,7 @@ Disadvantages:
- the implementor of the service creates stubs thus they might have nothing to do with the reality
- you can go to production with passing tests and failing production
To solve the aforementioned issues Accurest with Stub Runner were created. Their main idea is to give you very fast feedback, without the need
To solve the aforementioned issues Spring Cloud Contract Verifier with Stub Runner were created. Their main idea is to give you very fast feedback, without the need
to set up the whole world of microservices.
image::Stubs1.png[Stubbed Services]
@@ -61,13 +62,13 @@ If you work on stubs then the only applications you need are those that your app
image::Stubs2.png[Stubbed Services]
Accurest gives you the certainty that the stubs that you're using were created by the service that you're calling. Also if you can use them it means that they were
Spring Cloud Contract Verifier gives you the certainty that the stubs that you're using 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 other words - you can trust those stubs.
=== Purposes
The main purposes of Accurest with Stub Runner are:
The main purposes of Spring Cloud Contract Verifier with Stub Runner are:
- to ensure that WireMock / Messaging stubs (used when developing the client) are doing exactly what actual server-side implementation will do,
- to promote ATDD method and Microservices architectural style,
@@ -97,7 +98,7 @@ for response verification.
=== Dependencies
Accurest and Stub Runner are using the following libraries
Spring Cloud Contract Verifier and Stub Runner are using the following libraries
- http://wiremock.org/[WireMock]
- https://github.com/jayway/JsonPath[Jayway JSONPath]
@@ -105,16 +106,16 @@ Accurest and Stub Runner are using the following libraries
=== Additional links
Below you can find some resources related to Accurest and Stub Runner. Note that some can be outdated since the Accurest project
Below you can find some resources related to Spring Cloud Contract Verifier and Stub Runner. Note that some can be outdated since the Spring Cloud Contract Verifier project
is under constant development.
==== Videos
*Olga Maciaszek-Sharma talking about Accurest*
*Olga Maciaszek-Sharma talking about Accurest (Spring Cloud Contract Verifier predecessor)*
video::daafmTYFoDU[youtube]
*Marcin Grzejszczak and Jakub Kubryński talking about Accurest*
*Marcin Grzejszczak and Jakub Kubryński talking about Accurest (Spring Cloud Contract Verifier predecessor)*
video::130779882[vimeo]

150
docs/src/main/asciidoc/messaging.adoc Normal file
View File

@@ -0,0 +1,150 @@
:core_path: ../../../..
:verifier_root_path: {core_path}/spring-cloud-contract-verifier
:verifier_core_path: {verifier_root_path}/spring-cloud-contract-verifier-core
== Spring Cloud Contract Verifier Messaging
Spring Cloud Contract Verifier allows you to verify your application that uses messaging as means of communication.
All of our integrations are working with Spring but you can also set one yourself.
=== Integrations
You can use one of the three integration configurations:
- Apache Camel
- Spring Integration
- Spring Cloud Stream
If you're using Spring Boot, the aforementioned test configurations will be appended automatically.
You have to provide as a dependency one of the Spring Cloud Contract Verifier Messaging modules. Example for Gradle:
[source,groovy,indent=0]
----
// for Apache Camel
testCompile "org.springframework.cloud.contract:spring-cloud-contract-verifier-camel:${verifierVersion}"
// for Spring Integration
testCompile "org.springframework.cloud.contract:spring-cloud-contract-verifier-integration:${verifierVersion}"
// for Spring Cloud Stream
testCompile "org.springframework.cloud.contract:spring-cloud-contract-verifier-stream:${verifierVersion}"
----
=== Manual Integration
The `spring-cloud-contract-verifier-messaging-core` module contains 3 main interfaces:
- `ContractVerifierMessage` - describes a message received / sent to a channel / queue / topic etc.
- `ContractVerifierMessageBuilder` - describes how to build a message
- `ContractVerifierMessaging` - class that allows you to build, send and receive messages
- `ContractVerifierFilter` - interface to filter out the messages that do not follow the pattern from the DSL
In the generated test the `ContractVerifierMessaging` is injected via `@Inject` annotation thus you can use other injection
frameworks than Spring.
You have to provide as a dependency the `spring-cloud-contract-verifier-messaging-core` module. Example for Gradle:
[source,groovy,indent=0]
----
testCompile "org.springframework.cloud.contract:spring-cloud-contract-verifier-messaging-core:${verifierVersion}"
----
=== Publisher side test generation
Having the `input` or `outputMessage` sections in your DSL will result in creation of tests on the publisher's side. By default
JUnit tests will be created, however there is also a possibility to create Spock tests.
There are 3 main scenarios that we should take into consideration:
- Scenario 1: there is no input message that produces an output one. The output message is triggered by a component
inside the application (e.g. scheduler)
- Scenario 2: the input message triggers an output message
- Scenario 3: the input message is consumed and there is no output message
==== Scenario 1 (no input message)
For the given contract:
[source,groovy]
----
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_method_dsl]
----
The following JUnit test will be created:
[source,groovy]
----
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_method_junit_test]
----
And the following Spock test would be created:
[source,groovy]
----
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_method_test]
----
==== Scenario 2 (output triggered by input)
For the given contract:
[source,groovy]
----
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_message_dsl]
----
The following JUnit test will be created:
[source,groovy]
----
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_message_junit]
----
And the following Spock test would be created:
[source,groovy]
----
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_message_spock]
----
==== Scenario 3 (no output message)
For the given contract:
[source,groovy]
----
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_no_output_dsl]
----
The following JUnit test will be created:
[source,groovy]
----
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_no_output_junit]
----
And the following Spock test would be created:
[source,groovy]
----
include::{verifier_core_path}/src/test/groovy/org/springframework/cloud/contract/verifier/builder/MessagingMethodBodyBuilderSpec.groovy[tags=trigger_no_output_spock]
----
=== Consumer Stub Side generation
Unlike the HTTP part - in Messaging we need to publish the Groovy DSL inside the JAR with a stub. Then it's parsed on the consumer side
and proper stubbed routes are created.
For more infromation please consult the Stub Runner Messaging sections.
==== Gradle Setup
Example of Spring Cloud Contract Verifier Gradle setup:
[source,groovy,indent=0]
----
include::{verifier_root_path}/spring-cloud-contract-verifier-gradle-plugin/src/test/resources/functionalTest/scenarioProject/build.gradle[tags=jar_setup,indent=0]
----
==== Maven Setup
Example of Maven can be found in the https://github.com/Codearte/accurest-maven-plugin/=publishing-wiremock-stubs-projectf-stubsjar[Spring Cloud Contract Verifier Maven Plugin README]

102
docs/src/docs/asciidoc/rest.adoc → docs/src/main/asciidoc/rest.adoc
View File

@@ -1,10 +1,14 @@
== Accurest HTTP
:core_path: ../../../..
:verifier_root_path: {core_path}/spring-cloud-contract-verifier
:verifier_core_path: {verifier_root_path}/spring-cloud-contract-verifier-core
== Spring Cloud Contract Verifier HTTP
=== Gradle Project
==== Prerequisites
In order to use Accurest with Wiremock you have to use gradle or maven plugin.
In order to use Spring Cloud Contract Verifier with Wiremock you have to use gradle or maven plugin.
===== Add gradle plugin
@@ -15,12 +19,12 @@ buildscript {
mavenCentral()
}
dependencies {
classpath 'io.codearte.accurest:accurest-gradle-plugin:${accurest_version}'
classpath 'org.springframework.cloud.contract:spring-cloud-contract-verifier-gradle-plugin:${verifier_version}'
}
}
apply plugin: 'groovy'
apply plugin: 'accurest'
apply plugin: 'contract-verifier'
dependencies {
testCompile 'org.codehaus.groovy:groovy-all:2.4.6'
@@ -47,8 +51,8 @@ repositories {
[source,xml,indent=0]
----
<plugin>
<groupId>io.codearte.accurest</groupId>
<artifactId>accurest-maven-plugin</artifactId>
<groupId>org.springframework.cloud.contract</groupId>
<artifactId>spring-cloud-contract-verifier-maven-plugin</artifactId>
<executions>
<execution>
<goals>
@@ -66,7 +70,7 @@ Read more: http://codearte.github.io/accurest-maven-plugin/[accurest-maven-plugi
===== Add stubs
By default Accurest is looking for stubs in `src/test/resources/accurest` directory.
By default Spring Cloud Contract Verifier is looking for stubs in `src/test/resources/contracts` directory.
Directory containing stub definitions is treated as a class name, and each stub definition is treated as a single test.
We assume that it contains at least one directory which will be used as test class name. If there is more than one level of nested directories all except the last one will be used as package name.
@@ -74,29 +78,29 @@ So with following structure
[source,groovy,indent=0]
----
src/test/resources/accurest/myservice/shouldCreateUser.groovy
src/test/resources/accurest/myservice/shouldReturnUser.groovy
src/test/resources/contracts/myservice/shouldCreateUser.groovy
src/test/resources/contracts/myservice/shouldReturnUser.groovy
----
Accurest will create test class `defaultBasePackage.MyService` with two methods
Spring Cloud Contract Verifier will create test class `defaultBasePackage.MyService` with two methods
- `shouldCreateUser()`
- `shouldReturnUser()`
==== Run plugin
Plugin registers itself to be invoked before `check` task. You have nothing to do as long as you want it to be part of your build process. If you just want to generate tests please invoke `generateAccurest` task.
Plugin registers itself to be invoked before `check` task. You have nothing to do as long as you want it to be part of your build process. If you just want to generate tests please invoke `generateContractTests` task.
==== Configure plugin
To change default configuration just add `accurest` snippet to your Gradle config
To change default configuration just add `contractVerifier` snippet to your Gradle config
[source,groovy,indent=0]
----
accurest {
contractVerifier {
testMode = 'MockMvc'
baseClassForTests = 'org.mycompany.tests'
generatedTestSourcesDir = project.file('src/accurest')
generatedTestSourcesDir = project.file('src/generatedContract')
}
----
@@ -105,22 +109,22 @@ accurest {
- **testMode** - defines mode for acceptance tests. By default MockMvc which is based on Spring's MockMvc. It can also be changed to **JaxRsClient** or to **Explicit** for real HTTP calls.
- **imports** - array with imports that should be included in generated tests (for example ['org.myorg.Matchers']). By default empty array []
- **staticImports** - array with static imports that should be included in generated tests(for example ['org.myorg.Matchers.*']). By default empty array []
- **basePackageForTests** - specifies base package for all generated tests. By default set to io.codearte.accurest.tests
- **basePackageForTests** - specifies base package for all generated tests. By default set to org.springframework.cloud.contract.verifier.tests
- **baseClassForTests** - base class for generated tests. By default `spock.lang.Specification` if using Spock tests.
- **ruleClassForTests** - specifies Rule which should be added to generated test classes.
- **ignoredFiles** - Ant matcher allowing defining stub files for which processing should be skipped. By default empty array []
- **contractsDslDir** - directory containing contracts written using the GroovyDSL. By default `$rootDir/src/test/resources/accurest`
- **generatedTestSourcesDir** - test source directory where tests generated from Groovy DSL should be placed. By default `$buildDir/generated-test-sources/accurest`
- **stubsOutputDir** - dir where the generated Wiremock stubs from Groovy DSL should be placed
- **contractsDslDir** - directory containing contracts written using the GroovyDSL. By default `$rootDir/src/test/resources/contracts`
- **generatedTestSourcesDir** - test source directory where tests generated from Groovy DSL should be placed. By default `$buildDir/generated-test-sources/contractVerifier`
- **stubsOutputDir** - dir where the generated WireMock stubs from Groovy DSL should be placed
- **targetFramework** - the target test framework to be used; currently Spock and JUnit are supported with JUnit being the default framework
===== Base class for tests
When using Accurest in default MockMvc you need to create a base specification for all generated acceptance tests. In this class you need to point to endpoint which should be verified.
When using Spring Cloud Contract Verifier in default MockMvc you need to create a base specification for all generated acceptance tests. In this class you need to point to endpoint which should be verified.
[source,groovy,indent=0]
----
include::../../../../accurest-gradle-plugin/src/test/resources/functionalTest/bootSimple/src/test/groovy/com/ofg/twitter/places/BaseMockMvcSpec.groovy[tags=base_class,indent=0]
include::{verifier_root_path}/spring-cloud-contract-verifier-gradle-plugin/src/test/resources/functionalTest/bootSimple/src/test/groovy/org/springframework/cloud/twitter/places/BaseMockMvcSpec.groovy[tags=base_class,indent=0]
----
In case of using `Explicit` mode, you can use base class to initialize the whole tested app similarly as in regular integration tests. In case of `JAXRSCLIENT` mode this base class
@@ -132,13 +136,13 @@ To ensure that provider side is complaint with defined contracts, you need to in
[source,bash,indent=0]
----
./gradlew generateAccurest test
./gradlew generateContractTests test
----
==== Accurest on consumer side
==== Spring Cloud Contract Verifier on consumer side
In consumer service you need to configure Accurest plugin in exactly the same way as in case of provider. If you don't want to use Stub Runner then you need to copy contracts stored in
`src/test/resources/accurest` and generate WireMock json stubs using:
In consumer service you need to configure Spring Cloud Contract Verifier plugin in exactly the same way as in case of provider. If you don't want to use Stub Runner then you need to copy contracts stored in
`src/test/resources/contracts` and generate WireMock json stubs using:
[source,bash,indent=0]
----
@@ -174,7 +178,7 @@ class LoanApplicationServiceSpec extends Specification {
}
----
Underneath LoanApplication makes a call to FraudDetection service. This request is handled by Wiremock server configured using stubs generated by Accurest.
Underneath LoanApplication makes a call to FraudDetection service. This request is handled by Wiremock server configured using stubs generated by Spring Cloud Contract Verifier.
=== Using in your Maven project
@@ -183,8 +187,8 @@ Underneath LoanApplication makes a call to FraudDetection service. This request
[source,xml,indent=0]
----
<plugin>
<groupId>io.codearte.accurest</groupId>
<artifactId>accurest-maven-plugin</artifactId>
<groupId>org.springframework.cloud.contract.verifier</groupId>
<artifactId>spring-cloud-contract-verifier-maven-plugin</artifactId>
<executions>
<execution>
<goals>
@@ -201,18 +205,18 @@ Read more: http://codearte.github.io/accurest-maven-plugin/[accurest-maven-plugi
==== Add stubs
By default Accurest is looking for stubs in `src/test/resources/accurest` directory.
By default Spring Cloud Contract Verifier is looking for stubs in `src/test/resources/contracts` directory.
Directory containing stub definitions is treated as a class name, and each stub definition is treated as a single test.
We assume that it contains at least one directory which will be used as test class name. If there is more than one level of nested directories all except the last one will be used as package name.
So with following structure
[source,groovy,indent=0]
----
src/test/resources/accurest/myservice/shouldCreateUser.groovy
src/test/resources/accurest/myservice/shouldReturnUser.groovy
src/test/resources/contracts/myservice/shouldCreateUser.groovy
src/test/resources/contracts/myservice/shouldReturnUser.groovy
----
Accurest will create test class `defaultBasePackage.MyService` with two methods
Spring Cloud Contract Verifier will create test class `defaultBasePackage.MyService` with two methods
- `shouldCreateUser()`
- `shouldReturnUser()`
@@ -227,8 +231,8 @@ To change default configuration just add `configuration` section to plugin defin
[source,xml,indent=0]
----
<plugin>
<groupId>io.codearte.accurest</groupId>
<artifactId>accurest-maven-plugin</artifactId>
<groupId>org.springframework.cloud.contract.verifier</groupId>
<artifactId>spring-cloud-contract-verifier-maven-plugin</artifactId>
<executions>
<execution>
<goals>
@@ -239,8 +243,8 @@ To change default configuration just add `configuration` section to plugin defin
</execution>
</executions>
<configuration>
<basePackageForTests>com.ofg.twitter.place</basePackageForTests>
<baseClassForTests>com.ofg.twitter.place.BaseMockMvcSpec</baseClassForTests>
<basePackageForTests>org.springframework.cloud.contract.verifier.twitter.place</basePackageForTests>
<baseClassForTests>org.springframework.cloud.contract.verifier.twitter.place.BaseMockMvcSpec</baseClassForTests>
</configuration>
</plugin>
----
@@ -248,17 +252,17 @@ To change default configuration just add `configuration` section to plugin defin
===== Important configuration options
- **testMode** - defines mode for acceptance tests. By default `MockMvc` which is based on Spring's MockMvc. It can also be changed to `JaxRsClient` or to `Explicit` for real HTTP calls.
- **basePackageForTests** - specifies base package for all generated tests. By default set to `io.codearte.accurest.tests`.
- **basePackageForTests** - specifies base package for all generated tests. By default set to `org.springframework.cloud.contract.verifier.tests`.
- **ruleClassForTests** - specifies Rule which should be added to generated test classes.
- **baseClassForTests** - base class for generated tests. By default `spock.lang.Specification` if using Spock tests.
- **contractsDir** - directory containing contracts written using the GroovyDSL. By default `/src/test/resources/accurest`.
- **contractsDir** - directory containing contracts written using the GroovyDSL. By default `/src/test/resources/contracts`.
- **testFramework** - the target test framework to be used; currently Spock and JUnit are supported with Spock being the default framework
For complete information take a look at http://codearte.github.io/accurest-maven-plugin/plugin-info.html[Plugin Documentation]
===== Base class for tests
When using Accurest in default MockMvc you need to create a base specification for all generated acceptance tests. In this class you need to point to endpoint which should be verified.
When using Spring Cloud Contract Verifier in default MockMvc you need to create a base specification for all generated acceptance tests. In this class you need to point to endpoint which should be verified.
[source,groovy,indent=0]
----
@@ -279,7 +283,7 @@ In case of using `Explicit` mode, you can use base class to initialize the whole
==== Invoking generated tests
Accurest Maven Plugins generates verification code into directory `/generated-test-sources/accurest` and attach this directory to `testCompile` goal.
Spring Cloud Contract Verifier Maven Plugins generates verification code into directory `/generated-test-sources/contractVerifier` and attach this directory to `testCompile` goal.
For Groovy Spock code use:
@@ -305,7 +309,7 @@ For Groovy Spock code use:
</includes>
</testSource>
<testSource>
<directory>${project.build.directory}/generated-test-sources/accurest</directory>
<directory>${project.build.directory}/generated-test-sources/contractVerifier</directory>
<includes>
<include>**/*.groovy</include>
</includes>
@@ -317,18 +321,18 @@ For Groovy Spock code use:
To ensure that provider side is complaint with defined contracts, you need to invoke `mvn generateTest test`
==== Accurest on consumer side
==== Spring Cloud Contract Verifier on consumer side
In consumer service you need to configure Accurest plugin in exactly the same way as in case of provider. You need to copy contracts stored in `src/test/resources/accurest` and generate Wiremock json stubs using: `mvn generateStubs` command. By default generated WireMock mapping is stored in directory `target/mappings`. Your project should create from this generated mappings additional artifact with classifier `stubs` for easy deploy to maven repository.
In consumer service you need to configure Spring Cloud Contract Verifier plugin in exactly the same way as in case of provider. You need to copy contracts stored in `src/test/resources/contracts` and generate Wiremock json stubs using: `mvn generateStubs` command. By default generated WireMock mapping is stored in directory `target/mappings`. Your project should create from this generated mappings additional artifact with classifier `stubs` for easy deploy to maven repository.
Sample configuration:
[source,xml,indent=0]
----
<plugin>
<groupId>io.codearte.accurest</groupId>
<artifactId>accurest-maven-plugin</artifactId>
<version>${accurest-plugin.version}</version>
<groupId>org.springframework.cloud.contract.verifier</groupId>
<artifactId>spring-cloud-contract-verifier-maven-plugin</artifactId>
<version>${verifier-plugin.version}</version>
<executions>
<execution>
<goals>
@@ -367,11 +371,11 @@ class LoanApplicationServiceSpec extends Specification {
}
----
Underneath LoanApplication makes a call to FraudDetection service. This request is handled by Wiremock server configured using stubs generated by Accurest.
Underneath LoanApplication makes a call to FraudDetection service. This request is handled by Wiremock server configured using stubs generated by Spring Cloud Contract Verifier.
=== Scenarios
It's possible to handle scenarios with Accurest. All you need to do is to stick to proper naming convention while creating your contracts. The convention requires to include order number followed by the underscore.
It's possible to handle scenarios with Spring Cloud Contract Verifier. All you need to do is to stick to proper naming convention while creating your contracts. The convention requires to include order number followed by the underscore.
[source,indent=0]
----
@@ -382,10 +386,10 @@ my_contracts_dir\
3_logout.groovy
----
Such tree will cause Accurest generating Wiremock's scenario with name `scenario1` and three steps:
Such tree will cause Spring Cloud Contract Verifier generating Wiremock's scenario with name `scenario1` and three 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 under [http://wiremock.org/stateful-behaviour.html](http://wiremock.org/stateful-behaviour.html)
Accurest will also generate tests with guaranteed order of execution.
Spring Cloud Contract Verifier will also generate tests with guaranteed order of execution.

20
docs/src/main/asciidoc/spring-cloud-contract-verifier.adoc Normal file
View File

@@ -0,0 +1,20 @@
:core_path: ../../../..
:verifier_root_path: {core_path}/spring-cloud-contract-verifier
:verifier_core_path: {verifier_root_path}/spring-cloud-contract-verifier-core
:stubrunner_core_path: {core_path}/spring-cloud-contract-stub-runner
= Spring Cloud Contract Verifier
_Adam Dudczak, Marcin Grzejszczak, Jakub Kubryński, Karol Lassak, Olga Maciaszek-Sharma, Mariusz Smykuła_
include::introduction.adoc[]
include::contract.adoc[]
include::rest.adoc[]
include::messaging.adoc[]
include::stubrunner.adoc[]
include::stubrunner_msg.adoc[]

38
docs/src/docs/asciidoc/stubrunner.adoc → docs/src/main/asciidoc/stubrunner.adoc
View File

@@ -1,6 +1,10 @@
== Stub Runner
:core_path: ../../../..
:verifier_root_path: {core_path}/spring-cloud-contract-verifier
:verifier_core_path: {verifier_root_path}/spring-cloud-contract-verifier-core
One of the issues that you could have encountered while using Accurest was to pass the generated WireMock JSON stubs from the server side to the client side (or various clients).
== Spring Cloud Contract Stub Runner
One of the issues that you could have encountered while using Spring Cloud Contract Verifier was to pass the generated WireMock JSON stubs from the server side to the client side (or various clients).
The same takes place in terms of client side generation for messaging.
Copying the JSON files / setting the client side for messaging manually is out of the question.
@@ -11,40 +15,40 @@ The easiest approach would be to centralize the way stubs are kept. For example
==== Gradle
Example of Accurest Gradle setup:
Example of Spring Cloud Contract Verifier Gradle setup:
[source,groovy,indent=0]
----
include::../../../../accurest-gradle-plugin/src/test/resources/functionalTest/scenarioProject/build.gradle[tags=jar_setup,indent=0]
include::{verifier_root_path}/spring-cloud-contract-verifier-gradle-plugin/src/test/resources/functionalTest/scenarioProject/build.gradle[tags=jar_setup,indent=0]
----
==== Maven
Example of Maven can be found in the https://github.com/Codearte/accurest-maven-plugin/=publishing-wiremock-stubs-projectf-stubsjar[Accurest Maven Plugin README]
Example of Maven can be found in the https://github.com/Codearte/accurest-maven-plugin/=publishing-wiremock-stubs-projectf-stubsjar[Spring Cloud Contract Verifier Maven Plugin README]
=== Modules
Accurest comes with a new structure of modules
Spring Cloud Contract Stub Runner comes with a new structure of modules
[source,indent=0]
----
└── stub-runner
├── stub-runner
├── stub-runner-boot
├── stub-runner-junit
├── stub-runner-spring
└── stub-runner-spring-cloud
└── spring-cloud-contract-stub-runner
├── spring-cloud-contract-stub-runner
├── spring-cloud-contract-stub-runner-boot
├── spring-cloud-contract-stub-runner-junit
├── spring-cloud-contract-stub-runner-spring
└── spring-cloud-contract-stub-runner-spring-cloud
----
include::../../../../stub-runner/stub-runner/README.adoc[]
include::../../../../spring-cloud-contract-stub-runner/spring-cloud-contract-stub-runner/README.adoc[]
include::../../../../stub-runner/stub-runner-boot/README.adoc[]
include::../../../../spring-cloud-contract-stub-runner/spring-cloud-contract-stub-runner-boot/README.adoc[]
include::../../../../stub-runner/stub-runner-junit/README.adoc[]
include::../../../../spring-cloud-contract-stub-runner/spring-cloud-contract-stub-runner-junit/README.adoc[]
include::../../../../stub-runner/stub-runner-spring/README.adoc[]
include::../../../../spring-cloud-contract-stub-runner/spring-cloud-contract-stub-runner-spring/README.adoc[]
include::../../../../stub-runner/stub-runner-spring-cloud/README.adoc[]
include::../../../../spring-cloud-contract-stub-runner/spring-cloud-contract-stub-runner-spring-cloud/README.adoc[]
=== Common properties for JUnit and Spring

61
docs/src/main/asciidoc/stubrunner_msg.adoc Normal file
View File

@@ -0,0 +1,61 @@
:core_path: ../../../..
:verifier_root_path: {core_path}/spring-cloud-contract-verifier
:verifier_core_path: {verifier_root_path}/spring-cloud-contract-verifier-core
:stubrunner_core_path: {core_path}/spring-cloud-contract-stub-runner
== Stub Runner for Messaging
Stub Runner has the functionality to run the published stubs in memory. It can integrate with the following frameworks out of the box
- Spring Integration
- Spring Cloud Stream
- Apache Camel
It also provides points of entry to integrate with any other solution on the market.
=== Stub triggering
To trigger a message it's enough to use the `StubTrigger` interface:
[source,groovy]
----
include::{stubrunner_core_path}/spring-cloud-contract-stub-runner/src/main/groovy/org/springframework/cloud/contract/stubrunner/StubTrigger.groovy[]
----
For convenience the `StubFinder` interface extends `StubTrigger` so it's enough to use only one in your tests.
`StubTrigger` gives you the following options to trigger a message:
==== Trigger by label
[source,groovy]
----
include::{stubrunner_core_path}/spring-cloud-contract-stub-runner-messaging/spring-cloud-contract-stub-runner-camel/src/test/groovy/org/springframework/cloud/contract/stubrunner/messaging/camel/CamelStubRunnerSpec.groovy[tags=client_trigger,indent=0]
----
===== Trigger by group and artifact ids
[source,groovy]
----
include::{stubrunner_core_path}/spring-cloud-contract-stub-runner-messaging/spring-cloud-contract-stub-runner-camel/src/test/groovy/org/springframework/cloud/contract/stubrunner/messaging/camel/CamelStubRunnerSpec.groovy[tags=trigger_group_artifact,indent=0]
----
===== Trigger by artifact ids
[source,groovy]
----
include::{stubrunner_core_path}/spring-cloud-contract-stub-runner-messaging/spring-cloud-contract-stub-runner-camel/src/test/groovy/org/springframework/cloud/contract/stubrunner/messaging/camel/CamelStubRunnerSpec.groovy[tags=trigger_artifact,indent=0]
----
===== Trigger all messages
[source,groovy]
----
include::{stubrunner_core_path}/spring-cloud-contract-stub-runner-messaging/spring-cloud-contract-stub-runner-camel/src/test/groovy/org/springframework/cloud/contract/stubrunner/messaging/camel/CamelStubRunnerSpec.groovy[tags=trigger_all,indent=0]
----
include::{stubrunner_core_path}/spring-cloud-contract-stub-runner-messaging/spring-cloud-contract-stub-runner-camel/README.adoc[]
include::{stubrunner_core_path}/spring-cloud-contract-stub-runner-messaging/spring-cloud-contract-stub-runner-integration/README.adoc[]
include::{stubrunner_core_path}/spring-cloud-contract-stub-runner-messaging/spring-cloud-contract-stub-runner-stream/README.adoc[]

37
docs/src/main/ruby/generate_readme.sh Executable file
View File

@@ -0,0 +1,37 @@
#!/usr/bin/env ruby
base_dir = File.join(File.dirname(__FILE__),'../../..')
src_dir = File.join(base_dir, "/src/main/asciidoc")
require 'asciidoctor'
require 'optparse'
options = {}
file = "#{src_dir}/README.adoc"
OptionParser.new do |o|
o.on('-o OUTPUT_FILE', 'Output file (default is stdout)') { |file| options[:to_file] = file unless file=='-' }
o.on('-h', '--help') { puts o; exit }
o.parse!
end
file = ARGV[0] if ARGV.length>0
# Copied from https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/scripts/asciidoc-coalescer.rb
doc = Asciidoctor.load_file file, safe: :unsafe, header_only: true, attributes: options[:attributes]
header_attr_names = (doc.instance_variable_get :@attributes_modified).to_a
header_attr_names.each {|k| doc.attributes[%(#{k}!)] = '' unless doc.attr? k }
attrs = doc.attributes
attrs['allow-uri-read'] = true
puts attrs
out = "// Do not edit this file (e.g. go instead to src/main/asciidoc)\n\n"
doc = Asciidoctor.load_file file, safe: :unsafe, parse: false, attributes: attrs
out << doc.reader.read
unless options[:to_file]
puts out
else
File.open(options[:to_file],'w+') do |file|
file.write(out)
end
end