From 93652ac0fb4c791fe948a23ade2d0de4e747c91d Mon Sep 17 00:00:00 2001 From: Marcin Grzejszczak Date: Fri, 23 Sep 2016 15:57:16 +0200 Subject: [PATCH] Sync docs from master to gh-pages --- spring-cloud-contract.html | 178 +++++++++++++++++++++++++++++++++++-- 1 file changed, 169 insertions(+), 9 deletions(-) diff --git a/spring-cloud-contract.html b/spring-cloud-contract.html index 147768f80e..19de77d06d 100644 --- a/spring-cloud-contract.html +++ b/spring-cloud-contract.html @@ -474,6 +474,7 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
  • Producer
    • +
  • Can I have multiple base classes for tests?
    • @@ -495,7 +496,8 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
  • Configure plugin
  • Invoking generated tests
    • @@ -514,7 +516,8 @@ body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-b
  • Configure plugin
  • Invoking generated tests
    • @@ -1293,7 +1296,7 @@ It’s really important that you understand the map notation to set up contr <version>${spring-cloud-contract.version}</version> <extensions>true</extensions> <configuration> - <baseClassForTests>com.example.fraud.MvcTest</baseClassForTests> + <packageWithBaseClasses>com.example.fraud</packageWithBaseClasses> </configuration> </plugin> @@ -1479,7 +1482,7 @@ git pull https://your-git-server.com/server-side-fork.git contract-change-pr @@ -1496,7 +1499,7 @@ import com.jayway.restassured.module.mockmvc.RestAssuredMockMvc; import org.junit.Before; -public class MvcTest { +public class FraudBase { @Before public void setup() { @@ -2323,6 +2326,13 @@ when some incompatible changes are done.

    +
    +
    Can I have multiple base classes for tests?
    +
    +

    Yes! Check out the Different base classes for contracts sections +of either Gradle or Maven plugins.

    +
    +
    @@ -2559,7 +2569,13 @@ publishing {

    basePackageForTests - specifies base package for all generated tests. By default set to org.springframework.cloud.verifier.tests

  • -

    baseClassForTests - base class for generated tests. By default spock.lang.Specification if using Spock tests.

    +

    baseClassForTests - base class for all generated tests. By default spock.lang.Specification if using Spock tests.

    +
    • +
  • +

    packageWithBaseClasses - instead of providing a fixed value for base class you can provide a package where all the base classes lay. Takes precedence over baseClassForTests.

    +
    • +
  • +

    baseClassMappings - explicitly map contract package to a FQN of a base class. Takes precedence over packageWithBaseClasses and baseClassForTests.

  • ruleClassForTests - specifies Rule which should be added to generated test classes.

    @@ -2599,7 +2615,7 @@ publishing {
    • -
    Base class for tests
    +
    Single base class for all tests

    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.

    @@ -2627,6 +2643,62 @@ publishing { should also contain protected WebTarget webTarget field, right now the only option to test JAX-RS API is to start a web server.

    +
    +
    Different base classes for contracts
    +
    +

    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:

    +
    +
    +
      +
    • +

      follow a convention by providing the packageWithBaseClasses

      +
      • +
    • +

      provide explicit mapping via baseClassMappings

      +
      • +
    +
    +
    +

    Convention

    +
    +
    +

    The convention is such that if you have a contract under e.g. src/test/resources/contract/foo/bar/baz/ and provide the value of the packageWithBaseClasses property +to com.example.base then we will assume that there is a BarBazBase class under com.example.base package. In other words we take last two parts of package +if they exist and form a class with a Base suffix. Takes precedence over baseClassForTests. Example of usage in the contracts closure:

    +
    +
    +
    +
    packageWithBaseClasses = 'com.example.base'
    +
    +
    +
    +

    Mapping

    +
    +
    +

    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:

    +
    +
    +
    +
    baseClassForTests = "com.example.FooBase"
+baseClassMappings {
+	baseClassMapping('.*/com/.*', 'com.example.ComBase')
+	baseClassMapping('.*/bar/.*':'com.example.BarBase')
+}
    +
    +
    +
    +

    Let’s assume that you have contracts under + - src/test/resources/contract/com/ + - src/test/resources/contract/foo/

    +
    +
    +

    By providing the baseClassForTests we have a fallback in case mapping didn’t succeed (you could also provide +the packageWithBaseClasses as fallback). That way the tests generated from src/test/resources/contract/com/ contracts +will be extending the com.example.ComBase whereas the rest of tests will extend com.example.FooBase.

    +
    +
    Invoking generated tests
    @@ -2719,7 +2791,7 @@ class LoanApplicationServiceSpec extends Specification { <version>${spring-cloud-contract.version}</version> <extensions>true</extensions> <configuration> - <baseClassForTests>com.example.fraud.MvcTest</baseClassForTests> + <packageWithBaseClasses>com.example.fraud</packageWithBaseClasses> </configuration> </plugin>
    @@ -2864,6 +2936,19 @@ src/test/resources/contracts/myservice/shouldReturnUser.groovy

  • testFramework - the target test framework to be used; currently Spock and JUnit are supported with JUnit being the default framework

    • +
  • +

    packageWithBaseClasses - 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 src/test/resources/contract/foo/bar/baz/ and provide the value of this property +to com.example.base then we will assume that there is a BarBazBase class under com.example.base package. Takes precedence +over baseClassForTests

    +
    • +
  • +

    baseClassMappings - list of base class mappings that where you have to provide contractPackageRegex which is checked +against the package in which the contract lays and baseClassFQN that maps to fully qualified name of the base class for the matched +contract. If you have a contract under src/test/resources/contract/foo/bar/baz/ and map the property .* → com.example.base.BaseClass then +the test class generated from these contracts will extend com.example.base.BaseClass. Takes precedence over packageWithBaseClasses + and baseClassForTests.

    +
    • @@ -2890,7 +2975,7 @@ src/test/resources/contracts/myservice/shouldReturnUser.groovy
    -
    Base class for tests
    +
    Single base class for all tests

    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.

    @@ -2914,6 +2999,81 @@ class MvcSpec extends Specification {

    In case of using Explicit mode, you can use base class to initialize the whole tested app similarly as in regular integration tests. In case of JAXRSCLIENT mode this base class should also contain protected WebTarget webTarget field, right now the only option to test JAX-RS API is to start a web server.

    +
    +
    Different base classes for contracts
    +
    +

    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:

    +
    +
    +
      +
    • +

      follow a convention by providing the packageWithBaseClasses

      +
      • +
    • +

      provide explicit mapping via baseClassMappings

      +
      • +
    +
    +
    +

    Convention

    +
    +
    +

    The convention is such that if you have a contract under e.g. src/test/resources/contract/hello/v1/ and provide the value of the packageWithBaseClasses property +to hello then we will assume that there is a HelloV1Base class under hello package. In other words we take last two parts of package +if they exist and form a class with a Base suffix. Takes precedence over baseClassForTests. Example of usage in the contracts closure:

    +
    +
    +
    +
    			<plugin>
+				<groupId>org.springframework.cloud</groupId>
+				<artifactId>spring-cloud-contract-maven-plugin</artifactId>
+				<configuration>
+					<packageWithBaseClasses>hello</packageWithBaseClasses>
+				</configuration>
+			</plugin>
+		</plugins>
+	</build>
+
+</project>
    +
    +
    +
    +

    Mapping

    +
    +
    +

    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 baseClassMappings of baseClassMapping that takes a contractPackageRegex to baseClassFQN mapping. +Let’s take a look at the following example:

    +
    +
    +
    +
    <plugin>
+	<groupId>org.springframework.cloud</groupId>
+	<artifactId>spring-cloud-contract-maven-plugin</artifactId>
+	<configuration>
+		<baseClassForTests>com.example.FooBase</baseClassForTests>
+		<baseClassMappings>
+			<baseClassMapping>
+				<contractPackageRegex>.*com.*</contractPackageRegex>
+				<baseClassFQN>com.example.TestBase</baseClassFQN>
+			</baseClassMapping >
+		</baseClassMappings>
+	</configuration>
+</plugin>
    +
    +
    +
    +

    Let’s assume that you have contracts under + - src/test/resources/contract/com/ + - src/test/resources/contract/foo/

    +
    +
    +

    By providing the baseClassForTests we have a fallback in case mapping didn’t succeed (you could also provide +the packageWithBaseClasses as fallback). That way the tests generated from src/test/resources/contract/com/ contracts +will be extending the com.example.ComBase whereas the rest of tests will extend com.example.FooBase.

    +
    +
    Invoking generated tests