Updated docs
This commit is contained in:
Marcin Grzejszczak
13
README.md
13
README.md
@@ -1,15 +1,18 @@
|
||||
Accurate REST
|
||||
=============
|
||||
Accurest
|
||||
========
|
||||
|
||||
[](https://travis-ci.org/Codearte/accurest) [](https://maven-badges.herokuapp.com/maven-central/io.codearte.accurest/accurest-gradle-plugin)
|
||||
[](https://gitter.im/Codearte/accurest?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
|
||||
|
||||
Consumer Driven Contracts verifier for Java
|
||||
|
||||
To make a long story short - AccuREST is a tool for Consumer Driven Contract (CDC) development. AccuREST ships an easy DSL for describing REST contracts for JVM-based applications. The contract DSL is used by AccuREST for two things:
|
||||
To make a long story short - Accurest is a tool for Consumer Driven Contract (CDC) development. Accurest ships an easy DSL for describing REST contracts for JVM-based applications.
|
||||
Since version 1.0.7 it also supports messaging.
|
||||
|
||||
The contract DSL is used by Accurest for two things:
|
||||
|
||||
1. generating WireMock's JSON stub definitions, allowing rapid development of the consumer side,
|
||||
generating Spock's acceptance tests for the server - to verify if your API implementation is compliant with the contract.
|
||||
1. generating WireMock's JSON stub definitions / stubbed messaging endpoints, allowing rapid development of the consumer side,
|
||||
generating JUnit / Spock's acceptance tests for the server - to verify if your API implementation is compliant with the contract.
|
||||
2. moving TDD to an architecture level.
|
||||
|
||||
For more information please go to the [Documentation](http://codearte.github.io/accurest/)
|
||||
|
||||
@@ -39,6 +39,7 @@ configure([project(':fraudDetectionService'), project(':loanApplicationService')
|
||||
apply plugin: 'spring-boot'
|
||||
apply plugin: 'accurest'
|
||||
|
||||
// tag::jar_setup[]
|
||||
ext {
|
||||
contractsDir = file("mappings")
|
||||
stubsOutputDirRoot = file("${project.buildDir}/production/${project.name}-stubs/")
|
||||
@@ -46,6 +47,32 @@ configure([project(':fraudDetectionService'), project(':loanApplicationService')
|
||||
contractsOutputDir = file(new File(stubsOutputDirRoot, 'repository/accurest/'))
|
||||
}
|
||||
|
||||
task copyContracts(type: Copy) {
|
||||
from contractsDir
|
||||
include '**/*.groovy'
|
||||
into contractsOutputDir
|
||||
}
|
||||
|
||||
task stubsJar(type: Jar, dependsOn: ["generateWireMockClientStubs", copyContracts]) {
|
||||
baseName = "${project.name}"
|
||||
classifier = "stubs"
|
||||
from stubsOutputDirRoot
|
||||
}
|
||||
|
||||
artifacts {
|
||||
archives stubsJar
|
||||
}
|
||||
|
||||
publishing {
|
||||
publications {
|
||||
stubs(MavenPublication) {
|
||||
artifactId "${project.name}-stubs"
|
||||
artifact stubsJar
|
||||
}
|
||||
}
|
||||
}
|
||||
// end::jar_setup[]
|
||||
|
||||
accurest {
|
||||
// tag::target_framework[]
|
||||
targetFramework = 'Spock'
|
||||
@@ -80,31 +107,6 @@ configure([project(':fraudDetectionService'), project(':loanApplicationService')
|
||||
|
||||
clean.dependsOn('cleanup')
|
||||
|
||||
task copyContracts(type: Copy) {
|
||||
from contractsDir
|
||||
include '**/*.groovy'
|
||||
into contractsOutputDir
|
||||
}
|
||||
|
||||
task stubsJar(type: Jar, dependsOn: ["generateWireMockClientStubs", copyContracts]) {
|
||||
baseName = "${project.name}"
|
||||
classifier = "stubs"
|
||||
from stubsOutputDirRoot
|
||||
}
|
||||
|
||||
artifacts {
|
||||
archives stubsJar
|
||||
}
|
||||
|
||||
publishing {
|
||||
publications {
|
||||
stubs(MavenPublication) {
|
||||
artifactId "${project.name}-stubs"
|
||||
artifact stubsJar
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
test {
|
||||
testLogging {
|
||||
exceptionFormat = 'full'
|
||||
|
||||
@@ -1,19 +1,19 @@
|
||||
Welcome to the AccuREST Wiki!
|
||||
Welcome to the Accurest Wiki!
|
||||
|
||||
Please follow to the Introduction page to start your journey with Consumer Driven Contracts in JVM
|
||||
|
||||
== 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 __REST Contract Definition Language__ (DSL). Contract definitions are used by AccuREST to produce following resources:
|
||||
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 __REST Contract Definition Language__ (DSL). Contract definitions are used by Accurest 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.
|
||||
* Acceptance tests (in Spock) used to verify if server-side implementation of the API is compliant with the contract (__server tests__). Full test is generated by AccuREST.
|
||||
* 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.
|
||||
* Acceptance tests (in Spock) used to verify if server-side implementation of the API is compliant with the contract (__server tests__). Full test is generated by Accurest.
|
||||
|
||||
AccuREST moves TDD to the level of software architecture.
|
||||
Accurest moves TDD to the level of software architecture.
|
||||
|
||||
=== Why?
|
||||
|
||||
The main purposes of AccuREST are:
|
||||
The main purposes of Accurest are:
|
||||
|
||||
- to ensure that WireMock stubs (used when developing the client) are doing exactly what actual server-side implementation will do,
|
||||
- to promote ATDD method and Microservices architectural style,
|
||||
@@ -26,7 +26,7 @@ include::messaging.adoc[]
|
||||
|
||||
== 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 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.
|
||||
|
||||
Let's look at full example of a contract definition.
|
||||
|
||||
@@ -90,7 +90,7 @@ io.codearte.accurest.dsl.GroovyDsl.make {
|
||||
|
||||
=== 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 Accurest contract.
|
||||
|
||||
[source,groovy,indent=0]
|
||||
----
|
||||
@@ -576,61 +576,6 @@ More details about Wiremock scenarios can be found under [http://wiremock.org/st
|
||||
|
||||
Accurest will also generate tests with guaranteed order of execution.
|
||||
|
||||
== Stub Runner
|
||||
|
||||
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). Copying the JSON files manually is out of the question.
|
||||
|
||||
In this article you'll see how to prepare your project to start publishing stubs as JARs and how to use Stub Runner in your tests to run WireMock servers and feed them with stub definitions.
|
||||
|
||||
=== Publishing stubs as JARs
|
||||
|
||||
The easiest approach would be to centralize the way stubs are kept. For example you can keep them as JARs in a Maven repository.
|
||||
|
||||
==== Gradle
|
||||
|
||||
Example of AccuREST Gradle setup:
|
||||
|
||||
[source,groovy,indent=0]
|
||||
----
|
||||
apply plugin: 'maven-publish'
|
||||
|
||||
ext {
|
||||
wiremockStubsOutputDirRoot == file("${project.buildDir}/production/${project.name}-stubs/")
|
||||
wiremockStubsOutputDir == new File(wiremockStubsOutputDirRoot)
|
||||
}
|
||||
|
||||
accurest {
|
||||
targetFramework == 'Spock'
|
||||
testMode == 'MockMvc'
|
||||
baseClassForTests == 'com.toomuchcoding.MvcSpec'
|
||||
contractsDslDir == file("${project.projectDir.absolutePath}/mappings/")
|
||||
generatedTestSourcesDir == file("${project.buildDir}/generated-sources/")
|
||||
stubsOutputDir == wiremockStubsOutputDir
|
||||
}
|
||||
|
||||
task stubsJar(type: Jar, dependsOn: ["generateWireMockClientStubs"]) {
|
||||
baseName == "${project.name}-stubs"
|
||||
from wiremockStubsOutputDirRoot
|
||||
}
|
||||
|
||||
artifacts {
|
||||
archives stubsJar
|
||||
}
|
||||
|
||||
publishing {
|
||||
publications {
|
||||
stubs(MavenPublication) {
|
||||
artifactId "${project.name}-stubs"
|
||||
artifact stubsJar
|
||||
}
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
==== Maven
|
||||
|
||||
Example of Maven can be found in the [AccuREST Maven Plugin README](https://github.com/Codearte/accurest-maven-plugin/=publishing-wiremock-stubs-projectf-stubsjar)
|
||||
|
||||
include::stubrunner.adoc[]
|
||||
|
||||
== Migration Guide
|
||||
|
||||
@@ -1,6 +1,26 @@
|
||||
== Using Stub Runner to automate running stubs
|
||||
== Stub Runner
|
||||
|
||||
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.
|
||||
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).
|
||||
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.
|
||||
|
||||
=== Publishing stubs as JARs
|
||||
|
||||
The easiest approach would be to centralize the way stubs are kept. For example you can keep them as JARs in a Maven repository.
|
||||
|
||||
==== Gradle
|
||||
|
||||
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
|
||||
|
||||
Example of Maven can be found in the [AccuREST Maven Plugin README](https://github.com/Codearte/accurest-maven-plugin/=publishing-wiremock-stubs-projectf-stubsjar)
|
||||
|
||||
=== Modules
|
||||
|
||||
|
||||
Reference in New Issue
Block a user