Microcks Testcontainers Java

Java library for Testcontainers that enables embedding Microcks into your JUnit tests with lightweight, throwaway instance thanks to containers

Build Status

Latest released version is 0.1.3.

Current development version is 0.1.4-SNAPSHOT.

Sonarcloud Quality metrics

How to use it?

Include it into your project dependencies

If you're using Maven:

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

or if you're using Gradle:

dependencies {
    testImplementation 'io.github.microcks:microcks-testcontainers:0.1.3'
}

Startup the container

You just have to specify the container image you'd like to use. This library requires a Microcks uber distribution (with no MongoDB dependency).

MicrocksContainer microcks = new MicrocksContainer(
      DockerImageName.parse("quay.io/microcks/microcks-uber:nightly"));
microcks.start();

Import content in Microcks

To use Microcks mocks or contract-testing features, you first need to import OpenAPI, Postman Collection, GraphQL or gRPC artifacts. Artifacts can be imported as main/Primary ones or as secondary ones. See Multi-artifacts support for details.

microcks.importAsMainArtifact(new File("target/test-classes/apipastries-openapi.yaml"));
microcks.importAsSecondaryArtifact(new File("target/test-classes/apipastries-postman-collection.json"));

Please refer to our MicrocksContainerTest for comprehensive example on how to use it.

Using mock endpoints for your dependencies

During your test setup, you'd probably need to retrieve mock endpoints provided by Microcks containers to setup your base API url calls. You can do it like this:

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

The container provides methods for different supported API styles/protocols (Soap, GraphQL, gRPC,...).

The container also provides getHttpEndpoint() for raw access to those API endpoints.

Launching new contract-tests

If you want to ensure that your application under test is conformant to an OpenAPI contract (or other type of contract), you can launch a Microcks contract/conformance test using the local server port you're actually running. This is typically how it could be done for a Spring Boot application:

@LocalServerPort
private Integer port;

@BeforeEach
public void setupPort() {
  // Host port exposition should be done here.
  Testcontainers.exposeHostPorts(port);
}

@Test
public void testOpenAPIContract() throws Exception {
   // Ask for an Open API conformance to be launched.
   TestRequest testRequest = new TestRequest.Builder()
      .serviceId("API Pastries:0.0.1")
      .runnerType(TestRunnerType.OPEN_API_SCHEMA.name())
      .testEndpoint("http://host.testcontainers.internal:" + port)
      .timeout(2000L)
      .build();

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

The TestResult gives you access to all details regarding success of failure on different test cases.

A comprehensive Spring Boot demo application illustrating both usages is available here: spring-boot-order-service.