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

Reusing adocs of modules

Browse Source
This commit is contained in:
Marcin Grzejszczak
2016-04-21 09:27:17 +02:00
parent d9954503ec
commit fb94585b89
7 changed files with 198 additions and 285 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -631,203 +631,8 @@ Example of AccuREST Gradle setup:
Example of Maven can be found in the [AccuREST Maven Plugin README](https://github.com/Codearte/accurest-maven-plugin/=publishing-wiremock-stubs-projectf-stubsjar)
=== Using Stub Runner to automate running stubs
include::stubrunner.adoc[]
Stub Runner automates downloading stubs from a Maven repository (that includes also the local Maven repository) and starting the WireMock server for each of those stubs.
==== Modules
AccuREST comes with a new structure of modules
[source,indent=0]
----
└── stub-runner
├── stub-runner
├── stub-runner-junit
├── stub-runner-spring
└── stub-runner-spring-cloud
----
===== Stub Runner
Contains core logic of Stub Runner. Gives you a main class to run Stub Runner from the command line or from Gradle.
Here you can see a list of options with which you can run Stub Runner:
[source,indent=0]
----
java -jar stub-runner.jar [options...]
-maxp (--maxPort) N : Maximum port value to be assigned to the
Wiremock instance. Defaults to 15000
(default: 15000)
-minp (--minPort) N : Minimal port value to be assigned to the
Wiremock instance. Defaults to 10000
(default: 10000)
-s (--stubs) VAL : Comma separated list of Ivy representation of
jars with stubs. Eg. groupid:artifactid1,group
id2:artifactid2:classifier
-sr (--stubRepositoryRoot) VAL : Location of a Jar containing server where you
keep your stubs (e.g. http://nexus.net/content
/repositories/repository)
-ss (--stubsSuffix) VAL : Suffix for the jar containing stubs (e.g.
'stubs' if the stub jar would have a 'stubs'
classifier for stubs: foobar-stubs ).
Defaults to 'stubs' (default: stubs)
-wo (--workOffline) : Switch to work offline. Defaults to 'false'
(default: false)
----
You can either produce a fat-jar and run the app like presented above.
You can also configure the stub runner by either passing the full arguments list with the `-Pargs` like this:
`./gradlew stub-runner-root:stub-runner:run -Pargs="-c pl -minp 10000 -maxp 10005 -s a:b:c,d:e,f:g:h"`
or each parameter separately with a `-P` prefix and without the hyphen (-) in the name of the param
`./gradlew stub-runner-root:stub-runner:run -Pc=pl -Pminp=10000 -Pmaxp=10005 -Ps=a:b:c,d:e,f:g:h`
===== Stub Runner JUnit Rule
Stub Runner comes with a JUnit rule thanks to which you can very easily download and run stubs for given group and artifact id:
[source,java,indent=0]
----
@ClassRule public static AccurestRule rule == new AccurestRule()
.repoRoot("http://your.repo.com")
.downloadStub("io.codearte.accurest.stubs", "loanIssuance")
.downloadStub("io.codearte.accurest.stubs:fraudDetectionServer")
.downloadStub("io.codearte:stub1", "io.codearte:stub2:classifier", "io.codearte:stub3");
----
After that rule gets executed Stub Runner connects to your Maven repository and for the given list of dependencies tries to:
* download them
* cache them locally
* unzip them to a temporary folder
* start a WireMock server for each Maven dependency on a random port from the provided range of ports
* feed the WireMock server with all JSON files that are valid WireMock definitions
Stub Runner uses [Groovy's Grape](http://docs.groovy-lang.org/latest/html/documentation/grape.html) mechanism to download the Maven dependencies. Check their [docs](http://docs.groovy-lang.org/latest/html/documentation/grape.html) for more information.
Since the `AccurestRule` implements the `StubFinder` it allows you to find the started stubs:
[source,groovy,indent=0]
----
interface StubFinder {
/**
* For the given groupId and artifactId tries to find the matching
* URL of the running stub.
*
* @param groupId - might be null. In that case a search only via artifactId takes place
* @return URL of a running stub or null if not found
*/
URL findStubUrl(String groupId, String artifactId)
/**
* For the given Ivy notation {@code groupId:artifactId} tries to find the matching
* URL of the running stub. You can also pass only {@code artifactId}.
*
* @param ivyNotation - Ivy representation of the Maven artifact
* @return URL of a running stub or null if not found
*/
URL findStubUrl(String ivyNotation)
/**
* Returns all running stubs
*/
RunningStubs findAllRunningStubs()
}
----
Example of usage in Spock tests:
[source,groovy,indent=0]
----
@ClassRule @Shared AccurestRule rule == new AccurestRule()
.repoRoot('http://your.repo.com')
.downloadStub("io.codearte.accurest.stubs", "loanIssuance")
.downloadStub("io.codearte.accurest.stubs:fraudDetectionServer")
def 'should start WireMock servers'() {
expect: 'WireMocks are running'
rule.findStubUrl('io.codearte.accurest.stubs', 'loanIssuance') !== null
rule.findStubUrl('loanIssuance') !== null
rule.findStubUrl('loanIssuance') === rule.findStubUrl('io.codearte.accurest.stubs', 'loanIssuance')
rule.findStubUrl('io.codearte.accurest.stubs:fraudDetectionServer') !== null
and:
rule.findAllRunningStubs().isPresent('loanIssuance')
rule.findAllRunningStubs().isPresent('io.codearte.accurest.stubs', 'fraudDetectionServer')
rule.findAllRunningStubs().isPresent('io.codearte.accurest.stubs:fraudDetectionServer')
and: 'Stubs were registered'
"${rule.findStubUrl('loanIssuance').toString()}/name".toURL().text === 'loanIssuance'
"${rule.findStubUrl('fraudDetectionServer').toString()}/name".toURL().text === 'fraudDetectionServer'
}
----
Example of usage in JUnit tests:
[source,java,indent=0]
----
@ClassRule public static AccurestRule rule == new AccurestRule()
.repoRoot("http://your.repo.com")
.downloadStub("io.codearte.accurest.stubs", "loanIssuance")
.downloadStub("io.codearte.accurest.stubs:fraudDetectionServer");
@Test
public void should_start_wiremock_servers() throws Exception {
// expect: 'WireMocks are running'
then(rule.findStubUrl("io.codearte.accurest.stubs", "loanIssuance")).isNotNull();
then(rule.findStubUrl("loanIssuance")).isNotNull();
then(rule.findStubUrl("loanIssuance")).isEqualTo(rule.findStubUrl("io.codearte.accurest.stubs", "loanIssuance"));
then(rule.findStubUrl("io.codearte.accurest.stubs:fraudDetectionServer")).isNotNull();
// and:
then(rule.findAllRunningStubs().isPresent("loanIssuance")).isTrue();
then(rule.findAllRunningStubs().isPresent("io.codearte.accurest.stubs", "fraudDetectionServer")).isTrue();
then(rule.findAllRunningStubs().isPresent("io.codearte.accurest.stubs:fraudDetectionServer")).isTrue();
// and: 'Stubs were registered'
then(httpGet(rule.findStubUrl("loanIssuance").toString() + "/name")).isEqualTo("loanIssuance");
then(httpGet(rule.findStubUrl("fraudDetectionServer").toString() + "/name")).isEqualTo("fraudDetectionServer");
}
----
Check the *Common properties for JUnit and Spring* for more information on how to apply global configuration of Stub Runner.
===== Stub Runner Spring
If you're using Spring then you can just import the `io.codearte.accurest.stubrunner.spring.StubRunnerConfiguration` and a bean of type `StubFinder` will get registered.
In order to find a URL and port of a given dependency you can autowire the bean in your test and call its methods:
[source,groovy,indent=0]
----
@ContextConfiguration(classes == Config, loader == SpringApplicationContextLoader)
class StubRunnerConfigurationSpec extends Specification {
@Autowired StubFinder stubFinder
def 'should start WireMock servers'() {
expect: 'WireMocks are running'
stubFinder.findStubUrl('io.codearte.accurest.stubs', 'loanIssuance') !== null
stubFinder.findStubUrl('loanIssuance') !== null
stubFinder.findStubUrl('loanIssuance') === stubFinder.findStubUrl('io.codearte.accurest.stubs', 'loanIssuance')
stubFinder.findStubUrl('io.codearte.accurest.stubs:fraudDetectionServer') !== null
and:
stubFinder.findAllRunningStubs().isPresent('loanIssuance')
stubFinder.findAllRunningStubs().isPresent('io.codearte.accurest.stubs', 'fraudDetectionServer')
stubFinder.findAllRunningStubs().isPresent('io.codearte.accurest.stubs:fraudDetectionServer')
and: 'Stubs were registered'
"${stubFinder.findStubUrl('loanIssuance').toString()}/name".toURL().text === 'loanIssuance'
"${stubFinder.findStubUrl('fraudDetectionServer').toString()}/name".toURL().text === 'fraudDetectionServer'
}
@Configuration
@Import(StubRunnerConfiguration)
@EnableAutoConfiguration
static class Config {}
}
----
Check the *Common properties for JUnit and Spring* for more information on how to apply global configuration of Stub Runner.
===== Stub Runner Spring Cloud

37
docs/src/docs/asciidoc/stubrunner.adoc Normal file
View File

@@ -0,0 +1,37 @@
== Using Stub Runner to automate running stubs
Stub Runner automates downloading stubs from a Maven repository (that includes also the local Maven repository) and starting the WireMock server for each of those stubs.
=== Modules
AccuREST comes with a new structure of modules
[source,indent=0]
----
└── stub-runner
├── stub-runner
├── stub-runner-junit
├── stub-runner-spring
└── stub-runner-spring-cloud
----
include::../../../../stub-runner/stub-runner/README.adoc[]
include::../../../../stub-runner/stub-runner-junit/README.adoc[]
include::../../../../stub-runner/stub-runner-spring/README.adoc[]
include::../../../../stub-runner/stub-runner-spring-cloud/README.adoc[]
===== Common properties for JUnit and Spring
Some of the properties that are repetitive can be set using system properties or property sources (for Spring). Here are their names with their default values:
[width="60%",frame="topbot",options="header"]
|======================
| Property name | Default value | Description |
|stubrunner.port.range.min|10000| Minimal value of a port for a started WireMock with stubs|
|stubrunner.port.range.max|15000| Minimal value of a port for a started WireMock with stubs|
|stubrunner.stubs.repository.root|| Maven repo url. If blank then will call the local maven repo|
|stubrunner.stubs.classifier|stubs| Default classifier for the stub artifacts|
|stubrunner.work-offline|false| If true then will not contact any remote repositories to download stubs|
|stubrunner.stubs|| Comma separated list of Ivy notation of stubs to download|
|======================

106
stub-runner/stub-runner-junit/README.adoc Normal file
View File

@@ -0,0 +1,106 @@
=== Stub Runner JUnit Rule
Stub Runner comes with a JUnit rule thanks to which you can very easily download and run stubs for given group and artifact id:
[source,java,indent=0]
----
@ClassRule public static AccurestRule rule == new AccurestRule()
.repoRoot("http://your.repo.com")
.downloadStub("io.codearte.accurest.stubs", "loanIssuance")
.downloadStub("io.codearte.accurest.stubs:fraudDetectionServer")
.downloadStub("io.codearte:stub1", "io.codearte:stub2:classifier", "io.codearte:stub3");
----
After that rule gets executed Stub Runner connects to your Maven repository and for the given list of dependencies tries to:
* download them
* cache them locally
* unzip them to a temporary folder
* start a WireMock server for each Maven dependency on a random port from the provided range of ports
* feed the WireMock server with all JSON files that are valid WireMock definitions
Stub Runner uses http://docs.groovy-lang.org/latest/html/documentation/grape.html[Groovy's Grape] mechanism to download the Maven dependencies.
Check their http://docs.groovy-lang.org/latest/html/documentation/grape.html[docs] for more information.
Since the `AccurestRule` implements the `StubFinder` it allows you to find the started stubs:
[source,groovy,indent=0]
----
interface StubFinder {
/**
* For the given groupId and artifactId tries to find the matching
* URL of the running stub.
*
* @param groupId - might be null. In that case a search only via artifactId takes place
* @return URL of a running stub or null if not found
*/
URL findStubUrl(String groupId, String artifactId)
/**
* For the given Ivy notation {@code groupId:artifactId} tries to find the matching
* URL of the running stub. You can also pass only {@code artifactId}.
*
* @param ivyNotation - Ivy representation of the Maven artifact
* @return URL of a running stub or null if not found
*/
URL findStubUrl(String ivyNotation)
/**
* Returns all running stubs
*/
RunningStubs findAllRunningStubs()
}
----
Example of usage in Spock tests:
[source,groovy,indent=0]
----
@ClassRule @Shared AccurestRule rule == new AccurestRule()
.repoRoot('http://your.repo.com')
.downloadStub("io.codearte.accurest.stubs", "loanIssuance")
.downloadStub("io.codearte.accurest.stubs:fraudDetectionServer")
def 'should start WireMock servers'() {
expect: 'WireMocks are running'
rule.findStubUrl('io.codearte.accurest.stubs', 'loanIssuance') !== null
rule.findStubUrl('loanIssuance') !== null
rule.findStubUrl('loanIssuance') === rule.findStubUrl('io.codearte.accurest.stubs', 'loanIssuance')
rule.findStubUrl('io.codearte.accurest.stubs:fraudDetectionServer') !== null
and:
rule.findAllRunningStubs().isPresent('loanIssuance')
rule.findAllRunningStubs().isPresent('io.codearte.accurest.stubs', 'fraudDetectionServer')
rule.findAllRunningStubs().isPresent('io.codearte.accurest.stubs:fraudDetectionServer')
and: 'Stubs were registered'
"${rule.findStubUrl('loanIssuance').toString()}/name".toURL().text === 'loanIssuance'
"${rule.findStubUrl('fraudDetectionServer').toString()}/name".toURL().text === 'fraudDetectionServer'
}
----
Example of usage in JUnit tests:
[source,java,indent=0]
----
@ClassRule public static AccurestRule rule == new AccurestRule()
.repoRoot("http://your.repo.com")
.downloadStub("io.codearte.accurest.stubs", "loanIssuance")
.downloadStub("io.codearte.accurest.stubs:fraudDetectionServer");
@Test
public void should_start_wiremock_servers() throws Exception {
// expect: 'WireMocks are running'
then(rule.findStubUrl("io.codearte.accurest.stubs", "loanIssuance")).isNotNull();
then(rule.findStubUrl("loanIssuance")).isNotNull();
then(rule.findStubUrl("loanIssuance")).isEqualTo(rule.findStubUrl("io.codearte.accurest.stubs", "loanIssuance"));
then(rule.findStubUrl("io.codearte.accurest.stubs:fraudDetectionServer")).isNotNull();
// and:
then(rule.findAllRunningStubs().isPresent("loanIssuance")).isTrue();
then(rule.findAllRunningStubs().isPresent("io.codearte.accurest.stubs", "fraudDetectionServer")).isTrue();
then(rule.findAllRunningStubs().isPresent("io.codearte.accurest.stubs:fraudDetectionServer")).isTrue();
// and: 'Stubs were registered'
then(httpGet(rule.findStubUrl("loanIssuance").toString() + "/name")).isEqualTo("loanIssuance");
then(httpGet(rule.findStubUrl("fraudDetectionServer").toString() + "/name")).isEqualTo("fraudDetectionServer");
}
----
Check the *Common properties for JUnit and Spring* for more information on how to apply global configuration of Stub Runner.

49
stub-runner/stub-runner-junit/README.md
View File

@@ -1,49 +0,0 @@
stub-runner-junit
=================
Contains a JUnit Rule for Stub Runner.
Example of usage:
```
class AccurestRuleSpec extends Specification {
@ClassRule @Shared AccurestRule rule = new AccurestRule()
.repoRoot(AccurestRuleSpec.getResource("/m2repo").path)
.downloadStub("io.codearte.accurest.stubs", "loanIssuance")
.downloadStub("io.codearte.accurest.stubs:fraudDetectionServer")
def 'should start WireMock servers'() {
expect: 'WireMocks are running'
rule.findStubUrl('io.codearte.accurest.stubs', 'loanIssuance') != null
rule.findStubUrl('loanIssuance') != null
rule.findStubUrl('loanIssuance') == rule.findStubUrl('io.codearte.accurest.stubs', 'loanIssuance')
rule.findStubUrl('io.codearte.accurest.stubs:fraudDetectionServer') != null
and:
rule.findAllRunningStubs().isPresent('loanIssuance')
rule.findAllRunningStubs().isPresent('io.codearte.accurest.stubs', 'fraudDetectionServer')
rule.findAllRunningStubs().isPresent('io.codearte.accurest.stubs:fraudDetectionServer')
and: 'Stubs were registered'
"${rule.findStubUrl('loanIssuance').toString()}/name".toURL().text == 'loanIssuance'
"${rule.findStubUrl('fraudDetectionServer').toString()}/name".toURL().text == 'fraudDetectionServer'
}
}
```
You can set the default value of the Maven repository by means of a system property:
```
-Dstubrunner.stubs.repository.root=http://your.maven.repo.com
```
The list of configurable properties contains:
| Name | Default value | Description |
|------|---------------|-------------|
| stubrunner.port.range.min | 10000 | Minimal value of a port for a WireMock server |
| stubrunner.port.range.max | 15000 | Maximum value of a port for a WireMock server |
| stubrunner.stubs.repository.root | | Address to your M2 repo (will point to local M2 repo if none is provided) |
| stubrunner.stubs.classifier | stubs | Default classifier for the JARs containing stubs |
| stubrunner.work-offline | false | Should try to connect to any repo to download stubs (useful if there's no internet) |
| stubrunner.stubs | | Default comma separated list of stubs to download |

8
stub-runner/stub-runner-spring-cloud/README.md → stub-runner/stub-runner-spring-cloud/README.adoc
View File

@@ -1,11 +1,11 @@
stub-runner-spring-cloud
========================
=== Stub Runner Spring Cloud
Registers the stubs in the provided Service Discovery. It's enough to add the jar
```
[source,groovy,indent=0]
----
io.codearte.accurest:stub-runner-spring-cloud
```
----
and the Stub Runner autoconfiguration should be picked up.

34
stub-runner/stub-runner-spring/README.md → stub-runner/stub-runner-spring/README.adoc
View File

@@ -1,5 +1,4 @@
stub-runner-spring
=======================
=== Stub Runner Spring
Sets up Spring configuration of the Stub Runner project.
@@ -9,28 +8,39 @@ and registers in WireMock the selected stubs.
If you want to find the URL of your stubbed dependency you can autowire the `StubFinder` interface and use
its methods as presented below:
```
[source,groovy,indent=0]
----
@ContextConfiguration(classes == Config, loader == SpringApplicationContextLoader)
class StubRunnerConfigurationSpec extends Specification {
@Autowired StubFinder stubFinder
def 'should start WireMock servers'() {
expect: 'WireMocks are running'
stubFinder.findStubUrl('io.codearte.accurest.stubs', 'loanIssuance') != null
stubFinder.findStubUrl('loanIssuance') != null
stubFinder.findStubUrl('loanIssuance') == stubFinder.findStubUrl('io.codearte.accurest.stubs', 'loanIssuance')
stubFinder.findStubUrl('io.codearte.accurest.stubs:fraudDetectionServer') != null
stubFinder.findStubUrl('io.codearte.accurest.stubs', 'loanIssuance') !== null
stubFinder.findStubUrl('loanIssuance') !== null
stubFinder.findStubUrl('loanIssuance') === stubFinder.findStubUrl('io.codearte.accurest.stubs', 'loanIssuance')
stubFinder.findStubUrl('io.codearte.accurest.stubs:fraudDetectionServer') !== null
and:
stubFinder.findAllRunningStubs().isPresent('loanIssuance')
stubFinder.findAllRunningStubs().isPresent('io.codearte.accurest.stubs', 'fraudDetectionServer')
stubFinder.findAllRunningStubs().isPresent('io.codearte.accurest.stubs:fraudDetectionServer')
and: 'Stubs were registered'
"${stubFinder.findStubUrl('loanIssuance').toString()}/name".toURL().text == 'loanIssuance'
"${stubFinder.findStubUrl('fraudDetectionServer').toString()}/name".toURL().text == 'fraudDetectionServer'
"${stubFinder.findStubUrl('loanIssuance').toString()}/name".toURL().text === 'loanIssuance'
"${stubFinder.findStubUrl('fraudDetectionServer').toString()}/name".toURL().text === 'fraudDetectionServer'
}
```
@Configuration
@Import(StubRunnerConfiguration)
@EnableAutoConfiguration
static class Config {}
}
----
for the following configuration file:
```
[source,groovy,indent=0]
----
stubrunner.stubs.repository.root: classpath:m2repo
stubrunner.stubs.ids: io.codearte.accurest.stubs:loanIssuance,io.codearte.accurest.stubs:fraudDetectionServer
```
----

52
stub-runner/stub-runner/README.md → stub-runner/stub-runner/README.adoc
View File

@@ -1,16 +1,16 @@
Stub-runner
===========
=== Stub Runner core
Runs stubs for service collaborators. Treating stubs as contracts of services allows to use stub-runner as an implementation of
[Consumer Driven Contracts](http://martinfowler.com/articles/consumerDrivenContracts.html).
http://martinfowler.com/articles/consumerDrivenContracts.html[Consumer Driven Contracts].
### Running stubs
==== Running stubs
#### Running using main app
===== Running using main app
You can set the following options to the main class:
```
[source,groovy,indent=0]
----
-maxp (--maxPort) N : Maximum port value to be assigned to the
Wiremock instance. Defaults to 15000
(default: 15000)
@@ -29,45 +29,49 @@ You can set the following options to the main class:
Defaults to 'stubs' (default: stubs)
-wo (--workOffline) : Switch to work offline. Defaults to 'false'
(default: false)
```
----
#### Building a Fat Jar
===== Building a Fat Jar
Just call the following command:
```
[source,groovy,indent=0]
----
./gradlew stub-runner-root:stub-runner:shadowJar -PfatJar
```
----
and inside the `build/lib` there will be a Fat Jar with classifier `fatJar` waiting for you to execute. E.g.
```
[source,groovy,indent=0]
----
java -jar stub-runner/stub-runner/build/libs/stub-runner-1.0.1-SNAPSHOT-fatJar.jar -sr http://a.b.com -s a:b:c,d:e,f:g:h
```
----
### Stub runner configuration
==== Stub runner configuration
You can configure the stub runner by either passing the full arguments list with the `-Pargs` like this:
```
[source,groovy,indent=0]
----
./gradlew stub-runner-root:stub-runner:run -Pargs="-c pl -minp 10000 -maxp 10005 -s a:b:c,d:e,f:g:h"
```
----
or each parameter separately with a `-P` prefix and without the hyphen `-` in the name of the param
```
[source,groovy,indent=0]
----
./gradlew stub-runner-root:stub-runner:run -Pc=pl -Pminp=10000 -Pmaxp=10005 -Ps=a:b:c,d:e,f:g:h
```
----
===== Stubs
#### Stubs
Stubs are defined in JSON documents, whose syntax is defined in [WireMock documentation](http://wiremock.org/stubbing.html)
Stubs are defined in JSON documents, whose syntax is defined in http://wiremock.org/stubbing.html[WireMock documentation]
Example:
```json
[source,javascript,indent=0]
----
{
"request": {
"method": "GET",
@@ -81,10 +85,10 @@ Example:
}
}
}
```
----
In the provided JAR file we're harvesting all JSON files and try to put them inside running WireMock instance.
#### Viewing registered mappings
===== Viewing registered mappings
Every stubbed collaborator exposes list of defined mappings under `__/admin/` endpoint.