Sync docs from 2.0.x to gh-pages
This commit is contained in:
Marcin Grzejszczak
@@ -1,7 +1,10 @@
|
||||
<html><head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
|
||||
<title>3. Spring Cloud Contract Verifier Setup</title><link rel="stylesheet" type="text/css" href="css/manual-multipage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="multi_spring-cloud-contract.html" title="Spring Cloud Contract"><link rel="up" href="multi_spring-cloud-contract.html" title="Spring Cloud Contract"><link rel="prev" href="multi__spring_cloud_contract_verifier_introduction.html" title="2. Spring Cloud Contract Verifier Introduction"><link rel="next" href="multi__spring_cloud_contract_verifier_messaging.html" title="4. Spring Cloud Contract Verifier Messaging"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3. Spring Cloud Contract Verifier Setup</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="multi__spring_cloud_contract_verifier_introduction.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="multi__spring_cloud_contract_verifier_messaging.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_contract_verifier_setup" href="#_spring_cloud_contract_verifier_setup"></a>3. Spring Cloud Contract Verifier Setup</h1></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_gradle_project" href="#_gradle_project"></a>3.1 Gradle Project</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_prerequisites" href="#_prerequisites"></a>3.1.1 Prerequisites</h3></div></div></div><p>In order to use Spring Cloud Contract Verifier with WireMock you have to use Gradle or Maven plugin.</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>If you want to use Spock in your projects you have to add separately
|
||||
the <code class="literal">spock-core</code> and <code class="literal">spock-spring</code> modules. Check <a class="link" href="http://spockframework.github.io/" target="_top">Spock docs for more information</a></p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_add_gradle_plugin_with_dependencies" href="#_add_gradle_plugin_with_dependencies"></a>3.1.2 Add gradle plugin with dependencies</h3></div></div></div><pre class="programlisting">buildscript {
|
||||
<title>3. Spring Cloud Contract Verifier Setup</title><link rel="stylesheet" type="text/css" href="css/manual-multipage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="multi_spring-cloud-contract.html" title="Spring Cloud Contract"><link rel="up" href="multi_spring-cloud-contract.html" title="Spring Cloud Contract"><link rel="prev" href="multi__spring_cloud_contract_verifier_introduction.html" title="2. Spring Cloud Contract Verifier Introduction"><link rel="next" href="multi__spring_cloud_contract_verifier_messaging.html" title="4. Spring Cloud Contract Verifier Messaging"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3. Spring Cloud Contract Verifier Setup</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="multi__spring_cloud_contract_verifier_introduction.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="multi__spring_cloud_contract_verifier_messaging.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_contract_verifier_setup" href="#_spring_cloud_contract_verifier_setup"></a>3. Spring Cloud Contract Verifier Setup</h1></div></div></div><p>You can set up Spring Cloud Contract Verifier in either of two ways</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="link" href="multi__spring_cloud_contract_verifier_setup.html#gradle-project" title="3.1 Gradle Project">As a Gradle project</a></li><li class="listitem"><a class="link" href="multi__spring_cloud_contract_verifier_setup.html#maven-project" title="3.2 Maven Project">As a Maven project</a></li></ul></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="gradle-project" href="#gradle-project"></a>3.1 Gradle Project</h2></div></div></div><p>To learn how to set up the Gradle project for Spring Cloud Contract Verifier, read the
|
||||
following sections:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#gradle-prerequisites" title="3.1.1 Prerequisites">Section 3.1.1, “Prerequisites”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#gradle-add-gradle-plugin" title="3.1.2 Add Gradle Plugin with Dependencies">Section 3.1.2, “Add Gradle Plugin with Dependencies”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#gradle-and-rest-assured" title="3.1.3 Gradle and Rest Assured 2.0">Section 3.1.3, “Gradle and Rest Assured 2.0”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#gradle-snapshot-versions" title="3.1.4 Snapshot Versions for Gradle">Section 3.1.4, “Snapshot Versions for Gradle”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#gradle-add-stubs" title="3.1.5 Add stubs">Section 3.1.5, “Add stubs”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#gradle-default-setup" title="3.1.7 Default Setup">Section 3.1.7, “Default Setup”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#gradle-configure-plugin" title="3.1.8 Configure Plugin">Section 3.1.8, “Configure Plugin”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#gradle-configuration-options" title="3.1.9 Configuration Options">Section 3.1.9, “Configuration Options”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#gradle-single-base-class" title="3.1.10 Single Base Class for All Tests">Section 3.1.10, “Single Base Class for All Tests”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#gradle-different-base-classes" title="3.1.11 Different Base Classes for Contracts">Section 3.1.11, “Different Base Classes for Contracts”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#gradle-invoking-generated-tests" title="3.1.12 Invoking Generated Tests">Section 3.1.12, “Invoking Generated Tests”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#gradle-consumer" title="3.1.13 Spring Cloud Contract Verifier on the Consumer Side">Section 3.1.13, “Spring Cloud Contract Verifier on the Consumer Side”</a></li></ul></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="gradle-prerequisites" href="#gradle-prerequisites"></a>3.1.1 Prerequisites</h3></div></div></div><p>In order to use Spring Cloud Contract Verifier with WireMock, you muse use either a
|
||||
Gradle or a Maven plugin.</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="images/warning.png"></td><th align="left">Warning</th></tr><tr><td align="left" valign="top"><p>If you want to use Spock in your projects, you must add separately the
|
||||
<code class="literal">spock-core</code> and <code class="literal">spock-spring</code> modules. Check <a class="link" href="http://spockframework.github.io/" target="_top">Spock
|
||||
docs for more information</a></p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="gradle-add-gradle-plugin" href="#gradle-add-gradle-plugin"></a>3.1.2 Add Gradle Plugin with Dependencies</h3></div></div></div><p>To add a Gradle plugin with dependencies, use code similar to this:</p><pre class="programlisting">buildscript {
|
||||
repositories {
|
||||
mavenCentral()
|
||||
}
|
||||
@@ -26,8 +29,8 @@ dependencies {
|
||||
testCompile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.spockframework:spock-core:1.0-groovy-2.4'</span>
|
||||
testCompile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.spockframework:spock-spring:1.0-groovy-2.4'</span>
|
||||
testCompile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.springframework.cloud:spring-cloud-starter-contract-verifier'</span>
|
||||
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_gradle_and_rest_assured_2_0" href="#_gradle_and_rest_assured_2_0"></a>3.1.3 Gradle and Rest Assured 2.0</h3></div></div></div><p>By default Rest Assured 3.x is added to the classpath. However in order to give the users the
|
||||
opportunity to use Rest Assured 2.x it’s enough to add it to the plugins classpath.</p><pre class="programlisting">buildscript {
|
||||
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="gradle-and-rest-assured" href="#gradle-and-rest-assured"></a>3.1.3 Gradle and Rest Assured 2.0</h3></div></div></div><p>By default, Rest Assured 3.x is added to the classpath. However, to use Rest Assured 2.x
|
||||
you can add it to the plugins classpath, as shown here:</p><pre class="programlisting">buildscript {
|
||||
repositories {
|
||||
mavenCentral()
|
||||
}
|
||||
@@ -44,8 +47,9 @@ depenendencies {
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment">// you can exclude rest-assured from spring-cloud-contract-verifier</span>
|
||||
testCompile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"com.jayway.restassured:rest-assured:2.5.0"</span>
|
||||
testCompile <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"com.jayway.restassured:spring-mock-mvc:2.5.0"</span>
|
||||
}</pre><p>That way the plugin will automatically see that Rest Assured 2.x is present on the classpath
|
||||
and will modify the imports accordingly.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_snapshot_versions_for_gradle" href="#_snapshot_versions_for_gradle"></a>3.1.4 Snapshot versions for Gradle</h3></div></div></div><p>Add the additional snapshot repository to your build.gradle to use snapshot versions which are automatically uploaded after every successful build:</p><pre class="programlisting">buildscript {
|
||||
}</pre><p>That way, the plugin automatically sees that Rest Assured 2.x is present on the classpath
|
||||
and modifies the imports accordingly.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="gradle-snapshot-versions" href="#gradle-snapshot-versions"></a>3.1.4 Snapshot Versions for Gradle</h3></div></div></div><p>Add the additional snapshot repository to your build.gradle to use snapshot versions,
|
||||
which are automatically uploaded after every successful build, as shown here:</p><pre class="programlisting">buildscript {
|
||||
repositories {
|
||||
mavenCentral()
|
||||
mavenLocal()
|
||||
@@ -53,10 +57,17 @@ and will modify the imports accordingly.</p></div><div class="section"><div clas
|
||||
maven { url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://repo.spring.io/milestone"</span> }
|
||||
maven { url <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"http://repo.spring.io/release"</span> }
|
||||
}
|
||||
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_add_stubs" href="#_add_stubs"></a>3.1.5 Add stubs</h3></div></div></div><p>By default Spring Cloud Contract Verifier is looking for stubs in <code class="literal">src/test/resources/contracts</code> directory.</p><p>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</p><pre class="programlisting">src/test/resources/contracts/myservice/shouldCreateUser.groovy
|
||||
src/test/resources/contracts/myservice/shouldReturnUser.groovy</pre><p>Spring Cloud Contract Verifier will create test class <code class="literal">defaultBasePackage.MyService</code> with two methods</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">shouldCreateUser()</code></li><li class="listitem"><code class="literal">shouldReturnUser()</code></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_run_plugin" href="#_run_plugin"></a>3.1.6 Run plugin</h3></div></div></div><p>Plugin registers itself to be invoked before <code class="literal">check</code> 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 <code class="literal">generateContractTests</code> task.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_default_setup" href="#_default_setup"></a>3.1.7 Default setup</h3></div></div></div><p>Default Gradle Plugin setup creates the following Gradle part of the build (it’s a pseudocode)</p><pre class="programlisting">contracts {
|
||||
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="gradle-add-stubs" href="#gradle-add-stubs"></a>3.1.5 Add stubs</h3></div></div></div><p>By default, Spring Cloud Contract Verifier is looking for stubs in the
|
||||
<code class="literal">src/test/resources/contracts</code> directory.</p><p>The directory containing stub definitions is treated as a class name, and each stub
|
||||
definition is treated as a single test. Spring Cloud Contract Verifier assumes that it
|
||||
contains at least one level of directories that are to be used as the test class name.
|
||||
If more than one level of nested directories is present, all except the last one is used
|
||||
as the package name. For example, with following structure:</p><pre class="programlisting">src/test/resources/contracts/myservice/shouldCreateUser.groovy
|
||||
src/test/resources/contracts/myservice/shouldReturnUser.groovy</pre><p>Spring Cloud Contract Verifier creates a test class named <code class="literal">defaultBasePackage.MyService</code>
|
||||
with two methods:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">shouldCreateUser()</code></li><li class="listitem"><code class="literal">shouldReturnUser()</code></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="gradle-run-plugin" href="#gradle-run-plugin"></a>3.1.6 Run the Plugin</h3></div></div></div><p>The plugin registers itself to be invoked before a <code class="literal">check</code> task. If you want it to be
|
||||
part of your build process, you need to do nothing more. If you just want to generate
|
||||
tests, invoke the <code class="literal">generateContractTests</code> task.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="gradle-default-setup" href="#gradle-default-setup"></a>3.1.7 Default Setup</h3></div></div></div><p>The default Gradle Plugin setup creates the following Gradle part of the build (in
|
||||
pseudocode):</p><pre class="programlisting">contracts {
|
||||
targetFramework = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'JUNIT'</span>
|
||||
testMode = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'MockMvc'</span>
|
||||
generatedTestSourcesDir = project.file(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"${project.buildDir}/generated-test-sources/contracts"</span>)
|
||||
@@ -99,12 +110,42 @@ publishing {
|
||||
artifact verifierStubsJar
|
||||
}
|
||||
}
|
||||
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_configure_plugin" href="#_configure_plugin"></a>3.1.8 Configure plugin</h3></div></div></div><p>To change default configuration just add <code class="literal">contracts</code> snippet to your Gradle config</p><pre class="programlisting">contracts {
|
||||
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="gradle-configure-plugin" href="#gradle-configure-plugin"></a>3.1.8 Configure Plugin</h3></div></div></div><p>To change the default configuration, add a <code class="literal">contracts</code> snippet to your Gradle config, as
|
||||
shown here:</p><pre class="programlisting">contracts {
|
||||
testMode = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'MockMvc'</span>
|
||||
baseClassForTests = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'org.mycompany.tests'</span>
|
||||
generatedTestSourcesDir = project.file(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'src/generatedContract'</span>)
|
||||
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_configuration_options" href="#_configuration_options"></a>3.1.9 Configuration options</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>testMode</strong></span> - defines mode for acceptance tests. By default MockMvc which is based on Spring’s MockMvc. It can also be changed to <span class="strong"><strong>JaxRsClient</strong></span> or to <span class="strong"><strong>Explicit</strong></span> for real HTTP calls.</li><li class="listitem"><span class="strong"><strong>imports</strong></span> - array with imports that should be included in generated tests (for example ['org.myorg.Matchers']). By default empty array []</li><li class="listitem"><span class="strong"><strong>staticImports</strong></span> - array with static imports that should be included in generated tests(for example ['org.myorg.Matchers.*']). By default empty array []</li><li class="listitem"><span class="strong"><strong>basePackageForTests</strong></span> - specifies base package for all generated tests. If not set the value will be picked from <code class="literal">baseClassForTests’s package and from
|
||||
`packageWithBaseClasses</code>. If neither of these are set then the value will be set to <code class="literal">org.springframework.cloud.contract.verifier.tests</code></li><li class="listitem"><span class="strong"><strong>baseClassForTests</strong></span> - base class for all generated tests. By default <code class="literal">spock.lang.Specification</code> if using Spock tests.</li><li class="listitem"><span class="strong"><strong>packageWithBaseClasses</strong></span> - instead of providing a fixed value for base class you can provide a package where all the base classes lay. Takes precedence over <span class="strong"><strong>baseClassForTests</strong></span>.</li><li class="listitem"><span class="strong"><strong>baseClassMappings</strong></span> - explicitly map contract package to a FQN of a base class. Takes precedence over <span class="strong"><strong>packageWithBaseClasses</strong></span> and <span class="strong"><strong>baseClassForTests</strong></span>.</li><li class="listitem"><span class="strong"><strong>ruleClassForTests</strong></span> - specifies Rule which should be added to generated test classes.</li><li class="listitem"><span class="strong"><strong>ignoredFiles</strong></span> - Ant matcher allowing defining stub files for which processing should be skipped. By default empty array []</li><li class="listitem"><span class="strong"><strong>contractsDslDir</strong></span> - directory containing contracts written using the GroovyDSL. By default <code class="literal">$rootDir/src/test/resources/contracts</code></li><li class="listitem"><span class="strong"><strong>generatedTestSourcesDir</strong></span> - test source directory where tests generated from Groovy DSL should be placed. By default <code class="literal">$buildDir/generated-test-sources/contractVerifier</code></li><li class="listitem"><span class="strong"><strong>stubsOutputDir</strong></span> - dir where the generated WireMock stubs from Groovy DSL should be placed</li><li class="listitem"><span class="strong"><strong>targetFramework</strong></span> - the target test framework to be used; currently Spock and JUnit are supported with JUnit being the default framework</li></ul></div><p>The following properties are used when you want to provide where the JAR with contract lays</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>contractDependency</strong></span> - the Dependency that provides <code class="literal">groupid:artifactid:version:classifier</code> coordinates. You can use the <code class="literal">contractDependency</code> closure to set it up</li><li class="listitem"><span class="strong"><strong>contractsPath</strong></span> - if contract deps are downloaded will default to <code class="literal">groupid/artifactid</code> where <code class="literal">groupid</code> will be slash separated. Otherwise will scan contracts under provided directory</li><li class="listitem"><span class="strong"><strong>contractsWorkOffline</strong></span> - in order not to download the dependencies each time you can download them once and work offline afterwards (reuse local Maven repo)</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_single_base_class_for_all_tests" href="#_single_base_class_for_all_tests"></a>3.1.10 Single base class for all tests</h3></div></div></div><p>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.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">abstract</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> BaseMockMvcSpec <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> Specification {
|
||||
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="gradle-configuration-options" href="#gradle-configuration-options"></a>3.1.9 Configuration Options</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>testMode</strong></span>: Defines the mode for acceptance tests. By default, the mode is MockMvc,
|
||||
which is based on Spring’s MockMvc. It can also be changed to <span class="strong"><strong>JaxRsClient</strong></span> or to
|
||||
<span class="strong"><strong>Explicit</strong></span> for real HTTP calls.</li><li class="listitem"><span class="strong"><strong>imports</strong></span>: Creates an array with imports that should be included in generated tests
|
||||
(for example ['org.myorg.Matchers']). By default, it creates an empty array.</li><li class="listitem"><span class="strong"><strong>staticImports</strong></span>: Creates an array with static imports that should be included in
|
||||
generated tests(for example ['org.myorg.Matchers.*']). By default, it creates an empty
|
||||
array.</li><li class="listitem"><span class="strong"><strong>basePackageForTests</strong></span>: Specifies the base package for all generated tests. If not set,
|
||||
the value is picked from <code class="literal">baseClassForTests’s package and from `packageWithBaseClasses</code>.
|
||||
If neither of these values are set, then the value is set to
|
||||
<code class="literal">org.springframework.cloud.contract.verifier.tests</code>.</li><li class="listitem"><span class="strong"><strong>baseClassForTests</strong></span>: Creates a base class for all generated tests. By default, if you
|
||||
use Spock classes, the class is <code class="literal">spock.lang.Specification</code>.</li><li class="listitem"><span class="strong"><strong>packageWithBaseClasses</strong></span>: Defines a package where all the base classes reside. This
|
||||
setting takes precedence over <span class="strong"><strong>baseClassForTests</strong></span>.</li><li class="listitem"><span class="strong"><strong>baseClassMappings</strong></span>: Explicitly maps a contract package to a FQN of a base class. This
|
||||
setting takes precedence over <span class="strong"><strong>packageWithBaseClasses</strong></span> and <span class="strong"><strong>baseClassForTests</strong></span>.</li><li class="listitem"><span class="strong"><strong>ruleClassForTests</strong></span>: Specifies a rule that should be added to the generated test
|
||||
classes.</li><li class="listitem"><span class="strong"><strong>ignoredFiles</strong></span>: Uses an <code class="literal">Antmatcher</code> to allow defining stub files for which processing
|
||||
should be skipped. By default, it is an empty array.</li><li class="listitem"><span class="strong"><strong>contractsDslDir</strong></span>: Specifies the directory containing contracts written using the
|
||||
GroovyDSL. By default, its value is <code class="literal">$rootDir/src/test/resources/contracts</code>.</li><li class="listitem"><span class="strong"><strong>generatedTestSourcesDir</strong></span>: Specifies the test source directory where tests generated
|
||||
from the Groovy DSL should be placed. By default its value is
|
||||
<code class="literal">$buildDir/generated-test-sources/contractVerifier</code>.</li><li class="listitem"><span class="strong"><strong>stubsOutputDir</strong></span>: Specifies the directory where the generated WireMock stubs from
|
||||
the Groovy DSL should be placed.</li><li class="listitem"><span class="strong"><strong>targetFramework</strong></span>: Specifies the target test framework to be used. Currently, Spock and
|
||||
JUnit are supported with JUnit being the default framework.</li></ul></div><p>The following properties are used when you want to specify the location of the JAR
|
||||
containing the contracts:
|
||||
* <span class="strong"><strong>contractDependency</strong></span>: Specifies the Dependency that provides
|
||||
<code class="literal">groupid:artifactid:version:classifier</code> coordinates. You can use the <code class="literal">contractDependency</code>
|
||||
closure to set it up.
|
||||
* <span class="strong"><strong>contractsPath</strong></span>: Specifies the path to the jar. If contract dependencies are
|
||||
downloaded, the path defaults to <code class="literal">groupid/artifactid</code> where <code class="literal">groupid</code> is slash
|
||||
separated. Otherwise, it scans contracts under the provided directory.
|
||||
* <span class="strong"><strong>contractsWorkOffline</strong></span>: Specifies whether to download the dependencies each time, so
|
||||
that you can work online. In other words, it specifies whether to reuses the local Maven
|
||||
repo.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="gradle-single-base-class" href="#gradle-single-base-class"></a>3.1.10 Single Base Class for All Tests</h3></div></div></div><p>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 an
|
||||
endpoint, which should be verified.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">abstract</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> BaseMockMvcSpec <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> Specification {
|
||||
|
||||
def setup() {
|
||||
RestAssuredMockMvc.standaloneSetup(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> PairIdController())
|
||||
@@ -118,21 +159,32 @@ publishing {
|
||||
assert value == null
|
||||
}
|
||||
|
||||
}</pre><p>In case of using <code class="literal">Explicit</code> mode, you can use base class to initialize the whole tested app similarly as in regular integration tests. In case of <code class="literal">JAXRSCLIENT</code> mode this base class
|
||||
should also contain <code class="literal">protected WebTarget webTarget</code> field, right now the only option to test JAX-RS API is to start a web server.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_different_base_classes_for_contracts" href="#_different_base_classes_for_contracts"></a>3.1.11 Different base classes for contracts</h3></div></div></div><p>If your base classes differ between contracts you can tell the Spring Cloud Contract plugin which class should get
|
||||
extended by the autogenerated tests. You have two options:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">follow a convention by providing the <code class="literal">packageWithBaseClasses</code></li><li class="listitem">provide explicit mapping via <code class="literal">baseClassMappings</code></li></ul></div><p><span class="strong"><strong>Convention</strong></span></p><p>The convention is such that if you have a contract under e.g. <code class="literal">src/test/resources/contract/foo/bar/baz/</code> and provide the value of the <code class="literal">packageWithBaseClasses</code> property
|
||||
to <code class="literal">com.example.base</code> then we will assume that there is a <code class="literal">BarBazBase</code> class under <code class="literal">com.example.base</code> package. In other words we take last two parts of package
|
||||
if they exist and form a class with a <code class="literal">Base</code> suffix. Takes precedence over <span class="strong"><strong>baseClassForTests</strong></span>. Example of usage in the <code class="literal">contracts</code> closure:</p><pre class="programlisting">packageWithBaseClasses = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'com.example.base'</span></pre><p><span class="strong"><strong>Mapping</strong></span></p><p>You can manually map a regular expression of the contract’s package to fully qualified name of the base class for the matched contract.
|
||||
Let’s take a look at the following example:</p><pre class="programlisting">baseClassForTests = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"com.example.FooBase"</span>
|
||||
}</pre><p>If you use <code class="literal">Explicit</code> mode, you can use a base class to initialize the whole tested app
|
||||
as you might see in regular integration tests. If you use the <code class="literal">JAXRSCLIENT</code> mode, this
|
||||
base class should also contain a <code class="literal">protected WebTarget webTarget</code> field. Right now, the
|
||||
only option to test the JAX-RS API is to start a web server.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="gradle-different-base-classes" href="#gradle-different-base-classes"></a>3.1.11 Different Base Classes for Contracts</h3></div></div></div><p>If your base classes differ between contracts, you can tell the Spring Cloud Contract
|
||||
plugin which class should get extended by the autogenerated tests. You have two options:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Follow a convention by providing the <code class="literal">packageWithBaseClasses</code></li><li class="listitem">Provide explicit mapping via <code class="literal">baseClassMappings</code></li></ul></div><p><span class="strong"><strong>By Convention</strong></span></p><p>The convention is such that if you have a contract under (for example)
|
||||
<code class="literal">src/test/resources/contract/foo/bar/baz/</code> and set the value of the
|
||||
<code class="literal">packageWithBaseClasses</code> property to <code class="literal">com.example.base</code>, then Spring Cloud Contract
|
||||
Verifier assumes that there is a <code class="literal">BarBazBase</code> class under the <code class="literal">com.example.base</code> package.
|
||||
In other words, the system takes the last two parts of the package, if they exist, and
|
||||
forms a class with a <code class="literal">Base</code> suffix. This rule takes precedence over <span class="strong"><strong>baseClassForTests</strong></span>.
|
||||
Here is an example of how it works in the <code class="literal">contracts</code> closure:</p><pre class="programlisting">packageWithBaseClasses = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'com.example.base'</span></pre><p><span class="strong"><strong>By Mapping</strong></span></p><p>You can manually map a regular expression of the contract’s package to fully qualified
|
||||
name of the base class for the matched contract. You have to provide a list called
|
||||
<code class="literal">baseClassMappings</code> that consists <code class="literal">baseClassMapping</code> objects that takes a
|
||||
<code class="literal">contractPackageRegex</code> to <code class="literal">baseClassFQN</code> mapping. Consider the following example:</p><pre class="programlisting">baseClassForTests = <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">"com.example.FooBase"</span>
|
||||
baseClassMappings {
|
||||
baseClassMapping(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'.*/com/.*'</span>, <span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'com.example.ComBase'</span>)
|
||||
baseClassMapping(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'.*/bar/.*'</span>:<span xmlns:d="http://docbook.org/ns/docbook" class="hl-string">'com.example.BarBase'</span>)
|
||||
}</pre><p>Let’s assume that you have contracts under
|
||||
- <code class="literal">src/test/resources/contract/com/</code>
|
||||
- <code class="literal">src/test/resources/contract/foo/</code></p><p>By providing the <code class="literal">baseClassForTests</code> we have a fallback in case mapping didn’t succeed (you could also provide
|
||||
the <code class="literal">packageWithBaseClasses</code> as fallback). That way the tests generated from <code class="literal">src/test/resources/contract/com/</code> contracts
|
||||
will be extending the <code class="literal">com.example.ComBase</code> whereas the rest of tests will extend <code class="literal">com.example.FooBase</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_invoking_generated_tests" href="#_invoking_generated_tests"></a>3.1.12 Invoking generated tests</h3></div></div></div><p>To ensure that provider side is complaint with defined contracts, you need to invoke:</p><pre class="programlisting">./gradlew generateContractTests <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">test</span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_spring_cloud_contract_verifier_on_consumer_side" href="#_spring_cloud_contract_verifier_on_consumer_side"></a>3.1.13 Spring Cloud Contract Verifier on consumer side</h3></div></div></div><p>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
|
||||
<code class="literal">src/test/resources/contracts</code> and generate WireMock json stubs using:</p><pre class="programlisting">./gradlew generateClientStubs</pre><p>Note that <code class="literal">stubsOutputDir</code> option has to be set for stub generation to work.</p><p>When present, json stubs can be used in consumer automated tests.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@ContextConfiguration(loader == SpringApplicationContextLoader, classes == Application)</span></em>
|
||||
- <code class="literal">src/test/resources/contract/foo/</code></p><p>By providing the <code class="literal">baseClassForTests</code>, we have a fallback in case mapping did not succeed.
|
||||
(You could also provide the <code class="literal">packageWithBaseClasses</code> as a fallback.) That way, the tests
|
||||
generated from <code class="literal">src/test/resources/contract/com/</code> contracts extend the
|
||||
<code class="literal">com.example.ComBase</code>, whereas the rest of the tests extend <code class="literal">com.example.FooBase</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="gradle-invoking-generated-tests" href="#gradle-invoking-generated-tests"></a>3.1.12 Invoking Generated Tests</h3></div></div></div><p>To ensure that the provider side is compliant with defined contracts, you need to invoke:</p><pre class="programlisting">./gradlew generateContractTests <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">test</span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="gradle-consumer" href="#gradle-consumer"></a>3.1.13 Spring Cloud Contract Verifier on the Consumer Side</h3></div></div></div><p>In a consuming service, you need to configure the Spring Cloud Contract Verifier plugin
|
||||
in exactly the same way as in case of provider. If you do not want to use Stub Runner
|
||||
then you need to copy contracts stored in <code class="literal">src/test/resources/contracts</code> and generate
|
||||
WireMock JSON stubs using:</p><pre class="programlisting">./gradlew generateClientStubs</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td><th align="left">Note</th></tr><tr><td align="left" valign="top"><p>The <code class="literal">stubsOutputDir</code> option has to be set for stub generation to work.</p></td></tr></table></div><p>When present, JSON stubs can be used in automated tests of consuming a service.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@ContextConfiguration(loader == SpringApplicationContextLoader, classes == Application)</span></em>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> LoanApplicationServiceSpec <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">extends</span> Specification {
|
||||
|
||||
<em><span class="hl-annotation" style="color: gray">@ClassRule</span></em>
|
||||
@@ -152,7 +204,9 @@ will be extending the <code class="literal">com.example.ComBase</code> whereas t
|
||||
loanApplication.loanApplicationStatus == LoanApplicationStatus.LOAN_APPLIED
|
||||
loanApplication.rejectionReason == null
|
||||
}
|
||||
}</pre><p>Underneath LoanApplication makes a call to FraudDetection service. This request is handled by WireMock server configured using stubs generated by Spring Cloud Contract Verifier.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_using_in_your_maven_project" href="#_using_in_your_maven_project"></a>3.2 Using in your Maven project</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_add_maven_plugin" href="#_add_maven_plugin"></a>3.2.1 Add maven plugin</h3></div></div></div><p>Add the Spring Cloud Contract BOM</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencyManagement></span>
|
||||
}</pre><p><code class="literal">LoanApplication</code> makes a call to <code class="literal">FraudDetection</code> service. This request is handled by a
|
||||
WireMock server configured with stubs generated by Spring Cloud Contract Verifier.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="maven-project" href="#maven-project"></a>3.2 Maven Project</h2></div></div></div><p>To learn how to set up the Maven project for Spring Cloud Contract Verifier, read the
|
||||
following sections:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#maven-add-plugin" title="3.2.1 Add maven plugin">Section 3.2.1, “Add maven plugin”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#maven-rest-assured" title="3.2.2 Maven and Rest Assured 2.0">Section 3.2.2, “Maven and Rest Assured 2.0”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#maven-snapshot-versions" title="3.2.3 Snapshot versions for Maven">Section 3.2.3, “Snapshot versions for Maven”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#maven-add-stubs" title="3.2.4 Add stubs">Section 3.2.4, “Add stubs”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#maven-run-plugin" title="3.2.5 Run plugin">Section 3.2.5, “Run plugin”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#maven-configure-plugin" title="3.2.6 Configure plugin">Section 3.2.6, “Configure plugin”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#maven-configuration-options" title="3.2.7 Configuration Options">Section 3.2.7, “Configuration Options”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#maven-single-base" title="3.2.8 Single Base Class for All Tests">Section 3.2.8, “Single Base Class for All Tests”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#maven-different-base" title="3.2.9 Different base classes for contracts">Section 3.2.9, “Different base classes for contracts”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#maven-invoking-generated-tests" title="3.2.10 Invoking generated tests">Section 3.2.10, “Invoking generated tests”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#maven-sts" title="3.2.11 Maven Plugin and STS">Section 3.2.11, “Maven Plugin and STS”</a></li><li class="listitem"><a class="xref" href="multi__spring_cloud_contract_verifier_setup.html#maven-consumer" title="3.2.12 Spring Cloud Contract Verifier on the Consumer Side">Section 3.2.12, “Spring Cloud Contract Verifier on the Consumer Side”</a></li></ul></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="maven-add-plugin" href="#maven-add-plugin"></a>3.2.1 Add maven plugin</h3></div></div></div><p>Add the Spring Cloud Contract BOM in a fashion similar to this:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencyManagement></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependencies></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><dependency></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
||||
@@ -162,7 +216,7 @@ will be extending the <code class="literal">com.example.ComBase</code> whereas t
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><scope></span>import<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></scope></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependency></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencies></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencyManagement></span></pre><p>Next, the <code class="literal">Spring Cloud Contract Verifier</code> Maven plugin</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></dependencyManagement></span></pre><p>Next, add the <code class="literal">Spring Cloud Contract Verifier</code> Maven plugin:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${spring-cloud-contract.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
||||
@@ -170,8 +224,10 @@ will be extending the <code class="literal">com.example.ComBase</code> whereas t
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><packageWithBaseClasses></span>com.example.fraud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></packageWithBaseClasses></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p>You can read more in the <a class="link" href="https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract-maven-plugin/" target="_top">Spring Cloud Contract Maven Plugin Docs</a></p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_maven_and_rest_assured_2_0" href="#_maven_and_rest_assured_2_0"></a>3.2.2 Maven and Rest Assured 2.0</h3></div></div></div><p>By default Rest Assured 3.x is added to the classpath. However in order to give the users the
|
||||
opportunity to use Rest Assured 2.x it’s enough to add it to the plugins classpath.</p><pre class="programlisting"><plugin>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p>You can read more in the
|
||||
<a class="link" href="https://cloud.spring.io/spring-cloud-contract/spring-cloud-contract-maven-plugin/" target="_top">Spring
|
||||
Cloud Contract Maven Plugin Documentation</a>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="maven-rest-assured" href="#maven-rest-assured"></a>3.2.2 Maven and Rest Assured 2.0</h3></div></div></div><p>By default, Rest Assured 3.x is added to the classpath. However, you can use Rest
|
||||
Assured 2.x by adding it to the plugins classpath, as shown here:</p><pre class="programlisting"><plugin>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-contract-maven-plugin</artifactId>
|
||||
<version>${spring-cloud-contract.version}</version>
|
||||
@@ -215,8 +271,9 @@ opportunity to use Rest Assured 2.x it’s enough to add it to the plugins c
|
||||
<version><span class="hl-number">2.5</span>.<span class="hl-number">0</span></version>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
</dependencies></pre><p>That way the plugin will automatically see that Rest Assured 3.x is present on the classpath
|
||||
and will modify the imports accordingly.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_snapshot_versions_for_maven" href="#_snapshot_versions_for_maven"></a>3.2.3 Snapshot versions for Maven</h3></div></div></div><p>For Snapshot / Milestone versions you have to add the following section to your <code class="literal">pom.xml</code></p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><repositories></span>
|
||||
</dependencies></pre><p>That way, the plugin automatically sees that Rest Assured 3.x is present on the classpath
|
||||
and modifies the imports accordingly.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="maven-snapshot-versions" href="#maven-snapshot-versions"></a>3.2.3 Snapshot versions for Maven</h3></div></div></div><p>For Snapshot and Milestone versions, you have to add the following section to your
|
||||
<code class="literal">pom.xml</code>, as shown here:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><repositories></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><repository></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><id></span>spring-snapshots<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></id></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><name></span>Spring Snapshots<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></name></span>
|
||||
@@ -267,13 +324,17 @@ and will modify the imports accordingly.</p></div><div class="section"><div clas
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><enabled></span>false<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></enabled></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></snapshots></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginRepository></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginRepositories></span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_add_stubs_2" href="#_add_stubs_2"></a>3.2.4 Add stubs</h3></div></div></div><p>By default Spring Cloud Contract Verifier is looking for stubs in <code class="literal">src/test/resources/contracts</code> 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</p><pre class="programlisting">src/test/resources/contracts/myservice/shouldCreateUser.groovy
|
||||
src/test/resources/contracts/myservice/shouldReturnUser.groovy</pre><p>Spring Cloud Contract Verifier will create test class <code class="literal">defaultBasePackage.MyService</code> with two methods
|
||||
- <code class="literal">shouldCreateUser()</code>
|
||||
- <code class="literal">shouldReturnUser()</code></p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_run_plugin_2" href="#_run_plugin_2"></a>3.2.5 Run plugin</h3></div></div></div><p>Plugin goal <code class="literal">generateTests</code> is assigned to be invoked in phase <code class="literal">generate-test-sources</code>. 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 <code class="literal">generateTests</code> goal.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_configure_plugin_2" href="#_configure_plugin_2"></a>3.2.6 Configure plugin</h3></div></div></div><p>To change default configuration just add <code class="literal">configuration</code> section to plugin definition or <code class="literal">execution</code> definition.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginRepositories></span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="maven-add-stubs" href="#maven-add-stubs"></a>3.2.4 Add stubs</h3></div></div></div><p>By default, Spring Cloud Contract Verifier is looking for stubs in the
|
||||
<code class="literal">src/test/resources/contracts</code> directory. The 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 to be used as test class name. If there is more
|
||||
than one level of nested directories, all except the last one is used as package name.
|
||||
For example, with following structure:</p><pre class="programlisting">src/test/resources/contracts/myservice/shouldCreateUser.groovy
|
||||
src/test/resources/contracts/myservice/shouldReturnUser.groovy</pre><p>Spring Cloud Contract Verifier creates a test class named <code class="literal">defaultBasePackage.MyService</code>
|
||||
with two methods</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">shouldCreateUser()</code></li><li class="listitem"><code class="literal">shouldReturnUser()</code></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="maven-run-plugin" href="#maven-run-plugin"></a>3.2.5 Run plugin</h3></div></div></div><p>The plugin goal <code class="literal">generateTests</code> is assigned to be invoked in the phase called
|
||||
<code class="literal">generate-test-sources</code>. If you want it to be part of your build process, you need not do
|
||||
anything. If you just want to generate tests, invoke the <code class="literal">generateTests</code> goal.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="maven-configure-plugin" href="#maven-configure-plugin"></a>3.2.6 Configure plugin</h3></div></div></div><p>To change the default configuration, just add a <code class="literal">configuration</code> section to the plugin
|
||||
definition or the <code class="literal">execution</code> definition, as shown here:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><executions></span>
|
||||
@@ -289,18 +350,39 @@ src/test/resources/contracts/myservice/shouldReturnUser.groovy</pre><p>Spring Cl
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><basePackageForTests></span>org.springframework.cloud.verifier.twitter.place<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></basePackageForTests></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><baseClassForTests></span>org.springframework.cloud.verifier.twitter.place.BaseMockMvcSpec<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></baseClassForTests></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_important_configuration_options" href="#_important_configuration_options"></a>3.2.7 Important configuration options</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>testMode</strong></span> - defines mode for acceptance tests. By default <code class="literal">MockMvc</code> which is based on Spring’s MockMvc. It can also be changed to <code class="literal">JaxRsClient</code> or to <code class="literal">Explicit</code> for real HTTP calls.</li><li class="listitem"><span class="strong"><strong>basePackageForTests</strong></span> - specifies base package for all generated tests. If not set the value will be picked from <code class="literal">baseClassForTests’s package and from
|
||||
`packageWithBaseClasses</code>. If neither of these are set then the value will be set to <code class="literal">org.springframework.cloud.contract.verifier.tests</code></li><li class="listitem"><span class="strong"><strong>ruleClassForTests</strong></span> - specifies Rule which should be added to generated test classes.</li><li class="listitem"><span class="strong"><strong>baseClassForTests</strong></span> - base class for generated tests. By default <code class="literal">spock.lang.Specification</code> if using Spock tests.</li><li class="listitem"><span class="strong"><strong>contractsDirectory</strong></span> - directory containing contracts written using the GroovyDSL. By default <code class="literal">/src/test/resources/contracts</code>.</li><li class="listitem"><span class="strong"><strong>testFramework</strong></span> - the target test framework to be used; currently Spock and JUnit are supported with JUnit being the default framework</li><li class="listitem"><span class="strong"><strong>packageWithBaseClasses</strong></span> - instead of providing a fixed value for base class you can provide a package where all the base classes lay.
|
||||
The convention is such that if you have a contract under <code class="literal">src/test/resources/contract/foo/bar/baz/</code> and provide the value of this property
|
||||
to <code class="literal">com.example.base</code> then we will assume that there is a <code class="literal">BarBazBase</code> class under <code class="literal">com.example.base</code> package. Takes precedence
|
||||
over <span class="strong"><strong>baseClassForTests</strong></span></li><li class="listitem"><span class="strong"><strong>baseClassMappings</strong></span> - list of base class mappings that where you have to provide <code class="literal">contractPackageRegex</code> which is checked
|
||||
against the package in which the contract lays and <code class="literal">baseClassFQN</code> that maps to fully qualified name of the base class for the matched
|
||||
contract. If you have a contract under <code class="literal">src/test/resources/contract/foo/bar/baz/</code> and map the property <code class="literal">.*</code> → <code class="literal">com.example.base.BaseClass</code> then
|
||||
the test class generated from these contracts will extend <code class="literal">com.example.base.BaseClass</code>. Takes precedence over <span class="strong"><strong>packageWithBaseClasses</strong></span>
|
||||
and <span class="strong"><strong>baseClassForTests</strong></span>.</li></ul></div><p>If you want to download your contract definitions from a Maven repository you can use</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>contractDependency</strong></span> - the contract dependency that contains all the packaged contracts</li><li class="listitem"><span class="strong"><strong>contractsPath</strong></span> - path to concrete contracts in the JAR with packaged contracts. Defaults to <code class="literal">groupid/artifactid</code> where <code class="literal">gropuid</code> is slash separated.</li><li class="listitem"><span class="strong"><strong>contractsWorkOffline</strong></span> - if the dependencies should be downloaded or local Maven only should be reused</li><li class="listitem"><span class="strong"><strong>contractsRepositoryUrl</strong></span> - <span class="strong"><strong>DEPRECATED PROPERTY - please use the <code class="literal">contractRepository</code> closure</strong></span> - URL to a repo with the artifacts with contracts, if not provided should use the current Maven ones</li><li class="listitem"><p class="simpara"><span class="strong"><strong>contractRepository</strong></span> - closure where you can define properties related to repository with contracts</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><span class="strong"><strong>username</strong></span> - username to be used to connect to the repo</li><li class="listitem"><span class="strong"><strong>password</strong></span> - username to be used to connect to the repo</li><li class="listitem"><span class="strong"><strong>proxyHost</strong></span> - proxy host to be used to connect to the repo</li><li class="listitem"><span class="strong"><strong>proxyPort</strong></span> - proxy port to be used to connect to the repo</li><li class="listitem"><span class="strong"><strong>cacheDownloadedContracts</strong></span> - if you want to reuse download JARs that contain contract definitions.
|
||||
We cache only non-snapshot, explicitly provided versions (e.g. <code class="literal">+</code> or <code class="literal">1.0.0.BUILD-SNAPSHOT</code> won’t get cached).
|
||||
By default this feature is turned on.</li></ul></div></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_single_base_class_for_all_tests_2" href="#_single_base_class_for_all_tests_2"></a>3.2.8 Single base class for all tests</h3></div></div></div><p>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.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> org.mycompany.tests
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="maven-configuration-options" href="#maven-configuration-options"></a>3.2.7 Configuration Options</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>testMode</strong></span>: Defines the mode for acceptance tests. By default, the mode is MockMvc,
|
||||
which is based on Spring’s MockMvc. It can also be changed to <span class="strong"><strong>JaxRsClient</strong></span> or to
|
||||
<span class="strong"><strong>Explicit</strong></span> for real HTTP calls.</li><li class="listitem"><span class="strong"><strong>basePackageForTests</strong></span>: Specifies the base package for all generated tests. If not set,
|
||||
the value is picked from <code class="literal">baseClassForTests’s package and from `packageWithBaseClasses</code>.
|
||||
If neither of these values are set, then the value is set to
|
||||
<code class="literal">org.springframework.cloud.contract.verifier.tests</code>.</li><li class="listitem"><span class="strong"><strong>ruleClassForTests</strong></span>: Specifies a rule that should be added to the generated test
|
||||
classes.</li><li class="listitem"><span class="strong"><strong>baseClassForTests</strong></span>: Creates a base class for all generated tests. By default, if you
|
||||
use Spock classes, the class is <code class="literal">spock.lang.Specification</code>.</li><li class="listitem"><span class="strong"><strong>contractsDirectory</strong></span>: Specifies a directory containing contracts written with the
|
||||
GroovyDSL. The default directory is <code class="literal">/src/test/resources/contracts</code>.</li><li class="listitem"><span class="strong"><strong>testFramework</strong></span>: Specifies the target test framework to be used. Currently, Spock and
|
||||
JUnit are supported with JUnit being the default framework</li><li class="listitem"><span class="strong"><strong>packageWithBaseClasses</strong></span>: Defines a package where all the base classes reside. This
|
||||
setting takes precedence over <span class="strong"><strong>baseClassForTests</strong></span>. The convention is such that, if you
|
||||
have a contract under (for example) <code class="literal">src/test/resources/contract/foo/bar/baz/</code> and set
|
||||
the value of the <code class="literal">packageWithBaseClasses</code> property to <code class="literal">com.example.base</code>, then Spring
|
||||
Cloud Contract Verifier assumes that there is a <code class="literal">BarBazBase</code> class under the
|
||||
<code class="literal">com.example.base</code> package. In other words, the system takes the last two parts of the
|
||||
package, if they exist, and forms a class with a <code class="literal">Base</code> suffix.</li><li class="listitem"><span class="strong"><strong>baseClassMappings</strong></span>: Specifies a list of base class mappings that provide
|
||||
<code class="literal">contractPackageRegex</code>, which is checked against the package where the contract is
|
||||
located, and <code class="literal">baseClassFQN</code>, which maps to the fully qualified name of the base class for
|
||||
the matched contract. For example, if you have a contract under
|
||||
<code class="literal">src/test/resources/contract/foo/bar/baz/</code> and map the property
|
||||
<code class="literal">.* → com.example.base.BaseClass</code>, then the test class generated from these contracts
|
||||
extends <code class="literal">com.example.base.BaseClass</code>. This setting takes precedence over
|
||||
<span class="strong"><strong>packageWithBaseClasses</strong></span> and <span class="strong"><strong>baseClassForTests</strong></span>.</li></ul></div><p>If you want to download your contract definitions from a Maven repository, you can use
|
||||
the following options:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><span class="strong"><strong>contractDependency</strong></span>: The contract dependency that contains all the packaged contracts.</li><li class="listitem"><span class="strong"><strong>contractsPath</strong></span>: The path to the concrete contracts in the JAR with packaged contracts.
|
||||
Defaults to <code class="literal">groupid/artifactid</code> where <code class="literal">gropuid</code> is slash separated.</li><li class="listitem"><span class="strong"><strong>contractsWorkOffline</strong></span>: Dictates whether the dependencies should be downloaded or the
|
||||
local Maven artifacts should be reused.</li><li class="listitem"><span class="strong"><strong>contractsRepositoryUrl</strong></span>: <span class="strong"><strong>DEPRECATED PROPERTY - please use the <code class="literal">contractRepository</code>
|
||||
closure</strong></span>: URL to a repo with the artifacts that have contracts. If it is not provided,
|
||||
use the current Maven ones.</li><li class="listitem"><span class="strong"><strong>contractRepository</strong></span> - Lets you use a closure where you can define properties related
|
||||
to repository with contracts.</li><li class="listitem"><span class="strong"><strong>username</strong></span>: The user name to be used to connect to the repo.</li><li class="listitem"><span class="strong"><strong>password</strong></span>: The password to be used to connect to the repo.</li><li class="listitem"><span class="strong"><strong>proxyHost</strong></span>: The proxy host to be used to connect to the repo.</li><li class="listitem"><span class="strong"><strong>proxyPort</strong></span>: The proxy port to be used to connect to the repo.</li><li class="listitem"><span class="strong"><strong>cacheDownloadedContracts</strong></span> - Specifies whether to reuse downloaded JARs that contain
|
||||
contract definitions.</li></ul></div><p>We cache only non-snapshot, explicitly provided versions (for example
|
||||
<code class="literal">+</code> or <code class="literal">1.0.0.BUILD-SNAPSHOT</code> won’t get cached). By default, this feature is turned on.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="maven-single-base" href="#maven-single-base"></a>3.2.8 Single Base Class for All Tests</h3></div></div></div><p>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 an
|
||||
endpoint, which should be verified.</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">package</span> org.mycompany.tests
|
||||
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> org.mycompany.ExampleSpringController
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">import</span> com.jayway.restassured.module.mockmvc.RestAssuredMockMvc
|
||||
@@ -310,18 +392,26 @@ In this class you need to point to endpoint which should be verified.</p><pre cl
|
||||
def setup() {
|
||||
RestAssuredMockMvc.standaloneSetup(<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">new</span> ExampleSpringController())
|
||||
}
|
||||
}</pre><p>In case of using <code class="literal">Explicit</code> mode, you can use base class to initialize the whole tested app similarly as in regular integration tests. In case of <code class="literal">JAXRSCLIENT</code> mode this base class should also contain <code class="literal">protected WebTarget webTarget</code> field, right now the only option to test JAX-RS API is to start a web server.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_different_base_classes_for_contracts_2" href="#_different_base_classes_for_contracts_2"></a>3.2.9 Different base classes for contracts</h3></div></div></div><p>If your base classes differ between contracts you can tell the Spring Cloud Contract plugin which class should get
|
||||
extended by the autogenerated tests. You have two options:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">follow a convention by providing the <code class="literal">packageWithBaseClasses</code></li><li class="listitem">provide explicit mapping via <code class="literal">baseClassMappings</code></li></ul></div><p><span class="strong"><strong>Convention</strong></span></p><p>The convention is such that if you have a contract under e.g. <code class="literal">src/test/resources/contract/hello/v1/</code> and provide the value of the <code class="literal">packageWithBaseClasses</code> property
|
||||
to <code class="literal">hello</code> then we will assume that there is a <code class="literal">HelloV1Base</code> class under <code class="literal">hello</code> package. In other words we take last two parts of package
|
||||
if they exist and form a class with a <code class="literal">Base</code> suffix. Takes precedence over <span class="strong"><strong>baseClassForTests</strong></span>. Example of usage:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
||||
}</pre><p>If you use <code class="literal">Explicit</code> mode, you can use a base class to initialize the whole tested app
|
||||
similarly, as you might find in regular integration tests. If you use the <code class="literal">JAXRSCLIENT</code>
|
||||
mode, this base class should also contain a <code class="literal">protected WebTarget webTarget</code> field. Right
|
||||
now, the only option to test the JAX-RS API is to start a web server.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="maven-different-base" href="#maven-different-base"></a>3.2.9 Different base classes for contracts</h3></div></div></div><p>If your base classes differ between contracts, you can tell the Spring Cloud Contract
|
||||
plugin which class should get extended by the autogenerated tests. You have two options:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Follow a convention by providing the <code class="literal">packageWithBaseClasses</code></li><li class="listitem">provide explicit mapping via <code class="literal">baseClassMappings</code></li></ul></div><p><span class="strong"><strong>By Convention</strong></span></p><p>The convention is such that if you have a contract under (for example)
|
||||
<code class="literal">src/test/resources/contract/foo/bar/baz/</code> and set the value of the
|
||||
<code class="literal">packageWithBaseClasses</code> property to <code class="literal">com.example.base</code>, then Spring Cloud Contract
|
||||
Verifier assumes that there is a <code class="literal">BarBazBase</code> class under the <code class="literal">com.example.base</code> package.
|
||||
In other words, the system takes the last two parts of the package, if they exist, and
|
||||
forms a class with a <code class="literal">Base</code> suffix. This rule takes precedence over <span class="strong"><strong>baseClassForTests</strong></span>.
|
||||
Here is an example of how it works in the <code class="literal">contracts</code> closure:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><packageWithBaseClasses></span>hello<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></packageWithBaseClasses></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p><span class="strong"><strong>Mapping</strong></span></p><p>You can manually map a regular expression of the contract’s package to fully qualified name of the base class for the matched contract.
|
||||
You have to provide a list <code class="literal">baseClassMappings</code> of <code class="literal">baseClassMapping</code> that takes a <code class="literal">contractPackageRegex</code> to <code class="literal">baseClassFQN</code> mapping.
|
||||
Let’s take a look at the following example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p><span class="strong"><strong>By Mapping</strong></span></p><p>You can manually map a regular expression of the contract’s package to fully qualified
|
||||
name of the base class for the matched contract. You have to provide a list called
|
||||
<code class="literal">baseClassMappings</code> that consists <code class="literal">baseClassMapping</code> objects that takes a
|
||||
<code class="literal">contractPackageRegex</code> to <code class="literal">baseClassFQN</code> mapping. Consider the following example:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><configuration></span>
|
||||
@@ -333,11 +423,14 @@ Let’s take a look at the following example:</p><pre class="programlisting"
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></baseClassMapping></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></baseClassMappings></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p>Let’s assume that you have contracts under
|
||||
- <code class="literal">src/test/resources/contract/com/</code>
|
||||
- <code class="literal">src/test/resources/contract/foo/</code></p><p>By providing the <code class="literal">baseClassForTests</code> we have a fallback in case mapping didn’t succeed (you could also provide
|
||||
the <code class="literal">packageWithBaseClasses</code> as fallback). That way the tests generated from <code class="literal">src/test/resources/contract/com/</code> contracts
|
||||
will be extending the <code class="literal">com.example.ComBase</code> whereas the rest of tests will extend <code class="literal">com.example.FooBase</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_invoking_generated_tests_2" href="#_invoking_generated_tests_2"></a>3.2.10 Invoking generated tests</h3></div></div></div><p>Spring Cloud Contract Maven Plugin generates verification code into directory <code class="literal">/generated-test-sources/contractVerifier</code> and attach this directory to <code class="literal">testCompile</code> goal.</p><p>For Groovy Spock code use:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p>Assume that you have contracts under these two locations:
|
||||
* <code class="literal">src/test/resources/contract/com/</code>
|
||||
* <code class="literal">src/test/resources/contract/foo/</code></p><p>By providing the <code class="literal">baseClassForTests</code>, we have a fallback in case mapping did not succeed.
|
||||
(You can also provide the <code class="literal">packageWithBaseClasses</code> as a fallback.) That way, the tests
|
||||
generated from <code class="literal">src/test/resources/contract/com/</code> contracts extend the
|
||||
<code class="literal">com.example.ComBase</code>, whereas the rest of the tests extend <code class="literal">com.example.FooBase</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="maven-invoking-generated-tests" href="#maven-invoking-generated-tests"></a>3.2.10 Invoking generated tests</h3></div></div></div><p>The Spring Cloud Contract Maven Plugin generates verification code in a directory called
|
||||
<code class="literal">/generated-test-sources/contractVerifier</code> and attaches this directory to <code class="literal">testCompile</code>
|
||||
goal.</p><p>For Groovy Spock code, use the following:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.codehaus.gmavenplus<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>gmavenplus-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>1.5<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
||||
@@ -364,13 +457,14 @@ will be extending the <code class="literal">com.example.ComBase</code> whereas t
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></testSource></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></testSources></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></configuration></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p>To ensure that provider side is complaint with defined contracts, you need to invoke <code class="literal">mvn generateTest test</code></p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_faq_with_maven_plugin" href="#_faq_with_maven_plugin"></a>3.2.11 FAQ with Maven Plugin</h3></div></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_maven_plugin_and_sts" href="#_maven_plugin_and_sts"></a>3.2.12 Maven Plugin and STS</h3></div></div></div><p>In case you see the following exception while using STS</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/2.0.x/docs/src/main/asciidoc/images/sts_exception.png" alt="STS Exception"></div></div><p>when you click on the marker you should see sth like this</p><pre class="programlisting"> plugin:<span class="hl-number">1.1</span>.<span class="hl-number">0.</span>M1:convert:default-convert:process-<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">test</span>-resources) org.apache.maven.plugin.PluginExecutionException: Execution default-convert of goal org.springframework.cloud:spring-
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p>To ensure that provider side is compliant with defined contracts, you need to invoke
|
||||
<code class="literal">mvn generateTest test</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="maven-sts" href="#maven-sts"></a>3.2.11 Maven Plugin and STS</h3></div></div></div><p>If you see the following exception while using STS:</p><div class="informalfigure"><div class="mediaobject"><img src="https://raw.githubusercontent.com/spring-cloud/spring-cloud-contract/2.0.x/docs/src/main/asciidoc/images/sts_exception.png" alt="STS Exception"></div></div><p>When you click on the error marker you should see something like this:</p><pre class="programlisting"> plugin:<span class="hl-number">1.1</span>.<span class="hl-number">0.</span>M1:convert:default-convert:process-<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">test</span>-resources) org.apache.maven.plugin.PluginExecutionException: Execution default-convert of goal org.springframework.cloud:spring-
|
||||
cloud-contract-maven-plugin:<span class="hl-number">1.1</span>.<span class="hl-number">0.</span>M1:convert failed. at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:<span class="hl-number">145</span>) at
|
||||
org.eclipse.m2e.core.internal.embedder.MavenImpl.execute(MavenImpl.java:<span class="hl-number">331</span>) at org.eclipse.m2e.core.internal.embedder.MavenImpl$<span class="hl-number">11.</span>call(MavenImpl.java:<span class="hl-number">1362</span>) at
|
||||
...
|
||||
org.eclipse.core.internal.jobs.Worker.run(Worker.java:<span class="hl-number">55</span>) Caused by: java.lang.NullPointerException at
|
||||
org.eclipse.m2e.core.internal.builder.plexusbuildapi.EclipseIncrementalBuildContext.hasDelta(EclipseIncrementalBuildContext.java:<span class="hl-number">53</span>) at
|
||||
org.sonatype.plexus.build.incremental.ThreadBuildContext.hasDelta(ThreadBuildContext.java:<span class="hl-number">59</span>) at</pre><p>In order to fix this issue just provide the following section in your <code class="literal">pom.xml</code></p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><build></span>
|
||||
org.sonatype.plexus.build.incremental.ThreadBuildContext.hasDelta(ThreadBuildContext.java:<span class="hl-number">59</span>) at</pre><p>In order to fix this issue, provide the following section in your <code class="literal">pom.xml</code>:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><build></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><pluginManagement></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugins></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"><!--This plugin's configuration is used to store Eclipse m2e settings
|
||||
@@ -401,15 +495,15 @@ will be extending the <code class="literal">com.example.ComBase</code> whereas t
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugins></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></pluginManagement></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></build></span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_spring_cloud_contract_verifier_on_consumer_side_2" href="#_spring_cloud_contract_verifier_on_consumer_side_2"></a>3.2.13 Spring Cloud Contract Verifier on consumer side</h3></div></div></div><p>You can actually use the Spring Cloud Contract Verifier also for the consumer side!
|
||||
You can use the plugin so that it only converts the contracts and generates the stubs.
|
||||
To achieve that 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
|
||||
<code class="literal">src/test/resources/contracts</code> and generate WireMock json stubs using:
|
||||
<code class="literal">mvn generateStubs</code> command. By default generated WireMock mapping is
|
||||
stored in directory <code class="literal">target/mappings</code>. Your project should create from
|
||||
this generated mappings additional artifact with classifier <code class="literal">stubs</code> for
|
||||
easy deploy to maven repository.</p><p>Sample configuration:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></build></span></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="maven-consumer" href="#maven-consumer"></a>3.2.12 Spring Cloud Contract Verifier on the Consumer Side</h3></div></div></div><p>You can also use the Spring Cloud Contract Verifier for the consumer side. To do so, use
|
||||
the plugin so that it only converts the contracts and generates the stubs. To achieve
|
||||
that, you need to configure Spring Cloud Contract Verifier plugin in exactly the same way
|
||||
as you would for a provider. You need to copy contracts stored in
|
||||
<code class="literal">src/test/resources/contracts</code> and generate WireMock JSON stubs using the
|
||||
<code class="literal">mvn generateStubs</code> command. By default, the generated WireMock mapping is stored in a
|
||||
directory named <code class="literal">target/mappings</code>. From these generated mappings, your project should
|
||||
create additional artifacts with a classifier of <code class="literal">stubs</code> for easy deployment to the maven
|
||||
repository.</p><p>Here is a sample configuration:</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><plugin></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><groupId></span>org.springframework.cloud<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></groupId></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><artifactId></span>spring-cloud-contract-maven-plugin<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></artifactId></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"><version></span>${verifier-plugin.version}<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></version></span>
|
||||
@@ -421,7 +515,7 @@ easy deploy to maven repository.</p><p>Sample configuration:</p><pre class="prog
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></goals></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></execution></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></executions></span>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p>When present, json stubs can be used in consumer automated tests.</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RunWith(SpringTestRunner.class)</span></em>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-tag"></plugin></span></pre><p>When present, JSON stubs can be used in consumer automated tests, as shown here:</p><pre class="programlisting"><em><span class="hl-annotation" style="color: gray">@RunWith(SpringTestRunner.class)</span></em>
|
||||
<em><span class="hl-annotation" style="color: gray">@SpringBootTest</span></em>
|
||||
<em><span class="hl-annotation" style="color: gray">@AutoConfigureStubRunner</span></em>
|
||||
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">public</span> <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">class</span> LoanApplicationServiceTests {
|
||||
@@ -440,14 +534,12 @@ easy deploy to maven repository.</p><p>Sample configuration:</p><pre class="prog
|
||||
assertThat(loanApplication.loanApplicationStatus).isEqualTo(LoanApplicationStatus.LOAN_APPLIED);
|
||||
assertThat(loanApplication.rejectionReason).isNull();
|
||||
}
|
||||
}</pre><p>Underneath <code class="literal">LoanApplication</code> makes a call to the <code class="literal">FraudDetection</code> service. This request is handled by
|
||||
a WireMock server configured using stubs generated by Spring Cloud Contract Verifier.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_scenarios" href="#_scenarios"></a>3.3 Scenarios</h2></div></div></div><p>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.</p><pre class="screen">my_contracts_dir\
|
||||
scenario1\
|
||||
1_login.groovy
|
||||
2_showCart.groovy
|
||||
3_logout.groovy</pre><p>Such tree will cause Spring Cloud Contract Verifier generating WireMock’s scenario with name <code class="literal">scenario1</code> and three steps:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">login marked as <code class="literal">Started</code> pointing to:</li><li class="listitem">showCart marked as <code class="literal">Step1</code> pointing to:</li><li class="listitem">logout marked as <code class="literal">Step2</code> which will close the scenario.</li></ul></div><p>More details about WireMock scenarios can be found under <a class="link" href="http://wiremock.org/stateful-behaviour.html" target="_top">http://wiremock.org/stateful-behaviour.html</a></p><p>Spring Cloud Contract Verifier will also generate tests with guaranteed order of execution.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_stubs_and_transitive_dependencies" href="#_stubs_and_transitive_dependencies"></a>3.4 Stubs and transitive dependencies</h2></div></div></div><p>The Maven and Gradle plugin that we’re created are adding the tasks that create the stubs jar for you. What can be problematic
|
||||
is that when reusing the stubs you can by mistake import all of that stub dependencies! When building a Maven artifact
|
||||
even though you have a couple of different jars, all of them share one pom:</p><pre class="programlisting">├── github-webhook-<span class="hl-number">0.0</span>.<span class="hl-number">1.</span>BUILD-<span class="hl-number">20160903.075506</span>-<span class="hl-number">1</span>-stubs.jar
|
||||
}</pre><p><code class="literal">LoanApplication</code> makes a call to the <code class="literal">FraudDetection</code> service. This request is handled
|
||||
by a WireMock server configured with stubs generated by the Spring Cloud Contract
|
||||
Verifier.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_stubs_and_transitive_dependencies" href="#_stubs_and_transitive_dependencies"></a>3.3 Stubs and Transitive Dependencies</h2></div></div></div><p>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:</p><pre class="programlisting">├── github-webhook-<span class="hl-number">0.0</span>.<span class="hl-number">1.</span>BUILD-<span class="hl-number">20160903.075506</span>-<span class="hl-number">1</span>-stubs.jar
|
||||
├── github-webhook-<span class="hl-number">0.0</span>.<span class="hl-number">1.</span>BUILD-<span class="hl-number">20160903.075506</span>-<span class="hl-number">1</span>-stubs.jar.sha1
|
||||
├── github-webhook-<span class="hl-number">0.0</span>.<span class="hl-number">1.</span>BUILD-<span class="hl-number">20160903.075655</span>-<span class="hl-number">2</span>-stubs.jar
|
||||
├── github-webhook-<span class="hl-number">0.0</span>.<span class="hl-number">1.</span>BUILD-<span class="hl-number">20160903.075655</span>-<span class="hl-number">2</span>-stubs.jar.sha1
|
||||
@@ -455,6 +547,18 @@ even though you have a couple of different jars, all of them share one pom:</p><
|
||||
├── github-webhook-<span class="hl-number">0.0</span>.<span class="hl-number">1.</span>BUILD-SNAPSHOT.pom
|
||||
├── github-webhook-<span class="hl-number">0.0</span>.<span class="hl-number">1.</span>BUILD-SNAPSHOT-stubs.jar
|
||||
├── ...
|
||||
└── ...</pre><p>There are three possibilities of working with those dependencies so as not to have any issues with transitive dependencies.</p><p><span class="strong"><strong>Mark all application dependencies as optional</strong></span></p><p>If in the <code class="literal">github-webhook</code> application we would mark all of our dependencies as optional, when you include the
|
||||
<code class="literal">github-webhook</code> stubs in another application (or when that dependency gets downloaded by Stub Runner) then, since
|
||||
all of the depenencies are optional, they will not get downloaded.</p><p><span class="strong"><strong>Create a separate artifactid for stubs</strong></span></p><p>If you create a separate artifactid then you can set it up in whatever way you wish. For example by having no dependencies at all.</p><p><span class="strong"><strong>Exclude dependencies on the consumer side</strong></span></p><p>As a consumer, if you add the stub dependency to your classpath you can explicitly exclude the unwanted dependencies.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="multi__spring_cloud_contract_verifier_introduction.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="multi__spring_cloud_contract_verifier_messaging.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2. Spring Cloud Contract Verifier Introduction </td><td width="20%" align="center"><a accesskey="h" href="multi_spring-cloud-contract.html">Home</a></td><td width="40%" align="right" valign="top"> 4. Spring Cloud Contract Verifier Messaging</td></tr></table></div></body></html>
|
||||
└── ...</pre><p>There are three possibilities of working with those dependencies so as not to have any
|
||||
issues with transitive dependencies:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Mark all application dependencies as optional</li><li class="listitem">Create a separate artifactid for the stubs</li><li class="listitem">Exclude dependencies on the consumer side</li></ul></div><p><span class="strong"><strong>Mark all application dependencies as optional</strong></span></p><p>If, in the <code class="literal">github-webhook</code> application, you mark all of your dependencies as optional,
|
||||
when you include the <code class="literal">github-webhook</code> 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.</p><p><span class="strong"><strong>Create a separate <code class="literal">artifactid</code> for the stubs</strong></span></p><p>If you create a separate <code class="literal">artifactid</code>, then you can set it up in whatever way you wish.
|
||||
For example, you might decide to have no dependencies at all.</p><p><span class="strong"><strong>Exclude dependencies on the consumer side</strong></span></p><p>As a consumer, if you add the stub dependency to your classpath, you can explicitly
|
||||
exclude the unwanted dependencies.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_scenarios" href="#_scenarios"></a>3.4 Scenarios</h2></div></div></div><p>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, as shown in this example:</p><pre class="screen">my_contracts_dir\
|
||||
scenario1\
|
||||
1_login.groovy
|
||||
2_showCart.groovy
|
||||
3_logout.groovy</pre><p>Such a tree causes Spring Cloud Contract Verifier to generate WireMock’s scenario with a
|
||||
name of <code class="literal">scenario1</code> and the three following steps:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">login marked as <code class="literal">Started</code> pointing to…​</li><li class="listitem">showCart marked as <code class="literal">Step1</code> pointing to…​</li><li class="listitem">logout marked as <code class="literal">Step2</code> which will close the scenario.</li></ol></div><p>More details about WireMock scenarios can be found at
|
||||
<a class="link" href="http://wiremock.org/stateful-behaviour.html" target="_top">http://wiremock.org/stateful-behaviour.html</a></p><p>Spring Cloud Contract Verifier also generates tests with a guaranteed order of execution.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="multi__spring_cloud_contract_verifier_introduction.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="multi__spring_cloud_contract_verifier_messaging.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2. Spring Cloud Contract Verifier Introduction </td><td width="20%" align="center"><a accesskey="h" href="multi_spring-cloud-contract.html">Home</a></td><td width="40%" align="right" valign="top"> 4. Spring Cloud Contract Verifier Messaging</td></tr></table></div></body></html>
|
||||
Reference in New Issue
Block a user