> ## Documentation Index
> Fetch the complete documentation index at: https://moeck.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Java Client

> Control MockServer from Java using MockServerClient or ClientAndServer.

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:

<CodeGroup>
  ```xml Maven theme={null}
  <dependency>
      <groupId>org.mock-server</groupId>
      <artifactId>mockserver-netty-no-dependencies</artifactId>
      <version>5.15.0</version>
  </dependency>
  ```

  ```groovy Gradle theme={null}
  testImplementation 'org.mock-server:mockserver-netty-no-dependencies:5.15.0'
  ```
</CodeGroup>

## 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.

```java theme={null}
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.

```java theme={null}
import org.mockserver.integration.ClientAndServer;

ClientAndServer mockServer = ClientAndServer.startClientAndServer(1080);

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

<Tip>
  Use `PortFactory.findFreePort()` to avoid port conflicts when multiple test
  suites run in parallel.
</Tip>

## Static imports

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

```java theme={null}
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.

```java theme={null}
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:

```java theme={null}
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:

```java theme={null}
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:

```java theme={null}
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:

```java theme={null}
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:

```java theme={null}
RequestDefinition[] recordedRequests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );
```

Retrieve matching request-response pairs:

```java theme={null}
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:

```java theme={null}
new MockServerClient("localhost", 1080).clear(
    request().withPath("/some/path")
);
```

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

```java theme={null}
new MockServerClient("localhost", 1080).clear(
    request().withPath("/some/path"),
    ClearType.LOG
);
```

Clear only expectations, leaving the request log intact:

```java theme={null}
new MockServerClient("localhost", 1080).clear(
    request().withPath("/some/path"),
    ClearType.EXPECTATIONS
);
```

### Reset all state

Remove all expectations and the entire request log:

```java theme={null}
new MockServerClient("localhost", 1080).reset();
```

## Test framework integration

### JUnit 4 — `@Rule`

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

```xml theme={null}
<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:

```java theme={null}
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:

```xml theme={null}
<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:

```java theme={null}
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:

```java theme={null}
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:

```java theme={null}
// 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);
```