9. Using the Pluggable Architecture
Prev |  | Next

# 9. Using the Pluggable Architecture

You may encounter cases where you have your contracts have been defined in other formats, such as YAML, RAML or PACT. In those cases, you still want to benefit from the automatic generation of tests and stubs. You can add your own implementation for generating both tests and stubs. Also, you can customize the way tests are generated (for example, you can generate tests for other languages) and the way stubs are generated (for example, you can generate stubs for other HTTP server implementations).

## 9.1 Custom Contract Converter

Assume that your contract is written in a YAML file as follows:

    request:
      url: /foo
      method: PUT
      headers:
        foo: bar
      body:
        foo: bar
    response:
      status: 200
      headers:
        foo2: bar
      body:
        foo2: bar

The `ContractConverter` interface lets you register your own implementation of a contract structure converter. The following code listing shows the `ContractConverter` interface:

    package org.springframework.cloud.contract.spec

    /**
     * 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
     */
    interface ContractConverter<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.

| Important
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:

    # Converters
    org.springframework.cloud.contract.spec.ContractConverter=\
    org.springframework.cloud.contract.verifier.converter.YamlContractConverter

The following example shows a typical YAML implementation that matches the preceding example:

    package org.springframework.cloud.contract.verifier.converter

    import java.nio.file.Files

    import groovy.transform.CompileStatic
    import org.springframework.cloud.contract.spec.Contract
    import org.springframework.cloud.contract.spec.ContractConverter
    import org.springframework.cloud.contract.spec.internal.Headers
    import org.yaml.snakeyaml.Yaml

    /**
     * Simple converter from and to a {@link YamlContract} to a collection of {@link Contract}
     */
    @CompileStatic
    class YamlContractConverter implements ContractConverter<List<YamlContract>> {

    	@Override
    	public boolean isAccepted(File file) {
    		String name = file.getName()
    		return name.endsWith(".yml") || name.endsWith(".yaml")
    	}

    	@Override
    	public Collection<Contract> convertFrom(File file) {
    		try {
    			YamlContract yamlContract = new Yaml().loadAs(
    					Files.newInputStream(file.toPath()), YamlContract.class)
    			return [Contract.make {
    				request {
    					method(yamlContract?.request?.method)
    					url(yamlContract?.request?.url)
    					headers {
    						yamlContract?.request?.headers?.each { String key, Object value ->
    							header(key, value)
    						}
    					}
    					body(yamlContract?.request?.body)
    				}
    				response {
    					status(yamlContract?.response?.status)
    					headers {
    						yamlContract?.response?.headers?.each { String key, Object value ->
    							header(key, value)
    						}
    					}
    					body(yamlContract?.response?.body)
    				}
    			}]
    		}
    		catch (FileNotFoundException e) {
    			throw new IllegalStateException(e)
    		}
    	}

    	@Override
    	public List<YamlContract> convertTo(Collection<Contract> contracts) {
    		return contracts.collect { Contract contract ->
    			YamlContract yamlContract = new YamlContract()
    			yamlContract.request.with {
    				method = contract?.request?.method?.clientValue
    				url = contract?.request?.url?.clientValue
    				headers = (contract?.request?.headers as Headers)?.asStubSideMap()
    				body = contract?.request?.body?.clientValue as Map
    			}
    			yamlContract.response.with {
    				status = contract?.response?.status?.clientValue as Integer
    				headers = (contract?.response?.headers as Headers)?.asStubSideMap()
    				body = contract?.response?.body?.clientValue as Map
    			}
    			return yamlContract
    		}
    	}
    }

### 9.1.1 Pact Converter

Spring Cloud Contract includes support for Pact representation of contracts. Instead of using the Groovy DSL, you can use Pact files. In this section, we present how to add Pact support for your project.

### 9.1.2 Pact Contract

