对于最新的稳定版本,请使用 spring-cloud-contract 4.2.0! |
使用可插拔架构
您可能会遇到您的合约以其他格式定义的情况, 例如 YAML、RAML 或 PACT。在这些情况下,您仍然希望从自动 生成测试和存根。您可以添加自己的实现来生成两者 测试和存根。此外,您还可以自定义测试的生成方式(例如,您 可以为其他语言生成测试)和存根的生成方式(例如,您 可以为其他 HTTP 服务器实现生成存根)。
自定义合约转换器
这ContractConverter
interface 允许您注册自己的合约实现
结构转换器。以下代码清单显示了ContractConverter
接口:
import java.io.File;
import java.util.Collection;
/**
* Converter to be used to convert FROM {@link File} TO {@link Contract} and from
* {@link Contract} to {@code T}.
*
* @param <T> - type to which we want to convert the contract
* @author Marcin Grzejszczak
* @since 1.1.0
*/
public interface ContractConverter<T> extends ContractStorer<T>, ContractReader<T> {
/**
* Should this file be accepted by the converter. Can use the file extension to check
* if the conversion is possible.
* @param file - file to be considered for conversion
* @return - {@code true} if the given implementation can convert the file
*/
boolean isAccepted(File file);
/**
* Converts the given {@link File} to its {@link Contract} representation.
* @param file - file to convert
* @return - {@link Contract} representation of the file
*/
Collection<Contract> convertFrom(File file);
/**
* Converts the given {@link Contract} to a {@link T} representation.
* @param contract - the parsed contract
* @return - {@link T} the type to which we do the conversion
*/
T convertTo(Collection<Contract> contract);
}
Your implementation must define the condition on which it should start the
conversion. Also, you must define how to perform that conversion in both directions.
Once you create your implementation, you must create a
/META-INF/spring.factories
file in which you provide the fully qualified name of your
implementation.
The following example shows a typical spring.factories
file:
org.springframework.cloud.contract.spec.ContractConverter=\
org.springframework.cloud.contract.verifier.converter.YamlContractConverter
Using the Custom Test Generator
If you want to generate tests for languages other than Java or you are not happy with the
way the verifier builds Java tests, you can register your own implementation.
The SingleTestGenerator
interface lets you register your own implementation. The
following code listing shows the SingleTestGenerator
interface:
import java.nio.file.Path;
import java.util.Collection;
import org.springframework.cloud.contract.verifier.config.ContractVerifierConfigProperties;
import org.springframework.cloud.contract.verifier.file.ContractMetadata;
/**
* Builds a single test.
*
* @since 1.1.0
*/
public interface SingleTestGenerator {
/**
* Creates contents of a single test class in which all test scenarios from the
* contract metadata should be placed.
* @param properties - properties passed to the plugin
* @param listOfFiles - list of parsed contracts with additional metadata
* @param generatedClassData - information about the generated class
* @param includedDirectoryRelativePath - relative path to the included directory
* @return contents of a single test class
*/
String buildClass(ContractVerifierConfigProperties properties, Collection<ContractMetadata> listOfFiles,
String includedDirectoryRelativePath, GeneratedClassData generatedClassData);
class GeneratedClassData {
public final String className;
public final String classPackage;
public final Path testClassPath;
public GeneratedClassData(String className, String classPackage, Path testClassPath) {
this.className = className;
this.classPackage = classPackage;
this.testClassPath = testClassPath;
}
}
}
Again, you must provide a spring.factories
file, such as the one shown in the following
example:
org.springframework.cloud.contract.verifier.builder.SingleTestGenerator=/
com.example.MyGenerator
Using the Custom Stub Generator
If you want to generate stubs for stub servers other than WireMock, you can plug in your
own implementation of the StubGenerator
interface. The following code listing shows the
StubGenerator
interface:
import java.io.File;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
import org.springframework.cloud.contract.spec.Contract;
import org.springframework.cloud.contract.verifier.file.ContractMetadata;
/**
* Converts contracts into their stub representation.
*
* @param <T> - type of stub mapping
* @since 1.1.0
*/
public interface StubGenerator<T> {
/**
* @param mapping - potential stub mapping mapping
* @return {@code true} if this converter could have generated this mapping stub.
*/
default boolean canReadStubMapping(File mapping) {
return mapping.getName().endsWith(fileExtension());
}
/**
* @param rootName - root name of the contract
* @param content - metadata of the contract
* @return the collection of converted contracts into stubs. One contract can result
* in multiple stubs.
*/
Map<Contract, String> convertContents(String rootName, ContractMetadata content);
/**
* Post process a generated stub mapping.
* @param stubMapping - mapping of a stub
* @param contract - contract for which stub was generated
* @return the converted stub mapping
*/
default T postProcessStubMapping(T stubMapping, Contract contract) {
List<StubPostProcessor> processors = StubPostProcessor.PROCESSORS.stream()
.filter(p -> p.isApplicable(contract))
.collect(Collectors.toList());
if (processors.isEmpty()) {
return defaultStubMappingPostProcessing(stubMapping, contract);
}
T stub = stubMapping;
for (StubPostProcessor processor : processors) {
stub = (T) processor.postProcess(stub, contract);
}
return stub;
}
/**
* Stub mapping to chose when no post processors where found on the classpath.
* @param stubMapping - mapping of a stub
* @param contract - contract for which stub was generated
* @return the converted stub mapping
*/
default T defaultStubMappingPostProcessing(T stubMapping, Contract contract) {
return stubMapping;
}
/**
* @param inputFileName - name of the input file
* @return the name of the converted stub file. If you have multiple contracts in a
* single file then a prefix will be added to the generated file. If you provide the
* {@link Contract#getName} field then that field will override the generated file
* name.
*
* Example: name of file with 2 contracts is {@code foo.groovy}, it will be converted
* by the implementation to {@code foo.json}. The recursive file converter will create
* two files {@code 0_foo.json} and {@code 1_foo.json}
*/
String generateOutputFileNameForInput(String inputFileName);
/**
* Describes the file extension of the generated mapping that this stub generator can
* handle.
* @return string describing the file extension
*/
default String fileExtension() {
return ".json";
}
}
Again, you must provide a spring.factories
file, such as the one shown in the following
example:
# Stub converters
org.springframework.cloud.contract.verifier.converter.StubGenerator=\
org.springframework.cloud.contract.verifier.wiremock.DslToWireMockClientConverter
The default implementation is the WireMock stub generation.
You can provide multiple stub generator implementations. For example, from a single
DSL, you can produce both WireMock stubs and Pact files.
Using the Custom Stub Runner
If you decide to use custom stub generation, you also need a custom way of running
stubs with your different stub provider.
Assume that you use Moco to build your stubs and that
you have written a stub generator and placed your stubs in a JAR file.
In order for Stub Runner to know how to run your stubs, you have to define a custom
HTTP Stub server implementation, which might resemble the following example:
import com.github.dreamhead.moco.bootstrap.arg.HttpArgs
import com.github.dreamhead.moco.runner.JsonRunner
import com.github.dreamhead.moco.runner.RunnerSetting
import groovy.transform.CompileStatic
import groovy.util.logging.Commons
import org.springframework.cloud.contract.stubrunner.HttpServerStub
import org.springframework.cloud.contract.stubrunner.HttpServerStubConfiguration
@Commons
@CompileStatic
class MocoHttpServerStub implements HttpServerStub {
private boolean started
private JsonRunner runner
private int port
@Override
int port() {
if (!isRunning()) {
return -1
}
return port
}
@Override
boolean isRunning() {
return started
}
@Override
HttpServerStub start(HttpServerStubConfiguration configuration) {
this.port = configuration.port
return this
}
@Override
HttpServerStub stop() {
if (!isRunning()) {
return this
}
this.runner.stop()
return this
}
@Override
HttpServerStub registerMappings(Collection<File> stubFiles) {
List<RunnerSetting> settings = stubFiles.findAll { it.name.endsWith("json") }
.collect {
log.info("Trying to parse [${it.name}]")
try {
return RunnerSetting.aRunnerSetting().addStream(it.newInputStream()).
build()
}
catch (Exception e) {
log.warn("Exception occurred while trying to parse file [${it.name}]", e)
return null
}
}.findAll { it }
this.runner = JsonRunner.newJsonRunnerWithSetting(settings,
HttpArgs.httpArgs().withPort(this.port).build())
this.runner.run()
this.started = true
return this
}
@Override
String registeredMappings() {
return ""
}
@Override
boolean isAccepted(File file) {
return file.name.endsWith(".json")
}
}
Then you can register it in your spring.factories
file, as the following
example shows:
org.springframework.cloud.contract.stubrunner.HttpServerStub=\
org.springframework.cloud.contract.stubrunner.provider.moco.MocoHttpServerStub
Now you can run stubs with Moco.
If you do not provide any implementation, the default (WireMock)
implementation is used. If you provide more than one, the first one on the list is used.
Using the Custom Stub Downloader
You can customize the way your stubs are downloaded by creating an implementation of the
StubDownloaderBuilder
interface, as the following example shows:
class CustomStubDownloaderBuilder implements StubDownloaderBuilder {
@Override
public StubDownloader build(final StubRunnerOptions stubRunnerOptions) {
return new StubDownloader() {
@Override
public Map.Entry<StubConfiguration, File> downloadAndUnpackStubJar(
StubConfiguration config) {
File unpackedStubs = retrieveStubs();
return new AbstractMap.SimpleEntry<>(
new StubConfiguration(config.getGroupId(), config.getArtifactId(), version,
config.getClassifier()), unpackedStubs);
}
File retrieveStubs() {
// here goes your custom logic to provide a folder where all the stubs reside
}
}
}
}
Then you can register it in your spring.factories
file, as the following
example shows:
# Example of a custom Stub Downloader Provider
org.springframework.cloud.contract.stubrunner.StubDownloaderBuilder=\
com.example.CustomStubDownloaderBuilder
Now you can pick a folder with the source of your stubs.
If you do not provide any implementation, the default (scanning the classpath) is used.
If you provide the stubsMode = StubRunnerProperties.StubsMode.LOCAL
or
stubsMode = StubRunnerProperties.StubsMode.REMOTE
, the Aether implementation is used
If you provide more than one, the first one on the list is used.
Using the SCM Stub Downloader
Whenever the repositoryRoot
starts with a SCM protocol
(currently, we support only git://
), the stub downloader tries
to clone the repository and use it as a source of contracts
to generate tests or stubs.
Through environment variables, system properties, or properties set
inside the plugin or the contracts repository configuration, you can
tweak the downloader’s behavior. The following table describes the available
properties:
Table 1. SCM Stub Downloader properties
Type of a property
Name of the property
Description
* git.branch
(plugin prop)
* stubrunner.properties.git.branch
(system prop)
* STUBRUNNER_PROPERTIES_GIT_BRANCH
(env prop)
master
Which branch to checkout
* git.username
(plugin prop)
* stubrunner.properties.git.username
(system prop)
* STUBRUNNER_PROPERTIES_GIT_USERNAME
(env prop)
Git clone username
* git.password
(plugin prop)
* stubrunner.properties.git.password
(system prop)
* STUBRUNNER_PROPERTIES_GIT_PASSWORD
(env prop)
Git clone password
* git.no-of-attempts
(plugin prop)
* stubrunner.properties.git.no-of-attempts
(system prop)
* STUBRUNNER_PROPERTIES_GIT_NO_OF_ATTEMPTS
(env prop)
10
Number of attempts to push the commits to origin
* git.wait-between-attempts
(Plugin prop)
* stubrunner.properties.git.wait-between-attempts
(system prop)
* STUBRUNNER_PROPERTIES_GIT_WAIT_BETWEEN_ATTEMPTS
(env prop)
1000
Number of milliseconds to wait between attempts to push the commits to origin