89. Spring Cloud Contract Verifier 设置
您可以通过以下方式设置 Spring Cloud Contract Verifier:
89.1 Gradle 项目
要了解如何为 Spring Cloud Contract Verifier 设置 Gradle 项目,请阅读以下部分:
89.1.1 Prerequisites
为了将 Spring Cloud Contract Verifier 与 WireMock 一起使用,您必须使用 Gradle 或 Maven 插件。
Warning
如果要在项目中使用 Spock,则必须分别添加spock-core
和spock-spring
模块。检查Spock 文档以获取更多信息
89.1.2 添加具有依赖性的 Gradle 插件
要添加具有依赖性的 Gradle 插件,请使用类似于以下代码:
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath "org.springframework.boot:spring-boot-gradle-plugin:${springboot_version}"
classpath "org.springframework.cloud:spring-cloud-contract-gradle-plugin:${verifier_version}"
}
}
apply plugin: 'groovy'
apply plugin: 'spring-cloud-contract'
dependencyManagement {
imports {
mavenBom "org.springframework.cloud:spring-cloud-contract-dependencies:${verifier_version}"
}
}
dependencies {
testCompile 'org.codehaus.groovy:groovy-all:2.4.6'
// example with adding Spock core and Spock Spring
testCompile 'org.spockframework:spock-core:1.0-groovy-2.4'
testCompile 'org.spockframework:spock-spring:1.0-groovy-2.4'
testCompile 'org.springframework.cloud:spring-cloud-starter-contract-verifier'
}
89.1.3 Gradle and Rest Assured 2.0
默认情况下,Rest Assured 3.x 被添加到 Classpath 中。但是,要使用 Rest Assured 2.x,可以将其添加到插件的 classpath 中,如下所示:
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath "org.springframework.boot:spring-boot-gradle-plugin:${springboot_version}"
classpath "org.springframework.cloud:spring-cloud-contract-gradle-plugin:${verifier_version}"
classpath "com.jayway.restassured:rest-assured:2.5.0"
classpath "com.jayway.restassured:spring-mock-mvc:2.5.0"
}
}
depenendencies {
// all dependencies
// you can exclude rest-assured from spring-cloud-contract-verifier
testCompile "com.jayway.restassured:rest-assured:2.5.0"
testCompile "com.jayway.restassured:spring-mock-mvc:2.5.0"
}
这样,该插件会自动看到 Classpath 中存在 Rest Assured 2.x,并相应地修改了导入。
89.1.4 Gradle 的快照版本
将其他快照存储库添加到 build.gradle 以使用快照版本,快照版本在每次成功构建后都会自动上传,如下所示:
buildscript {
repositories {
mavenCentral()
mavenLocal()
maven { url "http://repo.spring.io/snapshot" }
maven { url "http://repo.spring.io/milestone" }
maven { url "http://repo.spring.io/release" }
}
}
89.1.5 添加存根
默认情况下,Spring Cloud Contract Verifier 在src/test/resources/contracts
目录中寻找存根。
包含存根定义的目录被视为类名,每个存根定义均被视为单个测试。 Spring Cloud Contract Verifier 假定它至少包含至少一层用作测试类名称的目录。如果存在多个嵌套目录,则使用除最后一个嵌套目录以外的所有目录作为包名。例如,具有以下结构:
src/test/resources/contracts/myservice/shouldCreateUser.groovy
src/test/resources/contracts/myservice/shouldReturnUser.groovy
Spring Cloud Contract Verifier 使用两种方法创建名为defaultBasePackage.MyService
的测试类:
-
shouldCreateUser()
-
shouldReturnUser()
89.1.6 运行插件
该插件会注册自己,以在check
任务之前被调用。如果您希望它成为构建过程的一部分,则无需执行其他任何操作。如果您只想生成测试,请调用generateContractTests
任务。
89.1.7 默认设置
默认的 Gradle 插件设置会创建构建的以下 Gradle 部分(以伪代码):
contracts {
testFramework ='JUNIT'
testMode = 'MockMvc'
generatedTestSourcesDir = project.file("${project.buildDir}/generated-test-sources/contracts")
generatedTestResourcesDir = project.file("${project.buildDir}/generated-test-resources/contracts")
contractsDslDir = "${project.rootDir}/src/test/resources/contracts"
basePackageForTests = 'org.springframework.cloud.verifier.tests'
stubsOutputDir = project.file("${project.buildDir}/stubs")
// the following properties are used when you want to provide where the JAR with contract lays
contractDependency {
stringNotation = ''
}
contractsPath = ''
contractsWorkOffline = false
contractRepository {
cacheDownloadedContracts(true)
}
}
tasks.create(type: Jar, name: 'verifierStubsJar', dependsOn: 'generateClientStubs') {
baseName = project.name
classifier = contracts.stubsSuffix
from contractVerifier.stubsOutputDir
}
project.artifacts {
archives task
}
tasks.create(type: Copy, name: 'copyContracts') {
from contracts.contractsDslDir
into contracts.stubsOutputDir
}
verifierStubsJar.dependsOn 'copyContracts'
publishing {
publications {
stubs(MavenPublication) {
artifactId project.name
artifact verifierStubsJar
}
}
}
89.1.8 配置插件
要更改默认配置,请在您的 Gradle 配置中添加一个contracts
代码段,如下所示:
contracts {
testMode = 'MockMvc'
baseClassForTests = 'org.mycompany.tests'
generatedTestSourcesDir = project.file('src/generatedContract')
}
89.1.9 配置选项
-
testMode :定义验收测试的模式。默认情况下,该模式是 MockMvc,它基于 Spring 的 MockMvc。对于真实的 HTTP 调用,也可以更改为 WebTestClient , JaxRsClient 或 Explicit 。
-
imports :创建一个带有导入的数组,该数组应包含在生成的测试中(例如['org.myorg.Matchers'])。默认情况下,它创建一个空数组。
-
staticImports :使用静态导入创建一个数组,该数组应包含在生成的测试中(例如['org.myorg.Matchers.*'])。默认情况下,它创建一个空数组。
-
basePackageForTests :指定所有生成的测试的基本软件包。如果未设置,则从
baseClassForTests's package and from `packageWithBaseClasses
中选择该值。如果这些值均未设置,则该值设置为org.springframework.cloud.contract.verifier.tests
。 -
baseClassForTests :为所有生成的测试创建 Base Class。默认情况下,如果使用 Spock 类,则该类为
spock.lang.Specification
。 -
packageWithBaseClasses :定义所有 Base Class 所在的包。此设置优先于 baseClassForTests 。
-
baseClassMappings :显式将 Contract 包 Map 到 Base Class 的 FQN。此设置优先于 packageWithBaseClasses 和 baseClassForTests 。
-
ruleClassForTests :指定应添加到生成的测试类的规则。
-
ignoredFiles :使用
Antmatcher
来定义应跳过处理的存根文件。默认情况下,它是一个空数组。 -
contractsDslDir :指定包含使用 GroovyDSL 编写的 Contract 的目录。默认情况下,其值为
$rootDir/src/test/resources/contracts
。 -
generateTestSourcesDir :指定应放置从 Groovy DSL 生成的测试的测试源目录。默认情况下,其值为
$buildDir/generated-test-sources/contracts
。 -
generatedTestResourcesDir :指定测试资源目录,应放置 Groovy DSL 生成的测试所使用的资源。默认情况下,其值为
$buildDir/generated-test-resources/contracts
。 -
stubsOutputDir :指定应放置 Groovy DSL 生成的 WireMock 存根的目录。
-
testFramework :指定要使用的目标测试框架。当前,Spock,JUnit 4(
TestFramework.JUNIT
)和 JUnit 5 受支持,而 JUnit 4 是默认框架。 -
contractsProperties :包含要传递给 Spring Cloud Contract 组件的属性的 Map。这些属性可能被例如内置或自定义存根下载器。
当您要指定包含 Contract 的 JAR 的位置时,使用以下属性:
-
contractDependency :指定提供
groupid:artifactid:version:classifier
坐标的依赖关系。您可以使用contractDependency
闭包进行设置。 -
contractsPath :指定 jar 的路径。如果下载了 Contract 依存关系,则路径默认为
groupid/artifactid
,其中groupid
以斜杠分隔。否则,它将在提供的目录下扫描 Contract。 -
contractsMode :指定下载 Contract 的方式(JAR 是否可以脱机,远程使用等)。
-
deleteStubsAfterTest :如果设置为
false
,则不会从临时目录中删除任何已下载的 Contract
您可以在下面找到通过插件打开的实验功能列表:
-
convertToYaml :将所有 DSL 转换为声明性的 YAML 格式。当您在 Groovy DSL 中使用外部库时,这可能非常有用。通过启用此功能(将其设置为
true
),您将不需要在使用者端添加库依赖项。 -
assertJsonSize :您可以在生成的测试中检查 JSON 数组的大小。默认情况下禁用此功能。
89.1.10 所有测试的单一 Base Class
在默认的 MockMvc 中使用 Spring Cloud Contract Verifier 时,您需要为所有生成的验收测试创建基本规范。在此类中,您需要指向一个端点,该端点应进行验证。
abstract class BaseMockMvcSpec extends Specification {
def setup() {
RestAssuredMockMvc.standaloneSetup(new PairIdController())
}
void isProperCorrelationId(Integer correlationId) {
assert correlationId == 123456
}
void isEmpty(String value) {
assert value == null
}
}
如果使用Explicit
模式,则可以使用 Base Class 来初始化整个测试的应用程序,就像在常规集成测试中看到的那样。如果使用JAXRSCLIENT
模式,则此 Base Class 也应包含protected WebTarget webTarget
字段。现在,测试 JAX-RS API 的唯一选择是启动 Web 服务器。
89.1.11Contract 的不同基本类别
如果 Contract 之间的 Base Class 不同,则可以告诉 Spring Cloud Contract 插件应通过自动生成的测试扩展哪个类。您有两种选择:
-
按照惯例提供
packageWithBaseClasses
-
通过
baseClassMappings
提供显式 Map
By Convention
约定是这样的:如果您在(例如)src/test/resources/contract/foo/bar/baz/
下有一个 Contract,并且将packageWithBaseClasses
属性的值设置为com.example.base
,那么 Spring Cloud Contract Verifier 会假定com.example.base
包下有一个BarBazBase
类。换句话说,系统将获取包的最后两个部分(如果存在的话),并形成带有Base
后缀的类。此规则优先于 baseClassForTests 。以下是contracts
闭包中的工作方式示例:
packageWithBaseClasses = 'com.example.base'
By Mapping
您可以将 Contract 包的正则表达式手动 Map 到匹配 Contract 的 Base Class 的完全限定名称。您必须提供一个名为baseClassMappings
的列表,该列表由baseClassMapping
个对象组成,这些对象采用contractPackageRegex
到baseClassFQN
的 Map。考虑以下示例:
baseClassForTests = "com.example.FooBase"
baseClassMappings {
baseClassMapping('.*/com/.*', 'com.example.ComBase')
baseClassMapping('.*/bar/.*':'com.example.BarBase')
}
假设您有-src/test/resources/contract/com/
-src/test/resources/contract/foo/
的 Contract
通过提供baseClassForTests
,我们可以进行后备,以防 Map 不成功。 (您也可以提供packageWithBaseClasses
作为后备.)这样,从src/test/resources/contract/com/
Contract 生成的测试扩展了com.example.ComBase
,而其余测试扩展了com.example.FooBase
。
89.1.12 调用生成的测试
为确保提供方符合已定义的 Contract,您需要调用:
./gradlew generateContractTests test
89.1.13 将存根推送到 SCM
如果您使用 SCM 存储库保留 Contract 和存根,则可能需要自动化将存根推入存储库的步骤。为此,只需调用pushStubsToScm
任务即可。例:
$ ./gradlew pushStubsToScm
在第 95.6 节“使用 SCM 存根下载器”下,您可以找到可以通过contractsProperties
字段传递的所有可能的配置选项,例如contracts { contractsProperties = [foo:"bar"] }
,通过contractsProperties
方法,例如contracts { contractsProperties([foo:"bar"]) }
,系统属性或环境变量。
Consumer 方的 Spring CloudContract 验证程序 89.1.14
在消费服务中,您需要以与提供者相同的方式配置 Spring Cloud Contract Verifier 插件。如果您不想使用 Stub Runner,则需要复制存储在src/test/resources/contracts
中的 Contract,并使用以下方法生成 WireMock JSON 存根:
./gradlew generateClientStubs
Note
必须设置stubsOutputDir
选项,才能生成存根。
如果存在,JSON 存根可用于使用服务的自动化测试中。
@ContextConfiguration(loader == SpringApplicationContextLoader, classes == Application)
class LoanApplicationServiceSpec extends Specification {
@ClassRule
@Shared
WireMockClassRule wireMockRule == new WireMockClassRule()
@Autowired
LoanApplicationService sut
def 'should successfully apply for loan'() {
given:
LoanApplication application =
new LoanApplication(client: new Client(clientPesel: '12345678901'), amount: 123.123)
when:
LoanApplicationResult loanApplication == sut.loanApplication(application)
then:
loanApplication.loanApplicationStatus == LoanApplicationStatus.LOAN_APPLIED
loanApplication.rejectionReason == null
}
}
LoanApplication
致电FraudDetection
服务。由 WireMock 服务器处理此请求,该服务器配置有 Spring Cloud Contract Verifier 生成的存根。
89.2 Maven 项目
要了解如何为 Spring Cloud Contract Verifier 设置 Maven 项目,请阅读以下部分:
89.2.1 添加 Maven 插件
以类似于以下方式添加 Spring Cloud Contract BOM:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>${spring-cloud-release.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
接下来,添加Spring Cloud Contract Verifier
Maven 插件:
<plugin>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-contract-maven-plugin</artifactId>
<version>${spring-cloud-contract.version}</version>
<extensions>true</extensions>
<configuration>
<packageWithBaseClasses>com.example.fraud</packageWithBaseClasses>
<convertToYaml>true</convertToYaml>
</configuration>
</plugin>
您可以在Spring Cloud Contract Maven 插件文档(2.0.0.RELEASE 版本的示例)中阅读更多内容。
89.2.2 Maven 和 Rest Assured 2.0
默认情况下,Rest Assured 3.x 被添加到 Classpath 中。但是,可以通过将 Rest Assured 2.x 添加到插件 Classpath 中来使用它,如下所示:
<plugin>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-contract-maven-plugin</artifactId>
<version>${spring-cloud-contract.version}</version>
<extensions>true</extensions>
<configuration>
<packageWithBaseClasses>com.example</packageWithBaseClasses>
</configuration>
<dependencies>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-contract-verifier</artifactId>
<version>${spring-cloud-contract.version}</version>
</dependency>
<dependency>
<groupId>com.jayway.restassured</groupId>
<artifactId>rest-assured</artifactId>
<version>2.5.0</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>com.jayway.restassured</groupId>
<artifactId>spring-mock-mvc</artifactId>
<version>2.5.0</version>
<scope>compile</scope>
</dependency>
</dependencies>
</plugin>
<dependencies>
<!-- all dependencies -->
<!-- you can exclude rest-assured from spring-cloud-contract-verifier -->
<dependency>
<groupId>com.jayway.restassured</groupId>
<artifactId>rest-assured</artifactId>
<version>2.5.0</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.jayway.restassured</groupId>
<artifactId>spring-mock-mvc</artifactId>
<version>2.5.0</version>
<scope>test</scope>
</dependency>
</dependencies>
这样,该插件会自动看到 Classpath 中存在 Rest Assured 3.x,并相应地修改了导入。
89.2.3 Maven 的快照版本
对于 Snapshot 和 Milestone 版本,您必须将以下部分添加到pom.xml
,如下所示:
<repositories>
<repository>
<id>spring-snapshots</id>
<name>Spring Snapshots</name>
<url>https://repo.spring.io/snapshot</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</repository>
<repository>
<id>spring-milestones</id>
<name>Spring Milestones</name>
<url>https://repo.spring.io/milestone</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
<repository>
<id>spring-releases</id>
<name>Spring Releases</name>
<url>https://repo.spring.io/release</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
<pluginRepositories>
<pluginRepository>
<id>spring-snapshots</id>
<name>Spring Snapshots</name>
<url>https://repo.spring.io/snapshot</url>
<snapshots>
<enabled>true</enabled>
</snapshots>
</pluginRepository>
<pluginRepository>
<id>spring-milestones</id>
<name>Spring Milestones</name>
<url>https://repo.spring.io/milestone</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
<pluginRepository>
<id>spring-releases</id>
<name>Spring Releases</name>
<url>https://repo.spring.io/release</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</pluginRepository>
</pluginRepositories>
89.2.4 添加存根
默认情况下,Spring Cloud Contract Verifier 在src/test/resources/contracts
目录中寻找存根。包含存根定义的目录被视为类名,每个存根定义均被视为单个测试。我们假定它至少包含一个目录用作测试类名称。如果嵌套目录有多个级别,则将最后一个嵌套目录用作包名称。例如,具有以下结构:
src/test/resources/contracts/myservice/shouldCreateUser.groovy
src/test/resources/contracts/myservice/shouldReturnUser.groovy
Spring Cloud Contract Verifier 使用两种方法创建名为defaultBasePackage.MyService
的测试类
-
shouldCreateUser()
-
shouldReturnUser()
89.2.5 运行插件
插件目标generateTests
被分配为在名为generate-test-sources
的阶段中被调用。如果您希望它成为构建过程的一部分,则无需执行任何操作。如果只想生成测试,请调用generateTests
目标。
89.2.6 配置插件
要更改默认配置,只需在插件定义或execution
定义中添加configuration
部分,如下所示:
<plugin>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-contract-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>convert</goal>
<goal>generateStubs</goal>
<goal>generateTests</goal>
</goals>
</execution>
</executions>
<configuration>
<basePackageForTests>org.springframework.cloud.verifier.twitter.place</basePackageForTests>
<baseClassForTests>org.springframework.cloud.verifier.twitter.place.BaseMockMvcSpec</baseClassForTests>
</configuration>
</plugin>
89.2.7 配置选项
-
testMode :定义验收测试的模式。默认情况下,该模式是 MockMvc,它基于 Spring 的 MockMvc。对于真实的 HTTP 调用,也可以更改为 WebTestClient , JaxRsClient 或 Explicit 。
-
basePackageForTests :指定所有生成的测试的基本软件包。如果未设置,则从
baseClassForTests's package and from `packageWithBaseClasses
中选择该值。如果这些值均未设置,则该值设置为org.springframework.cloud.contract.verifier.tests
。 -
ruleClassForTests :指定应添加到生成的测试类的规则。
-
baseClassForTests :为所有生成的测试创建 Base Class。默认情况下,如果使用 Spock 类,则该类为
spock.lang.Specification
。 -
contractsDirectory :指定一个目录,其中包含用 GroovyDSL 编写的 Contract。默认目录为
/src/test/resources/contracts
。 -
generateTestSourcesDir :指定应放置从 Groovy DSL 生成的测试的测试源目录。默认情况下,其值为
$buildDir/generated-test-sources/contracts
。 -
generatedTestResourcesDir :指定测试资源目录,测试所使用的资源将在此目录中生成
-
testFramework :指定要使用的目标测试框架。当前,Spock,JUnit 4(
TestFramework.JUNIT
)和 JUnit 5 受支持,而 JUnit 4 是默认框架。 -
packageWithBaseClasses :定义所有 Base Class 所在的包。此设置优先于 baseClassForTests 。约定是这样的,如果您在(例如)
src/test/resources/contract/foo/bar/baz/
下有一个 Contract,并且将packageWithBaseClasses
属性的值设置为com.example.base
,则 Spring Cloud Contract Verifier 假定com.example.base
包下有一个BarBazBase
类。换句话说,系统将获取包的最后两个部分(如果存在的话),并形成带有Base
后缀的类。 -
baseClassMappings :指定 Base ClassMap 的列表,这些 Map 提供
contractPackageRegex
和baseClassFQN
,contractPackageRegex
将根据 Contract 所在的包进行检查,baseClassFQN
Map 到匹配 Contract 的 Base Class 的标准名称。例如,如果您在src/test/resources/contract/foo/bar/baz/
下有一个 Contract 并 Map 了.* → com.example.base.BaseClass
属性,则从这些 Contract 生成的测试类将扩展com.example.base.BaseClass
。此设置优先于 packageWithBaseClasses 和 baseClassForTests 。 -
contractsProperties :包含要传递给 Spring Cloud Contract 组件的属性的 Map。这些属性可能被例如内置或自定义存根下载器。
如果要从 Maven 存储库下载 Contract 定义,则可以使用以下选项:
-
contractDependency :包含所有打包 Contract 的 Contract 依赖关系。
-
contractsPath :具有打包 Contract 的 JAR 中具体 Contract 的路径。默认为
groupid/artifactid
,其中gropuid
以斜杠分隔。 -
contractsMode :选择将在其中找到并注册存根的模式
-
deleteStubsAfterTest :如果设置为
false
,则不会从临时目录中删除任何已下载的 Contract -
contractsRepositoryUrl :包含 Contract 的工件的 repo 的 URL。如果未提供,请使用当前的 Maven。
-
contractsRepositoryUsername :用于通过 Contract 连接到仓库的用户名。
-
contractsRepositoryPassword :用于通过 Contract 连接到仓库的密码。
-
contractsRepositoryProxyHost :用于通过 Contract 连接到仓库的代理主机。
-
contractsRepositoryProxyPort :用于通过 Contract 连接到仓库的代理端口。
我们仅缓存非快照的显式提供的版本(例如+
或1.0.0.BUILD-SNAPSHOT
将不会被缓存)。默认情况下,此功能处于打开状态。
您可以在下面找到通过插件打开的实验功能列表:
-
convertToYaml :将所有 DSL 转换为声明性的 YAML 格式。当您在 Groovy DSL 中使用外部库时,这可能非常有用。通过启用此功能(将其设置为
true
),您将不需要在使用者端添加库依赖项。 -
assertJsonSize :您可以在生成的测试中检查 JSON 数组的大小。默认情况下禁用此功能。
89.2.8 适用于所有测试的单一 Base Class
在默认的 MockMvc 中使用 Spring Cloud Contract Verifier 时,您需要为所有生成的验收测试创建基本规范。在此类中,您需要指向一个端点,该端点应进行验证。
package org.mycompany.tests
import org.mycompany.ExampleSpringController
import com.jayway.restassured.module.mockmvc.RestAssuredMockMvc
import spock.lang.Specification
class MvcSpec extends Specification {
def setup() {
RestAssuredMockMvc.standaloneSetup(new ExampleSpringController())
}
}
如果需要,您还可以设置整个上下文。
import io.restassured.module.mockmvc.RestAssuredMockMvc;
import org.junit.Before;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.web.context.WebApplicationContext;
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT, classes = SomeConfig.class, properties="some=property")
public abstract class BaseTestClass {
@Autowired
WebApplicationContext context;
@Before
public void setup() {
RestAssuredMockMvc.webAppContextSetup(this.context);
}
}
如果使用EXPLICIT
模式,则可以使用 Base Class 类似地初始化整个测试的应用程序,就像在常规集成测试中可能会发现的那样。
import io.restassured.RestAssured;
import org.junit.Before;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.web.server.LocalServerPort
import org.springframework.test.context.junit4.SpringRunner;
import org.springframework.web.context.WebApplicationContext;
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT, classes = SomeConfig.class, properties="some=property")
public abstract class BaseTestClass {
@LocalServerPort
int port;
@Before
public void setup() {
RestAssured.baseURI = "http://localhost:" + this.port;
}
}
如果使用JAXRSCLIENT
模式,则此 Base Class 还应包含protected WebTarget webTarget
字段。现在,测试 JAX-RS API 的唯一选择是启动 Web 服务器。
89.2.9Contract 的不同 Base Class
如果 Contract 之间的 Base Class 不同,则可以告诉 Spring Cloud Contract 插件应通过自动生成的测试扩展哪个类。您有两种选择:
-
按照惯例提供
packageWithBaseClasses
-
通过
baseClassMappings
提供显式 Map
By Convention
约定是这样的:如果您在(例如)src/test/resources/contract/foo/bar/baz/
下有一个 Contract,并且将packageWithBaseClasses
属性的值设置为com.example.base
,那么 Spring Cloud Contract Verifier 会假定com.example.base
包下有一个BarBazBase
类。换句话说,系统将获取包的最后两个部分(如果存在的话),并形成带有Base
后缀的类。此规则优先于 baseClassForTests 。以下是contracts
闭包中的工作方式示例:
<plugin>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-contract-maven-plugin</artifactId>
<configuration>
<packageWithBaseClasses>hello</packageWithBaseClasses>
</configuration>
</plugin>
By Mapping
您可以将 Contract 包的正则表达式手动 Map 到匹配 Contract 的 Base Class 的完全限定名称。您必须提供一个名为baseClassMappings
的列表,该列表由baseClassMapping
个对象组成,这些对象采用contractPackageRegex
到baseClassFQN
的 Map。考虑以下示例:
<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>
假设您在以下两个位置拥有 Contract:* src/test/resources/contract/com/
* src/test/resources/contract/foo/
通过提供baseClassForTests
,我们可以进行后备,以防 Map 不成功。 (您也可以提供packageWithBaseClasses
作为后备.)这样,从src/test/resources/contract/com/
Contract 生成的测试扩展了com.example.ComBase
,而其余测试扩展了com.example.FooBase
。
89.2.10 调用生成的测试
Spring Cloud Contract Maven 插件在名为/generated-test-sources/contractVerifier
的目录中生成验证代码,并将此目录附加到testCompile
目标。
对于 Groovy Spock 代码,请使用以下代码:
<plugin>
<groupId>org.codehaus.gmavenplus</groupId>
<artifactId>gmavenplus-plugin</artifactId>
<version>1.5</version>
<executions>
<execution>
<goals>
<goal>testCompile</goal>
</goals>
</execution>
</executions>
<configuration>
<testSources>
<testSource>
<directory>${project.basedir}/src/test/groovy</directory>
<includes>
<include>**/*.groovy</include>
</includes>
</testSource>
<testSource>
<directory>${project.build.directory}/generated-test-sources/contractVerifier</directory>
<includes>
<include>**/*.groovy</include>
</includes>
</testSource>
</testSources>
</configuration>
</plugin>
为了确保提供方符合已定义的 Contract,您需要调用mvn generateTest test
。
89.2.11 将存根推送到 SCM
如果您使用 SCM 存储库保留 Contract 和存根,则可能需要自动化将存根推入存储库的步骤。为此,添加pushStubsToScm
目标就足够了。例:
<plugin>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-contract-maven-plugin</artifactId>
<version>${spring-cloud-contract.version}</version>
<extensions>true</extensions>
<configuration>
<!-- Base class mappings etc. -->
<!-- We want to pick contracts from a Git repository -->
<contractsRepositoryUrl>git://https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs-contracts-git.git</contractsRepositoryUrl>
<!-- We reuse the contract dependency section to set up the path
to the folder that contains the contract definitions. In our case the
path will be /groupId/artifactId/version/contracts -->
<contractDependency>
<groupId>${project.groupId}</groupId>
<artifactId>${project.artifactId}</artifactId>
<version>${project.version}</version>
</contractDependency>
<!-- The contracts mode can't be classpath -->
<contractsMode>REMOTE</contractsMode>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<!-- By default we will not push the stubs back to SCM,
you have to explicitly add it as a goal -->
<goal>pushStubsToScm</goal>
</goals>
</execution>
</executions>
</plugin>
在第 95.6 节“使用 SCM 存根下载器”下,您可以找到可以通过<configuration><contractProperties>
Map,系统属性或环境变量传递的所有可能的配置选项。
89.2.12 Maven 插件和 STS
如果在使用 STS 时看到以下异常:
当您单击错误标记时,您应该看到类似以下的内容:
plugin:1.1.0.M1:convert:default-convert:process-test-resources) org.apache.maven.plugin.PluginExecutionException: Execution default-convert of goal org.springframework.cloud:spring-
cloud-contract-maven-plugin:1.1.0.M1:convert failed. at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:145) at
org.eclipse.m2e.core.internal.embedder.MavenImpl.execute(MavenImpl.java:331) at org.eclipse.m2e.core.internal.embedder.MavenImpl$11.call(MavenImpl.java:1362) at
...
org.eclipse.core.internal.jobs.Worker.run(Worker.java:55) Caused by: java.lang.NullPointerException at
org.eclipse.m2e.core.internal.builder.plexusbuildapi.EclipseIncrementalBuildContext.hasDelta(EclipseIncrementalBuildContext.java:53) at
org.sonatype.plexus.build.incremental.ThreadBuildContext.hasDelta(ThreadBuildContext.java:59) at
为了解决此问题,请在您的pom.xml
中提供以下部分:
<build>
<pluginManagement>
<plugins>
<!--This plugin's configuration is used to store Eclipse m2e settings
only. It has no influence on the Maven build itself. -->
<plugin>
<groupId>org.eclipse.m2e</groupId>
<artifactId>lifecycle-mapping</artifactId>
<version>1.0.0</version>
<configuration>
<lifecycleMappingMetadata>
<pluginExecutions>
<pluginExecution>
<pluginExecutionFilter>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-contract-maven-plugin</artifactId>
<versionRange>[1.0,)</versionRange>
<goals>
<goal>convert</goal>
</goals>
</pluginExecutionFilter>
<action>
<execute />
</action>
</pluginExecution>
</pluginExecutions>
</lifecycleMappingMetadata>
</configuration>
</plugin>
</plugins>
</pluginManagement>
</build>
89.2.13 具有 Spock 测试的 Maven 插件
您可以选择Spock Framework来使用 Maven 和 Gradle 插件创建和执行自动生成的 Contract 验证测试。但是,尽管使用 Gradle 非常简单,但是在 Maven 中,您将需要一些其他设置才能使测试正确编译和执行。
首先,您将必须使用一个插件(例如GMavenPlus插件)将 Groovy 添加到您的项目中。在 GMavenPlus 插件中,您将需要显式设置测试源,包括定义基本测试类的路径和添加了生成的 Contract 测试的路径。请参考以下示例:
<plugin>
<groupId>org.codehaus.gmavenplus</groupId>
<artifactId>gmavenplus-plugin</artifactId>
<version>1.6.1</version>
<executions>
<execution>
<goals>
<goal>compileTests</goal>
<goal>addTestSources</goal>
</goals>
</execution>
</executions>
<configuration>
<testSources>
<testSource>
<directory>${project.basedir}/src/test/groovy</directory>
<includes>
<include>**/*.groovy</include>
</includes>
</testSource>
<testSource>
<directory>
${project.basedir}/target/generated-test-sources/contracts/com/example/beer
</directory>
<includes>
<include>**/*.groovy</include>
<include>**/*.gvy</include>
</includes>
</testSource>
</testSources>
</configuration>
<dependencies>
<dependency>
<groupId>org.codehaus.groovy</groupId>
<artifactId>groovy-all</artifactId>
<version>2.4.15</version>
<scope>runtime</scope>
<type>pom</type>
</dependency>
</dependencies>
如果您坚持使用Spec
结束测试类名称的 Spock 约定,则还需要调整 Maven Surefire 插件设置,如以下示例所示:
89.3 存根和传递依赖项
Maven 和 Gradle 插件可添加为您创建存根 jar 的任务。出现的一个问题是,当重用存根时,您可能会错误地导入该存根的所有依赖关系。在构建 Maven 工件时,即使您有几个不同的 jar,它们都共享一个 pom:
├── github-webhook-0.0.1.BUILD-20160903.075506-1-stubs.jar
├── github-webhook-0.0.1.BUILD-20160903.075506-1-stubs.jar.sha1
├── github-webhook-0.0.1.BUILD-20160903.075655-2-stubs.jar
├── github-webhook-0.0.1.BUILD-20160903.075655-2-stubs.jar.sha1
├── github-webhook-0.0.1.BUILD-SNAPSHOT.jar
├── github-webhook-0.0.1.BUILD-SNAPSHOT.pom
├── github-webhook-0.0.1.BUILD-SNAPSHOT-stubs.jar
├── ...
└── ...
使用这些依赖项有三种可能性,以使传递依赖项没有任何问题:
-
将所有应用程序依赖项标记为可选
-
为存根创建一个单独的 artifactid
-
排除 Consumer 方面的依赖
将所有应用程序依赖项标记为可选
如果在github-webhook
应用程序中将所有依赖项标记为可选,则在另一个应用程序中包含github-webhook
存根时(或当 Stub Runner 下载该依赖项时),则由于所有依赖项都是可选的,因此它们将不会得到已下载。
为存根创建单独的artifactid
如果您创建单独的artifactid
,则可以按照您希望的任何方式进行设置。例如,您可能决定完全没有依赖项。
排除 Consumer 方面的依赖
作为使用者,如果将存根依赖项添加到 Classpath 中,则可以显式排除不需要的依赖项。
89.4 Scenarios
您可以使用 Spring Cloud Contract Verifier 处理方案。您需要做的就是在创建 Contract 时遵循正确的命名约定。约定要求在订货号后加上下划线。无论您使用的是 YAML 还是 Groovy,这都将起作用。例:
my_contracts_dir\
scenario1\
1_login.groovy
2_showCart.groovy
3_logout.groovy
这样的树使 Spring Cloud Contract Verifier 生成名称为scenario1
的 WireMock 场景,并执行以下三个步骤:
-
标记为
Started
的登录指向… -
标记为
Step1
的 showCart 指向… -
标记为
Step2
的注销将关闭方案。
有关 WireMock 方案的更多详细信息,请参见http://wiremock.org/docs/stateful-behaviour/
Spring Cloud Contract Verifier 还会生成具有保证执行 Sequences 的测试。
89.5 Docker 项目
我们正在发布springcloud/spring-cloud-contract
Docker 映像,其中包含一个项目,该项目将生成测试并针对正在运行的应用程序以EXPLICIT
模式执行测试。
Tip
EXPLICIT
模式意味着从 Contract 生成的测试将发送真实的请求,而不是模拟的请求。
89.5.1 Maven,JAR 和二进制存储的简短介绍
由于 Docker 映像可由非 JVM 项目使用,因此最好解释一下 Spring Cloud Contract 打包默认设置背后的基本术语。
以下定义的一部分取自Maven Glossary
-
Project
:Maven 考虑项目。您将构建的所有内容都是项目。这些项目遵循定义明确的“项目对象模型”。项目可以依赖于其他项目,在这种情况下,后者称为“依赖项”。一个项目可能与几个子项目一致,但是这些子项目仍被视为项目。 -
Artifact
:工件是项目产生或使用的东西。 Maven 为项目生成的工件的示例包括:JAR,源代码和二进制发行版。每个工件都由组 ID 和组内唯一的工件 ID 唯一标识。 -
JAR
:JAR 代表 Java ARchive。这是一种基于 ZIP 文件格式的格式。 Spring Cloud Contract 将 Contract 和生成的存根打包在 JAR 文件中。 -
GroupId
:组 ID 是项目的通用唯一标识符。尽管这通常只是项目名称(例如 commons-collections),但使用完全合格的程序包名称将其与具有类似名称的其他项目(例如 org.apache.maven)区分开是很有帮助的。通常,发布到 Artifact Manager 时,GroupId
将被斜线分隔并构成 URL 的一部分。例如。对于组 IDcom.example
和工件 IDapplication
将为/com/example/application/
。 -
Classifier
:Maven 依赖项表示法如下:groupId:artifactId:version:classifier
。分类器是传递给依赖项的附加后缀。例如。stubs
,sources
。相同的依赖关系com.example:application
会产生多个分类器彼此不同的工件。 -
Artifact manager
:生成二进制文件/源代码/软件包时,希望其他人可以下载/引用或重用它们。在 JVM 的情况下,这些工件将是 JAR,对于 Ruby 而言,它们是宝石,对于 Docker,则是 Docker 映像。您可以将这些工件存储在 Management 器中。此类 Management 器的示例可以是Artifactory或Nexus。
89.5.2 工作原理
该图像在/contracts
文件夹下搜索 Contract。运行测试的输出将在/spring-cloud-contract/build
文件夹下提供(对于调试目的很有用)。
挂载 Contract,传递环境变量就足够了,该映像将:
-
生成 Contract 测试
-
针对提供的 URL 执行测试
-
产生WireMock个存根
-
(可选-默认情况下处于启用状态)将存根发布到 Artifact Manager
Environment Variables
Docker 映像需要一些环境变量以指向您正在运行的应用程序,工件 Management 器实例等。
-
PROJECT_GROUP
-您的项目的组 ID。默认为com.example
-
PROJECT_VERSION
-您项目的版本。默认为0.0.1-SNAPSHOT
-
PROJECT_NAME
-工件 ID。默认为example
-
REPO_WITH_BINARIES_URL
-Artifact Manager 的网址。默认为http://localhost:8081/artifactory/libs-release-local
,这是本地运行的Artifactory的默认 URL -
REPO_WITH_BINARIES_USERNAME
-(可选)保护 Artifact Manager 的用户名 -
REPO_WITH_BINARIES_PASSWORD
-(安全的 Artifact Manager)密码(可选) -
PUBLISH_ARTIFACTS
-如果设置为true
,则会将工件发布到二进制存储。默认为true
。
当 Contract 位于外部存储库中时,将使用这些环境变量。要启用此功能,必须设置EXTERNAL_CONTRACTS_ARTIFACT_ID
环境变量。
-
EXTERNAL_CONTRACTS_GROUP_ID
-带有 Contract 的项目的组 ID。默认为com.example
-
EXTERNAL_CONTRACTS_ARTIFACT_ID
-带有 Contract 的项目的工件 ID。 -
EXTERNAL_CONTRACTS_CLASSIFIER
-带有 Contract 的项目分类。默认为空 -
EXTERNAL_CONTRACTS_VERSION
-带有 Contract 的项目版本。默认为+
,相当于选择最新的 -
EXTERNAL_CONTRACTS_REPO_WITH_BINARIES_URL
-Artifact Manager 的网址。默认值为REPO_WITH_BINARIES_URL
env var。如果未设置,则默认为http://localhost:8081/artifactory/libs-release-local
,这是本地运行的Artifactory的默认 URL -
EXTERNAL_CONTRACTS_PATH
-包含 Contract 的项目内给定项目的 Contract 路径。默认为斜线分隔的EXTERNAL_CONTRACTS_GROUP_ID
与/
和EXTERNAL_CONTRACTS_ARTIFACT_ID
串联。例如。对于组 IDfoo.bar
和工件 IDbaz
,将导致foo/bar/baz
Contract 路径。 -
EXTERNAL_CONTRACTS_WORK_OFFLINE
-如果设置为true
,则将从容器的.m2
中检索带有 Contract 的工件。将本地.m2
作为卷安装在容器的/root/.m2
路径上。您不能同时设置EXTERNAL_CONTRACTS_WORK_OFFLINE
和EXTERNAL_CONTRACTS_REPO_WITH_BINARIES_URL
。
执行测试时使用以下环境变量:
-
APPLICATION_BASE_URL
-应对其执行测试的 URL。请记住,必须可以从 Docker 容器访问它(例如localhost
将不起作用) -
APPLICATION_USERNAME
-(可选)用于对应用程序进行基本身份验证的用户名 -
APPLICATION_PASSWORD
-(可选)用于对应用程序进行基本身份验证的密码
89.5.3 使用示例
让我们看一个简单的 MVC 应用程序
$ git clone https://github.com/spring-cloud-samples/spring-cloud-contract-nodejs
$ cd bookstore
Contract 位于/contracts
文件夹下。
89.5.4 服务器端(nodejs)
因为我们要运行测试,所以我们可以执行:
$ npm test
但是,出于学习目的,让我们将其分为几部分:
# Stop docker infra (nodejs, artifactory)
$ ./stop_infra.sh
# Start docker infra (nodejs, artifactory)
$ ./setup_infra.sh
# Kill & Run app
$ pkill -f "node app"
$ nohup node app &
# Prepare environment variables
$ SC_CONTRACT_DOCKER_VERSION="..."
$ APP_IP="192.168.0.100"
$ APP_PORT="3000"
$ ARTIFACTORY_PORT="8081"
$ APPLICATION_BASE_URL="http://${APP_IP}:${APP_PORT}"
$ ARTIFACTORY_URL="http://${APP_IP}:${ARTIFACTORY_PORT}/artifactory/libs-release-local"
$ CURRENT_DIR="$( pwd )"
$ CURRENT_FOLDER_NAME=${PWD##*/}
$ PROJECT_VERSION="0.0.1.RELEASE"
# Execute contract tests
$ docker run --rm -e "APPLICATION_BASE_URL=${APPLICATION_BASE_URL}" -e "PUBLISH_ARTIFACTS=true" -e "PROJECT_NAME=${CURRENT_FOLDER_NAME}" -e "REPO_WITH_BINARIES_URL=${ARTIFACTORY_URL}" -e "PROJECT_VERSION=${PROJECT_VERSION}" -v "${CURRENT_DIR}/contracts/:/contracts:ro" -v "${CURRENT_DIR}/node_modules/spring-cloud-contract/output:/spring-cloud-contract-output/" springcloud/spring-cloud-contract:"${SC_CONTRACT_DOCKER_VERSION}"
# Kill app
$ pkill -f "node app"
将会发生的是通过 bash 脚本:
-
基础设施将被构建(MongoDb,Artifactory)。在现实生活中,您只需运行带有模拟数据库的 NodeJS 应用程序。在此示例中,我们想展示如何立即受益于 Spring Cloud Contract。
-
由于这些限制,Contract 也代表了有状态的情况
-
第一个请求是
POST
,它导致数据被插入到数据库中- 第二个请求是
GET
,该列表返回具有 1 个先前插入的元素的数据列表
- 第二个请求是
-
NodeJS 应用程序将启动(在端口
3000
上) -
Contract 测试将通过 Docker 生成,并且测试将针对正在运行的应用程序执行
-
Contract 将从
/contracts
文件夹中提取。- 测试执行的输出在
node_modules/spring-cloud-contract/output
下可用。
- 测试执行的输出在
-
存根将被上传到 Artifactory。您可以在http://localhost:8081/artifactory/libs-release-local/com/example/bookstore/0.0.1.RELEASE/下检出它们。存根将在此处http://localhost:8081/artifactory/libs-release-local/com/example/bookstore/0.0.1.RELEASE/bookstore-0.0.1.RELEASE-stubs.jar。
要查看 Client 端的外观,请查看第 91.9 节“ Stub Runner Docker”部分。