Consider following example of a Pact contract, which is a file under the `src/test/resources/contracts` folder.

    {
      "provider": {
        "name": "Provider"
      },
      "consumer": {
        "name": "Consumer"
      },
      "interactions": [
        {
          "description": "",
          "request": {
            "method": "PUT",
            "path": "/fraudcheck",
            "headers": {
              "Content-Type": "application/vnd.fraud.v1+json"
            },
            "body": {
              "clientId": "1234567890",
              "loanAmount": 99999
            },
            "matchingRules": {
              "$.body.clientId": {
                "match": "regex",
                "regex": "[0-9]{10}"
              }
            }
          },
          "response": {
            "status": 200,
            "headers": {
              "Content-Type": "application/vnd.fraud.v1+json;charset=UTF-8"
            },
            "body": {
              "fraudCheckStatus": "FRAUD",
              "rejectionReason": "Amount too high"
            },
            "matchingRules": {
              "$.body.fraudCheckStatus": {
                "match": "regex",
                "regex": "FRAUD"
              }
            }
          }
        }
      ],
      "metadata": {
        "pact-specification": {
          "version": "2.0.0"
        },
        "pact-jvm": {
          "version": "2.4.18"
        }
      }
    }

The remainder of this section about using Pact refers to the preceding file.

### 9.1.3 Pact for Producers

On the producer side, you mustadd two additional dependencies to your plugin configuration. One is the Spring Cloud Contract Pact support, and the other represents the current Pact version that you use.

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>
    	</configuration>
    	<dependencies>
    		<dependency>
    			<groupId>org.springframework.cloud</groupId>
    			<artifactId>spring-cloud-contract-spec-pact</artifactId>
    			<version>${spring-cloud-contract.version}</version>
    		</dependency>
    		<dependency>
    			<groupId>au.com.dius</groupId>
    			<artifactId>pact-jvm-model</artifactId>
    			<version>2.4.18</version>
    		</dependency>
    	</dependencies>
    </plugin>

Gradle.

    classpath "org.springframework.cloud:spring-cloud-contract-spec-pact:${findProperty('verifierVersion') ?: verifierVersion}"
    classpath 'au.com.dius:pact-jvm-model:2.4.18'

When you execute the build of your application, a test will be generated. The generated test might be as follows:

    @Test
    public void validate_shouldMarkClientAsFraud() throws Exception {
    	// given:
    		MockMvcRequestSpecification request = given()
    				.header("Content-Type", "application/vnd.fraud.v1+json")
    				.body("{\"clientId\":\"1234567890\",\"loanAmount\":99999}");

    	// when:
    		ResponseOptions response = given().spec(request)
    				.put("/fraudcheck");

    	// then:
    		assertThat(response.statusCode()).isEqualTo(200);
    		assertThat(response.header("Content-Type")).isEqualTo("application/vnd.fraud.v1+json;charset=UTF-8");
    	// and:
    		DocumentContext parsedJson = JsonPath.parse(response.getBody().asString());
    		assertThatJson(parsedJson).field("rejectionReason").isEqualTo("Amount too high");
    	// and:
    		assertThat(parsedJson.read("$.fraudCheckStatus", String.class)).matches("FRAUD");
    }

The corresponding generated stub might be as follows:

    {
      "uuid" : "996ae5ae-6834-4db6-8fac-358ca187ab62",
      "request" : {
        "url" : "/fraudcheck",
        "method" : "PUT",
        "headers" : {
          "Content-Type" : {
            "equalTo" : "application/vnd.fraud.v1+json"
          }
        },
        "bodyPatterns" : [ {
          "matchesJsonPath" : "$[?(@.loanAmount == 99999)]"
        }, {
          "matchesJsonPath" : "$[?(@.clientId =~ /([0-9]{10})/)]"
        } ]
      },
      "response" : {
        "status" : 200,
        "body" : "{\"fraudCheckStatus\":\"FRAUD\",\"rejectionReason\":\"Amount too high\"}",
        "headers" : {
          "Content-Type" : "application/vnd.fraud.v1+json;charset=UTF-8"
        }
      }
    }

### 9.1.4 Pact for Consumers

On the producer side, you must add two additional dependencies to your project dependencies. One is the Spring Cloud Contract Pact support, and the other represents the current Pact version that you use.

