In previous posts, I talked about the characteristics of contracts and mentioned some of its advantages and disadvantages. Now it is time for a deep-dive into the technical (and funniest) side to see how you can develop contracts for your API and produce Rest-Assured tests and Wiremock stubs in just a few steps.

Writing contracts

The only thing we need to start writing contracts is the OpenApi (or Swagger) specification and – to make it quick – I will use the same API I defined on my previous post, more precisely the following endpoints:

  • GET /projects
  • GET /projects/{project-id}

Let’s start with the first endpoint. What do we expect our API to do if we perform that request? The happy path would be a response with http status code 200 and a list of projects in the body, so our contract will be something like:

  • Request:
    • Http method: GET
    • url /tasklist-management/api/projects
  • Response:
    • Http status: 200
    • body: {project-1, project-2}

The next step is to translate it into code. I will use Groovy because I think the code will be more readable and I am used to write tests with it, but it also works with Java directly. 

def contracts = []

contracts << Contract.make {
    name("get projects should return 200 code and list of projects")
    description('''
given:
when:
    get /projects is called
then:
    should answer with http 200 and the list of projects
''')
    request {
        method("GET")
        urlPath "/tasklist-management/api/projects"
    }
    response {
        status(200)
        headers {
            contentType(applicationJson())
        }
        body([
                [
                        projectId  : 1,
                        title      : 'My awesome project 1',
                        description: 'This is the first project created with the best api',
                ],
                [
                        projectId  : 2,
                        title      : 'My second project',
                        description: 'Another awesome project',
                ]
        ]
        )
    }
}

As you can see, the different parts I mentioned above can be identified very easily in the contract. This is a best case example, but you can define more contracts to cover the edge cases, like searching for a project which does not exist and delivering a 404 instead of a 200 and so on.

I defined another example for the second endpoint, you can find it in the Github repository.

Configuring the plugin

Our contracts have already been defined, so now it is time for the Spring Cloud Contract Verifier plugin to come into game. Generally, we will feed the plugin with our contracts and it will produce the tests and mock stubs for us, but for that there are some parameters which need to be configured.

First of all, we need to add the dependency in our pom.xml and configure the plugin. There are more parameters to configure the plugin but I will show you the basic ones. We will use Spock as framework for our Rest-Assured tests, so we need to add some extra dependencies to get them running. Do not worry, you will find the link to my Github repository at the end of the post ;).

Next step is to define the execution part, which in our case consists in generating the tests and WireMock stubs before the integration tests phase. For that, the following goals need to be defined:

  • convert: Basically converts the contracts into stubs mappings allowing to generate a ‘stubs-jar’ that we will need later
  • generateStubs: Creates a jar file with the previously converted stubs. Requires convert to be executed first.
  • generateTests: Picks the contracts from the provided directory and generates the Rest-Assured tests using the framework that we defined in the plugin configuration

As a result, this is how the plugin should look like: