In this section, we describe how to customize various parts of Spring Cloud Contract.

1. DSL Customization

This section is valid only for the Groovy DSL

You can customize the Spring Cloud Contract Verifier by extending the DSL, as shown in the remainder of this section.

1.1. Extending the DSL

You can provide your own functions to the DSL. The key requirement for this feature is to maintain the static compatibility. Later in this chapter, you can see examples of:

  • Creating a JAR with reusable classes.

  • Referencing of these classes in the DSLs.

You can find the full example here.

1.2. Common JAR

The following examples show three classes that can be reused in the DSLs.

PatternUtils contains functions used by both the consumer and the producer. The following listing shows the PatternUtils class:

package com.example;

import java.util.regex.Pattern;

/**
 * If you want to use {@link Pattern} directly in your tests
 * then you can create a class resembling this one. It can
 * contain all the {@link Pattern} you want to use in the DSL.
 *
 * <pre>
 * {@code
 * request {
 *     body(
 *         [ age: $(c(PatternUtils.oldEnough()))]
 *     )
 * }
 * </pre>
 *
 * Notice that we're using both {@code $()} for dynamic values
 * and {@code c()} for the consumer side.
 *
 * @author Marcin Grzejszczak
 */
//tag::impl[]
public class PatternUtils {

    public static String tooYoung() {
        //remove::start[]
        return "[0-1][0-9]";
        //remove::end[return]
    }

    public static Pattern oldEnough() {
        //remove::start[]
        return Pattern.compile("[2-9][0-9]");
        //remove::end[return]
    }

    /**
     * Makes little sense but it's just an example ;)
     */
    public static Pattern ok() {
        //remove::start[]
        return Pattern.compile("OK");
        //remove::end[return]
    }
}
//end::impl[]

ConsumerUtils contains functions used by the consumer. The following listing shows the ConsumerUtils class:

package com.example;

import org.springframework.cloud.contract.spec.internal.ClientDslProperty;

/**
 * DSL Properties passed to the DSL from the consumer's perspective.
 * That means that on the input side {@code Request} for HTTP
 * or {@code Input} for messaging you can have a regular expression.
 * On the {@code Response} for HTTP or {@code Output} for messaging
 * you have to have a concrete value.
 *
 * @author Marcin Grzejszczak
 */
//tag::impl[]
public class ConsumerUtils {
    /**
     * Consumer side property. By using the {@link ClientDslProperty}
     * you can omit most of boilerplate code from the perspective
     * of dynamic values. Example
     *
     * <pre>
     * {@code
     * request {
     *     body(
     *         [ age: $(ConsumerUtils.oldEnough())]
     *     )
     * }
     * </pre>
     *
     * That way it's in the implementation that we decide what value we will pass to the consumer
     * and which one to the producer.
     *
     * @author Marcin Grzejszczak
     */
    public static ClientDslProperty oldEnough() {
        //remove::start[]
        // this example is not the best one and
        // theoretically you could just pass the regex instead of `ServerDslProperty` but
        // it's just to show some new tricks :)
        return new ClientDslProperty(PatternUtils.oldEnough(), 40);
        //remove::end[return]
    }

}
//end::impl[]

ProducerUtils contains functions used by the producer. The following listing shows the ProducerUtils class:

package com.example;

import org.springframework.cloud.contract.spec.internal.ServerDslProperty;

/**
 * DSL Properties passed to the DSL from the producer's perspective.
 * That means that on the input side {@code Request} for HTTP
 * or {@code Input} for messaging you have to have a concrete value.
 * On the {@code Response} for HTTP or {@code Output} for messaging
 * you can have a regular expression.
 *
 * @author Marcin Grzejszczak
 */
//tag::impl[]
public class ProducerUtils {

    /**
     * Producer side property. By using the {@link ProducerUtils}
     * you can omit most of boilerplate code from the perspective
     * of dynamic values. Example
     *
     * <pre>
     * {@code
     * response {
     *     body(
     *         [ status: $(ProducerUtils.ok())]
     *     )
     * }
     * </pre>
     *
     * That way it's in the implementation that we decide what value we will pass to the consumer
     * and which one to the producer.
     */
    public static ServerDslProperty ok() {
        // this example is not the best one and
        // theoretically you could just pass the regex instead of `ServerDslProperty` but
        // it's just to show some new tricks :)
        return new ServerDslProperty( PatternUtils.ok(), "OK");
    }
}
//end::impl[]

1.3. Adding a Test Dependency in the Project’s Dependencies

To add a test dependency in the project’s dependencies, you must first add the common jar dependency as a test dependency. Because your contracts files are available on the test resources path, the common jar classes automatically become visible in your Groovy files. The following examples show how to test the dependency:

Maven
<dependency>
    <groupId>com.example</groupId>
    <artifactId>beer-common</artifactId>
    <version>${project.version}</version>
    <scope>test</scope>
</dependency>
Gradle
testImplementation("com.example:beer-common:0.0.1-SNAPSHOT")

1.4. Adding a Test Dependency in the Plugin’s Dependencies

Now, you must add the dependency for the plugin to reuse at runtime, as the following example shows:

Maven
<plugin>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-contract-maven-plugin</artifactId>
    <version>${spring-cloud-contract.version}</version>
    <extensions>true</extensions>
    <configuration>
        <testFramework>JUNIT5</testFramework>
        <packageWithBaseClasses>com.example</packageWithBaseClasses>
        <baseClassMappings>
            <baseClassMapping>
                <contractPackageRegex>.*intoxication.*</contractPackageRegex>
                <baseClassFQN>com.example.intoxication.BeerIntoxicationBase</baseClassFQN>
            </baseClassMapping>
        </baseClassMappings>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>beer-common</artifactId>
            <version>${project.version}</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>
