Java Client

The Java client gives you two ways to interact with MockServer: connect to an already-running instance, or start MockServer in-process and connect to it in one step.

Installation

Add the mockserver-netty-no-dependencies artifact to your project:

<dependency>
    <groupId>org.mock-server</groupId>
    <artifactId>mockserver-netty-no-dependencies</artifactId>
    <version>5.15.0</version>
</dependency>

Choosing a client class

MockServerClient

MockServerClient connects to a MockServer instance that is already running. Use this when MockServer is started separately — for example, via Docker, the Maven plugin, or the CLI.

import org.mockserver.client.MockServerClient;

MockServerClient client = new MockServerClient("localhost", 1080);

ClientAndServer

ClientAndServer starts a MockServer instance in the current JVM process and returns a client connected to it. This is the most convenient option for unit and integration tests.

import org.mockserver.integration.ClientAndServer;

ClientAndServer mockServer = ClientAndServer.startClientAndServer(1080);

// In @AfterClass or @AfterAll:
mockServer.stop();

Use PortFactory.findFreePort() to avoid port conflicts when multiple test suites run in parallel.

Static imports

The Java API relies on static factory methods. Add these imports to every test file that uses the fluent builder API:

import static org.mockserver.model.HttpRequest.request;
import static org.mockserver.model.HttpResponse.response;
import static org.mockserver.model.Cookie.cookie;
import static org.mockserver.model.Parameter.param;
import org.mockserver.verify.VerificationTimes;

Creating expectations

Call .when(request) to match a request, then chain .respond(response) to define the action.

new MockServerClient("localhost", 1080)
    .when(
        request()
            .withMethod("GET")
            .withPath("/view/cart")
            .withCookies(
                cookie("session", "4930456C-C718-476F-971F-CB8E047AB349")
            )
            .withQueryStringParameters(
                param("cartId", "055CA455-1DF7-45BB-8535-4F83E7266092")
            )
    )
    .respond(
        response()
            .withBody("some_response_body")
    );

To limit how many times the expectation fires, pass a Times constraint:

new MockServerClient("localhost", 1080)
    .when(
        request().withPath("/some/path"),
        Times.exactly(2)
    )
    .respond(
        response().withBody("some_response_body")
    );

Connecting over TLS

Pass .withSecure(true) to send client requests over HTTPS:

new MockServerClient("localhost", 1080)
    .withSecure(true)
    .when(
        request()
            .withMethod("GET")
            .withPath("/view/cart")
    )
    .respond(
        response().withBody("some_response_body")
    );

Verifying requests

Verify by count

Check that a request was received a specific number of times:

new MockServerClient("localhost", 1080)
    .verify(
        request().withPath("/some/path"),
        VerificationTimes.atLeast(2)
    );

new MockServerClient("localhost", 1080)
    .verify(
        request().withPath("/some/path"),
        VerificationTimes.exactly(2)
    );

new MockServerClient("localhost", 1080)
    .verify(
        request().withPath("/some/path"),
        VerificationTimes.atMost(2)
    );

Verify a sequence

Pass multiple request matchers to .verify() to assert that they were received in order:

new MockServerClient("localhost", 1080)
    .verify(
        request().withPath("/some/path/one"),
        request().withPath("/some/path/two"),
        request().withPath("/some/path/three")
    );

MockServer confirms that each request in the list was received at least once, in that exact order.

Retrieving recorded requests

Retrieve all requests MockServer has received that match a given matcher:

RequestDefinition[] recordedRequests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );

Retrieve matching request-response pairs:

LogEventRequestAndResponse[] pairs = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequestsAndResponses(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );

Clearing and resetting state

Clear matching state

Remove expectations and recorded requests that match a specific request pattern:

new MockServerClient("localhost", 1080).clear(
    request().withPath("/some/path")
);

Clear only the log (recorded requests and responses), leaving expectations intact:

new MockServerClient("localhost", 1080).clear(
    request().withPath("/some/path"),
    ClearType.LOG
);

Clear only expectations, leaving the request log intact:

new MockServerClient("localhost", 1080).clear(
    request().withPath("/some/path"),
    ClearType.EXPECTATIONS
);

Reset all state

Remove all expectations and the entire request log:

new MockServerClient("localhost", 1080).reset();

Test framework integration

JUnit 4 — `@Rule`

Add the mockserver-junit-rule-no-dependencies dependency:

<dependency>
    <groupId>org.mock-server</groupId>
    <artifactId>mockserver-junit-rule-no-dependencies</artifactId>
    <version>5.15.0</version>
    <scope>test</scope>
</dependency>

Use the MockServerRule in your test class. MockServer starts before any test runs and stops after all tests complete. Any field of type MockServerClient is automatically injected:

import org.junit.Rule;
import org.junit.Test;
import org.mockserver.client.MockServerClient;
import org.mockserver.junit.MockServerRule;

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

public class MyServiceTest {

    @Rule
    public MockServerRule mockServerRule = new MockServerRule(this);

    private MockServerClient mockServerClient;

    @Test
    public void shouldReturnCartBody() {
        mockServerClient
            .when(
                request()
                    .withMethod("GET")
                    .withPath("/view/cart")
            )
            .respond(
                response()
                    .withStatusCode(200)
                    .withBody("cart contents")
            );

        // ... call your system under test here ...

        mockServerClient.verify(
            request().withPath("/view/cart"),
            VerificationTimes.atLeast(1)
        );
    }
}

JUnit 5 — `@ExtendWith`

Add the mockserver-junit-jupiter-no-dependencies dependency:

<dependency>
    <groupId>org.mock-server</groupId>
    <artifactId>mockserver-junit-jupiter-no-dependencies</artifactId>
    <version>5.15.0</version>
    <scope>test</scope>
</dependency>

Use @ExtendWith(MockServerExtension.class). MockServer injects a ClientAndServer (or MockServerClient) via constructor or method parameter resolution:

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockserver.client.MockServerClient;
import org.mockserver.integration.ClientAndServer;
import org.mockserver.junit.jupiter.MockServerExtension;
import org.mockserver.junit.jupiter.MockServerSettings;

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

@ExtendWith(MockServerExtension.class)
@MockServerSettings(ports = {8787, 8888})
class MyServiceTest {

    private final ClientAndServer client;

    public MyServiceTest(ClientAndServer client) {
        this.client = client;
    }

    @Test
    void shouldReturnResponse() {
        client
            .when(
                request()
                    .withMethod("GET")
                    .withPath("/api/resource")
            )
            .respond(
                response()
                    .withStatusCode(200)
                    .withBody("{\"status\": \"ok\"}")
            );

        // ... exercise your code ...
    }
}

Omit @MockServerSettings to let MockServer pick a free port automatically.

Standalone test class with `@BeforeClass`

If you prefer not to use a rule or extension, use ClientAndServer.startClientAndServer in a static setup method:

import org.junit.AfterClass;
import org.junit.BeforeClass;
import org.junit.Test;
import org.mockserver.integration.ClientAndServer;
import org.mockserver.socket.PortFactory;

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

public class MyServiceTest {

    private static ClientAndServer mockServer;

    @BeforeClass
    public static void startMockServer() {
        mockServer = ClientAndServer.startClientAndServer(PortFactory.findFreePort());
    }

    @AfterClass
    public static void stopMockServer() {
        if (mockServer != null) {
            mockServer.stop();
        }
    }

    @Test
    public void shouldHandleLogin() {
        mockServer
            .when(
                request()
                    .withMethod("POST")
                    .withPath("/login")
            )
            .respond(
                response()
                    .withStatusCode(200)
                    .withBody("welcome")
            );

        mockServer.verify(
            request().withPath("/login"),
            VerificationTimes.atLeast(1)
        );
    }
}

Binding additional ports

Instruct a running MockServer to start listening on additional ports:

// Bind to two OS-assigned free ports
List<Integer> freePorts = new MockServerClient("localhost", 1080).bind(0, 0);

// Bind to specific ports
List<Integer> boundPorts = new MockServerClient("localhost", 1080).bind(1081, 1082);

REST API

Client SDKs

Installation

Choosing a client class

MockServerClient

ClientAndServer

Static imports

Creating expectations

Connecting over TLS

Verifying requests

Verify by count

Verify a sequence

Retrieving recorded requests

Clearing and resetting state

Clear matching state

Reset all state

Test framework integration

JUnit 4 — `@Rule`

JUnit 5 — `@ExtendWith`

Standalone test class with `@BeforeClass`

Binding additional ports

REST API

Client SDKs

​Installation

​Choosing a client class

​MockServerClient

​ClientAndServer

​Static imports

​Creating expectations

​Connecting over TLS

​Verifying requests

​Verify by count

​Verify a sequence

​Retrieving recorded requests

​Clearing and resetting state

​Clear matching state

​Reset all state

​Test framework integration

​JUnit 4 — @Rule

​JUnit 5 — @ExtendWith

​Standalone test class with @BeforeClass

​Binding additional ports

Installation

Choosing a client class

MockServerClient

ClientAndServer

Static imports

Creating expectations

Connecting over TLS

Verifying requests

Verify by count

Verify a sequence

Retrieving recorded requests

Clearing and resetting state

Clear matching state

Reset all state

Test framework integration

JUnit 4 — `@Rule`

JUnit 5 — `@ExtendWith`

Standalone test class with `@BeforeClass`

Binding additional ports