Maven.

    <dependency>
    	<groupId>org.springframework.cloud</groupId>
    	<artifactId>spring-cloud-contract-spec-pact</artifactId>
    	<scope>test</scope>
    </dependency>
    <dependency>
    	<groupId>au.com.dius</groupId>
    	<artifactId>pact-jvm-model</artifactId>
    	<version>2.4.18</version>
    	<scope>test</scope>
    </dependency>

Gradle.

    testCompile "org.springframework.cloud:spring-cloud-contract-spec-pact"
    testCompile 'au.com.dius:pact-jvm-model:2.4.18'

## 9.2 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:

    package org.springframework.cloud.contract.verifier.builder

    import org.springframework.cloud.contract.verifier.config.ContractVerifierConfigProperties
    import org.springframework.cloud.contract.verifier.file.ContractMetadata
    /**
     * Builds a single test.
     *
     * @since 1.1.0
     */
    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 className - the name of the generated test class
    	 * @param classPackage - the name of the package in which the test class should be stored
    	 * @param includedDirectoryRelativePath - relative path to the included directory
    	 * @return contents of a single test class
    	 */
    	String buildClass(ContractVerifierConfigProperties properties, Collection<ContractMetadata> listOfFiles,
    					  String className, String classPackage, String includedDirectoryRelativePath)

    	/**
    	 * Extension that should be appended to the generated test class. E.g. {@code .java} or {@code .php}
    	 *
    	 * @param properties - properties passed to the plugin
    	 */
    	String fileExtension(ContractVerifierConfigProperties properties)
    }

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

## 9.3 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:

    package org.springframework.cloud.contract.verifier.converter

    import groovy.transform.CompileStatic
    import org.springframework.cloud.contract.spec.Contract
    import org.springframework.cloud.contract.verifier.file.ContractMetadata

    /**
     * Converts contracts into their stub representation.
     *
     * @since 1.1.0
     */
    @CompileStatic
    interface StubGenerator {

    	/**
    	 * Returns {@code true} if the converter can handle the file to convert it into a stub.
    	 */
    	boolean canHandleFileName(String fileName)

    	/**
    	 * Returns the collection of converted contracts into stubs. One contract can
    	 * result in multiple stubs.
    	 */
    	Map<Contract, String> convertContents(String rootName, ContractMetadata content)

    	/**
    	 * Returns 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#name} 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)
    }

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.

| Tip
You can provide multiple stub generator implementations. For example, from a single DSL, you can produce both WireMock stubs and Pact files.

## 9.4 Using the Custom Stub Runner

If you decide to use a 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:

    package org.springframework.cloud.contract.stubrunner.provider.moco

    import com.github.dreamhead.moco.bootstrap.arg.HttpArgs
    import com.github.dreamhead.moco.runner.JsonRunner
    import com.github.dreamhead.moco.runner.RunnerSetting
    import groovy.util.logging.Slf4j
    import org.springframework.cloud.contract.stubrunner.HttpServerStub
    import org.springframework.util.SocketUtils

    @Slf4j
    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() {
    		return start(SocketUtils.findAvailableTcpPort())
    	}

    	@Override
    	HttpServerStub start(int port) {
    		this.port = 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().withStream(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
    	boolean isAccepted(File file) {
    		return file.name.endsWith(".json")
    	}
    }

Then, you can register it in your `spring.factories` file, as shown in the following example:

    org.springframework.cloud.contract.stubrunner.HttpServerStub=\
    org.springframework.cloud.contract.stubrunner.provider.moco.MocoHttpServerStub

Now you can run stubs with Moco.

| Important
If you do not provide any implementation, then the default (WireMock) implementation is used. If you provide more than one, the first one on the list is used.

## 9.5 Using the Custom Stub Downloader

You can customize the way your stubs are downloaded by creating an implementation of the `StubDownloaderBuilder` interface, as shown in the following example:

    package com.example;

    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 shown in the following example:

    # 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.

| Important
If you do not provide any implementation, then the default is used. If you use the `repositoryRoot` property or the `workOffline` flag, then an Aether-based implementation that downloads stubs from a remote repository is used. If you do not provide these values, the `ClasspathStubProvider` (which will scan the classpath) is used. If you provide more than one, then the first one on the list is used.

Prev |  | Next
8. Customization | Home | 10. Spring Cloud Contract WireMock