Testcontainers | MockServer

MockServer publishes its own Testcontainers module, mockserver-testcontainers, that starts the official MockServer Docker image for the duration of a test and gives you a ready-wired client. It is the MockServer-maintained module and is kept in lockstep with each MockServer release.

Note: this module supersedes the older bundled org.testcontainers:mockserver module. The bundled module exposes only a single port, pins an old default image, and has no configuration helpers. New projects should use org.mock-server:mockserver-testcontainers described here.

Maven

<dependency>
    <groupId>org.mock-server</groupId>
    <artifactId>mockserver-testcontainers</artifactId>
    <version>7.0.0</version>
    <scope>test</scope>
</dependency>

Gradle

testImplementation 'org.mock-server:mockserver-testcontainers:7.0.0'

The module brings in Testcontainers and the MockServer Java client transitively, so no other MockServer dependency is required for a test.

Start the container, set up an expectation through the wired client, then point the system under test at the container endpoint. By default the image tag is derived from the MockServer client library on the classpath, so the container and client always match.

import org.mockserver.client.MockServerClient;
import org.mockserver.testcontainers.MockServerContainer;
import org.junit.jupiter.api.Test;

import static org.mockserver.model.HttpRequest.request;
import static org.mockserver.model.HttpResponse.response;

class ExampleTest {

    @Test
    void shouldMockResponse() {
        try (MockServerContainer mockServer = new MockServerContainer()) {
            mockServer.start();

            MockServerClient client = mockServer.getClient();
            client
                .when(request().withPath("/hello"))
                .respond(response().withBody("world"));

            // point the system under test at mockServer.getEndpoint()
            // e.g. http://<host>:<mapped-port>/hello  ->  "world"
        }
    }
}

Use getEndpoint() / getSecureEndpoint() for the HTTP / HTTPS base URL (MockServer serves both on the same port), and getServerPort() for the mapped host port. The client returned by getClient() is cached and stopped automatically when the container stops.

Fluent helpers configure the container before it starts. Each returns the container for chaining.

Helper	What it does
`withServerPort(int)`	Change the port MockServer listens on inside the container.
`withDnsPort(int)`	Enable the DNS resolver and expose the DNS port over UDP.
`withTransparentProxy()`	Enable transparent proxy mode and add the `NET_ADMIN` capability. iptables / redirect rules remain your responsibility.
`withHttp3(int)`	Enable experimental HTTP/3 (QUIC) and expose the port over UDP.
`withInitializationJson(String)`	Copy an initialization JSON file into the container and load its expectations at startup.
`withLogLevel(String)`	Set the MockServer log level (e.g. `DEBUG`).
`withProperty(key, value)` / `withProperties(Map)`	Set any MockServer configuration property by its environment-variable name (e.g. `MOCKSERVER_MAX_EXPECTATIONS`).

To connect MockServer to other containers (for example an AsyncAPI broker), use the standard Testcontainers withNetwork(Network) and withNetworkAliases(String...) methods inherited from GenericContainer.

Pinning the image: to use a specific image instead of the version-matched default, pass a DockerImageName to the constructor:

new MockServerContainer(
    DockerImageName.parse("mockserver/mockserver:mockserver-7.0.0")
);