World is not ideal, so is software engineering. In some situations, you won’t be able or don’t want to test a 3rd party API rest service with the real endpoints. In such situations, there is a combination of tools, specifications and frameworks that can massively help us:

- https://www.testcontainers.org/, is a Java library able to run anything that can be run in a Docker container
- https://www.openapis.org/, a broadly adopted industry standard for describing modern APIs
- https://stoplight.io/open-source/prism/, a tool able to mock a REST API using its OpenApi documentation
- http://spockframework.org, a testing and specification framework for Java and Groovy applications

The problem we want to solve is what happens when we need to create an application using a 3rd party REST API service that hasn’t still been developed, but at least they provided us the OpenApi specification. The OpenApi specification is pretty simple and it only contains an endpoint with the list the users. This endpoint just returns an array of strings. The yaml file looks like this:

Then, the idea is to have an implementation in our app to get this list of users using the implementation of the 3rd party service that has not been implemented yet. We will then call our implementation that will use the mock server using the OpenApi definition.

Again, to keep this example as simple as possible, I put everything in one groovy script class. Let’s dig a bit in this example.

First, we import all the dependencies needed for this example. This example has been tested against groovy 2.5.4.

The class UserController just contains the method getUsers() to calls the prism an external url to get the list of users and returns a List of String.

The test class UserControllerSpec first defines two shared variables: prism and userController. prism is where all the magic happens and it basically is able to start a docker container using the image stoplight/prism:3.3.4. Then, it runs the command mock -h 0.0.0.0 -d /tmp/swagger.yml after a volume has been added to the docker container. The flag -d tells prism to create random output, which is pretty cool and allow us to stress out the test a bit more than with always the same output. userController is just an instance to the bean that will be calling the 3rd party endpoint.

Finally, we have a test method to check the output received from the method getUsers(). We are basically testing that it always returns a List of String.

With this in place, it will be pretty simple to replace the actual call to the mock API server to use the real one once it has been developed.