API Mocking and Testing With Microcks

1. Introduction

In this tutorial, we’ll look at Microcks, an open-source, Kubernetes-native platform for turning API and microservices contracts into live mocks. We’ll also see how to reuse the same contracts to run conformance tests against a real implemenation.

We’ll cover the core concepts first, then use the Testcontainers integration to spin up Microcks inside a JUnit5 test, import an OpenAPI contract, call the generated mock, and validate a running service against it.

2. What Is Microcks?

Microcks is a CNCF (Cloud Native Computing Foundation) project for API mocking and testing. It consumes API and microservice artifacts, such as OpenAPI specs, AsyncAPI specs, gRPC protobuf files, GraphQL schemas, Postman collections, and SoapUI projects. Then, it turns them into live, stateful mocks in seconds.

Beyond mocking, Microcks reuses these same artifacts to run contract conformance and non-regression tests against a real API implementation. It also integrates with Jenkins, GitHub Actions and Tekton pipelines through a CLI, so both mocking and testing can be automated across the whole delivery chain.

We can run Microcks as a standalone server, using Docker Compose or a Kubernetes/Helm deployment. For local development and CI, though, it’s more convenient to embed it directly inside a test using the Testcontainers module.

Microcks isn’t limited to synchronous REST APIs, either. Through its ensemble mode, it can also mock and contract-test SOAP, GraphQL, and gRPC services, as well as event-driven APIs described with AsyncAPI, over brokers like Kafka, SQS or SNS. That means the same tool and the same workflow can cover most of the API styles a typical microservices architecture is likely to use.

3. Setting Up Microcks With Testcontainers

The microcks-testcontainers library lets us start a lightweight, throwaway Microcks instance for the lifetime of a test class.

First, let’s add the Maven dependency:

<dependency>
    <groupId>io.github.microcks</groupId>
    <artifactId>microcks-testcontainers</artifactId>
    <version>0.4.4</version>
</dependency>

Next, let’s create and start a MicrocksContainer, pointing it to an OpenAPI contract for our API:

MicrocksContainer microcks = new MicrocksContainer(
  DockerImageName.parse("quay.io/microcks/microcks-uber:1.14.0"))
  .withMainArtifacts("apipastries-openapi.yaml");
microcks.start();

The uber image bundles everything Microcks needs without an external MongoDB dependency, which keeps startup fast. We can also import artifacts after startup, using importAsMainArtifact() or importAsSecondaryArtifact() on the running container.

4. Mocking the API

Once the container has imported the contract, Microcks automatically exposes a mock endpoint for every operation. We can retrieve the base URL and call it like any real API:

String baseApiUrl = microcks.getRestMockEndpoint("API Pastries", "0.0.1");

HttpResponse<String> response = client.send(
  HttpRequest.newBuilder(URI.create(baseApiUrl + "/pastries/Millefeuille")).GET().build(),
  HttpResponse.BodyHandlers.ofString());

assertEquals(200, response.statusCode());

Microcks generates realistic responses straight from the examples defined in the OpenAPI contract. Then, it cycles through them so repeated calls don’t always return the same payload. This means consumers can be developed and tested against a dependency that doesn’t exist yet, or isn’t reacheable from a test environment.

Furthermore, there are ways we can confirm a mock was actually called. We’ll do this by either calling microcks.verify(“API Pastries”,”0.0.1″), or by checking the exact invocation count through microcks.getServiceInvocationsCount(“API Pastries”,”0.0.1″).

5. Running Contract Tests

The same contract can validate a real implementation running on our machine. First, we need to expose the port with Testcontainers.exposeHostPorts() before starting the container, not after. We do this since the Microcks container needs to reach back out to our host:

Testcontainers.exposeHostPorts(port);
microcks.start();

Then, let’s launch a conformance test against our locally running server:

TestRequest testRequest = new TestRequest.Builder()
  .serviceId("API Pastries:0.0.1")
  .runnerType(TestRunnerType.OPEN_API_SCHEMA.name())
  .testEndpoint("http://host.testcontainers.internal:" + port)
  .filteredOperations(List.of("GET /pastries/{name}"))
  .timeout(Duration.ofSeconds(2))
  .build();

TestResult testResult = microcks.testEndpoint(testRequest);
assertTrue(testResult.isSuccess());

We scoped the test to a single operation with filteredOperations(). Without it, Microcks also replays the GET /pastries and PATCH /pastries/{name} examples from the contract, which fail against an implementation that doesn’t cover them yet.

Here, Microcks replays every example from the OpenAPI contract against our running application and checks each response against the schema. For a more JUnit-friendly failure report, we can use the Assertions helper instead, Assertions.assertSuccess(testResult);

This single call runs the same conformance check that a CI pipeline would run against a live deployment, only locally and in milliseconds.

6. Conclusion

In this article, we introduced Microcks as a tool for turning API contracts into live mocks and reusing those same contracts for conformance testing. We used its Testcontainers integration to start a throwaway Microcks instance inside a JUnit test, import an OpenAPI contract, call the generated mock, and run a contract test against a live implementation.

Because mocks and tests are dervide from the same source contract, both stay in sync with the API definition. That removes a common source of drift between what an API promises and what it actually does.

As always, the code is available over on Github.