</plugin>
Gradle

1.5. Referencing Classes in DSLs

You can now reference your classes in your DSL, as the following example shows:

package contracts.beer.rest

import com.example.ConsumerUtils
import com.example.ProducerUtils
import org.springframework.cloud.contract.spec.Contract

Contract.make {
    description("""
Represents a successful scenario of getting a beer

```
given:
    client is old enough
when:
    he applies for a beer
then:
    we'll grant him the beer
```

""")
    request {
        method 'POST'
        url '/check'
        body(
                age: $(ConsumerUtils.oldEnough())
        )
        headers {
            contentType(applicationJson())
        }
    }
    response {
        status 200
        body("""
            {
                "status": "${value(ProducerUtils.ok())}"
            }
            """)
        headers {
            contentType(applicationJson())
        }
    }
}
You can set the Spring Cloud Contract plugin up by setting convertToYaml to true. That way, you do NOT have to add the dependency with the extended functionality to the consumer side, since the consumer side uses YAML contracts instead of Groovy contracts.

2. WireMock Customization

In this section, we show how to customize the way you work with WireMock.

2.1. Registering Your Own WireMock Extension

WireMock lets you register custom extensions. By default, Spring Cloud Contract registers the transformer, which lets you reference a request from a response. If you want to provide your own extensions, you can register an implementation of the org.springframework.cloud.contract.verifier.dsl.wiremock.WireMockExtensions interface. Since we use the spring.factories extension approach, you can create an entry similar to the following in the META-INF/spring.factories file:

org.springframework.cloud.contract.verifier.dsl.wiremock.WireMockExtensions=\
org.springframework.cloud.contract.stubrunner.provider.wiremock.TestWireMockExtensions
org.springframework.cloud.contract.spec.ContractConverter=\
org.springframework.cloud.contract.stubrunner.TestCustomYamlContractConverter

The following example shows a custom extension:

Example 1. TestWireMockExtensions.groovy
/*
 * Copyright 2013-2020 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.cloud.contract.verifier.dsl.wiremock

import com.github.tomakehurst.wiremock.extension.Extension

/**
 * Extension that registers the default transformer and the custom one
 */
class TestWireMockExtensions implements WireMockExtensions {
    @Override
    List<Extension> extensions() {
        return [
                new DefaultResponseTransformer(),
                new CustomExtension()
        ]
    }
}

class CustomExtension implements Extension {

    @Override
    String getName() {
        return "foo-transformer"
    }
}
If you want the transformation to be applied only for a mapping that explicitly requires it, override the applyGlobally() method and set it to false .

2.2. Customization of WireMock Configuration

You can register a bean of type org.springframework.cloud.contract.wiremock.WireMockConfigurationCustomizer to customize the WireMock configuration (for example, to add custom transformers). The following example shows how to do so:

        @Bean
        WireMockConfigurationCustomizer optionsCustomizer() {
            return new WireMockConfigurationCustomizer() {
                @Override
                public void customize(WireMockConfiguration options) {
// perform your customization here
                }
            };
        }

2.3. Customization of WireMock via Metadata

With version 3.0.0 you’re able to set metadata in your contracts. If you set an entry with key equal to wiremock and the value will be a valid WireMock’s StubMapping JSON / map or an actual StubMapping object, Spring Cloud Contract will patch the generated stub with part of your customization. Let’s look at the following example

name: "should count all frauds"
request:
  method: GET
  url: /yamlfrauds
response:
  status: 200
  body:
    count: 200
  headers:
    Content-Type: application/json
metadata:
  wiremock:
    stubMapping: >
      {
        "response" : {
          "fixedDelayMilliseconds": 2000
        }
      }

In the metadata section we’ve set an entry with key wiremock and its value is a JSON StubMapping that sets a delay in the generated stub. Such code allowed us to get the following merged WireMock JSON stub.

{
  "id" : "ebae49e2-a2a3-490c-a57f-ba28e26b81ea",
  "request" : {
    "url" : "/yamlfrauds",
    "method" : "GET"
  },
  "response" : {
    "status" : 200,
    "body" : "{\"count\":200}",
    "headers" : {
      "Content-Type" : "application/json"
    },
    "fixedDelayMilliseconds" : 2000,
    "transformers" : [ "response-template" ]
  },
  "uuid" : "ebae49e2-a2a3-490c-a57f-ba28e26b81ea"
}

The current implementation allows to manipulate only the stub side (we don’t change the generated test). Also, what does not get changed are the whole request and body and headers of the response.

2.3.1. Customization of WireMock via Metadata and a Custom Processor

If you want to apply a custom WireMock StubMapping post processing, you can under META-INF/spring.factories under the org.springframework.cloud.contract.verifier.converter.StubProcessor key register your own implementation of a stub processor. For your convenience we’ve created an interface called org.springframework.cloud.contract.verifier.wiremock.WireMockStubPostProcessor that is dedicated to WireMock.

You’ll have to implement methods to inform Spring Cloud Contract whether the post processor is applicable for a given contract and how should the post processing look like.

On the consumer side, when using Stub Runner, remember to pass the custom HttpServerStubConfigurer implementation (e.g. the one that extends WireMockHttpServerStubConfigurer) where you’ll register a custom extension of your choosing. If you don’t do so, even you have a custom WireMock extension on the classpath, WireMock will not notice it, won’t apply it and will print out a warning statement that the given extension was not found.

3. Using the Pluggable Architecture

You may encounter cases where 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).

3.1. Custom Contract Converter

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;

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

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

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

3.4. 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:

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

3.5. 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:

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

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