Running MockServer

MockServer supports multiple deployment options. Choose the one that fits your environment.

All deployment options (except the deployable WAR) use a single port for HTTP, HTTPS, and SOCKS traffic via port unification. You do not need to configure separate ports for different protocols.

Run MockServer as a Docker container:

docker run -d --rm -p 1080:1080 mockserver/mockserver

MockServer is now available at http://localhost:1080.Configure via environment variablesPass configuration options as environment variables:

docker run -d --rm \
  -p 1090:1090 \
  --env MOCKSERVER_LOG_LEVEL=TRACE \
  --env MOCKSERVER_SERVER_PORT=1090 \
  mockserver/mockserver

Docker ComposeAdd MockServer as a service in your docker-compose.yml:

version: "2.4"
services:
  mockServer:
    image: mockserver/mockserver:5.15.0
    ports:
      - 1080:1080
    environment:
      MOCKSERVER_MAX_EXPECTATIONS: 100
      MOCKSERVER_MAX_HEADER_SIZE: 8192

To mount a properties file or JSON expectation initializer:

version: "2.4"
services:
  mockServer:
    image: mockserver/mockserver:5.15.0
    ports:
      - 1080:1080
    environment:
      MOCKSERVER_PROPERTY_FILE: /config/mockserver.properties
      MOCKSERVER_INITIALIZATION_JSON_PATH: /config/initializerJson.json
    volumes:
      - type: bind
        source: .
        target: /config

MockServer uses a distroless base image (no interactive shell) for reduced attack surface. Only the JVM and MockServer code are included in the container.

Deploy MockServer to any Kubernetes cluster using the official Helm chart.Add the chart repository

helm repo add mockserver https://www.mock-server.com
helm repo update

Install the chart

helm upgrade --install \
  --kube-context <your kube context> \
  --namespace mockserver \
  --create-namespace \
  --version 5.15.0 \
  mockserver mockserver/mockserver

After installation, MockServer is available inside the cluster at mockserver.mockserver.svc.cluster.local.Configure the deploymentPass configuration values with --set:

helm upgrade --install \
  --namespace mockserver \
  --set app.serverPort=1080 \
  --set app.logLevel=INFO \
  mockserver mockserver/mockserver

Supported values include:

Value	Default	Description
`app.serverPort`	`1080`	Port MockServer listens on
`app.logLevel`	`INFO`	Log verbosity
`app.proxyRemoteHost`	—	Host to forward proxy requests to
`app.proxyRemotePort`	—	Port to forward proxy requests to
`app.jvmOptions`	—	Additional JVM options
`image.snapshot`	`false`	Use the latest snapshot image

Check deployment status

kubectl -n mockserver rollout status deployments mockserver

View logs

kubectl -n mockserver logs --tail=100 -l app=mockserver,release=mockserver

Access from outside the cluster (port-forward)

kubectl -n mockserver port-forward svc/mockserver 1080:1080 &
export MOCKSERVER_HOST=127.0.0.1:1080

Remove the chart

helm delete -n mockserver mockserver

Use the Maven plugin to start MockServer automatically as part of your build lifecycle.Add the plugin to your pom.xml:

<plugin>
    <groupId>org.mock-server</groupId>
    <artifactId>mockserver-maven-plugin</artifactId>
    <version>5.15.0</version>
    <configuration>
        <serverPort>1080</serverPort>
        <logLevel>DEBUG</logLevel>
        <initializationClass>org.mockserver.maven.ExampleInitializationClass</initializationClass>
    </configuration>
    <executions>
        <execution>
            <id>process-test-classes</id>
            <phase>process-test-classes</phase>
            <goals>
                <goal>start</goal>
            </goals>
        </execution>
        <execution>
            <id>verify</id>
            <phase>verify</phase>
            <goals>
                <goal>stop</goal>
            </goals>
        </execution>
    </executions>
</plugin>

This starts MockServer in the process-test-classes phase and stops it in the verify phase, so your tests can use it during the test and integration-test phases.Run from the command line

mvn mockserver:run

Or start MockServer as a forked JVM:

mvn -Dmockserver.serverPort=1080 -Dmockserver.logLevel=INFO \
  org.mock-server:mockserver-maven-plugin:5.15.0:runForked

Stop the forked instance:

mvn -Dmockserver.serverPort=1080 \
  org.mock-server:mockserver-maven-plugin:5.15.0:stopForked

If you use the runForked goal and a test fails, Maven skips the verify phase, so MockServer will not be stopped. Use the start and stop goals instead to ensure MockServer always shuts down, even on test failures.

Use the Java client APITo control MockServer programmatically, add the client dependency:

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

Then start and stop MockServer in your test lifecycle:

import static org.mockserver.integration.ClientAndServer.startClientAndServer;

private ClientAndServer mockServer;

@Before
public void startMockServer() {
    mockServer = startClientAndServer(1080);
}

@After
public void stopMockServer() {
    mockServer.stop();
}

Install the npm module:

npm install mockserver-node --save-dev

Start and stop from Node.js

var mockserver = require('mockserver-node');

mockserver.start_mockserver({
    serverPort: 1080,
    verbose: true,
    trace: true
});

// run tests

mockserver.stop_mockserver({
    serverPort: 1080
});

Grunt pluginAdd start_mockserver and stop_mockserver tasks to your Gruntfile:

grunt.initConfig({
    start_mockserver: {
        start: {
            options: {
                serverPort: 1080,
                trace: true
            }
        }
    },
    stop_mockserver: {
        stop: {
            options: {
                serverPort: 1080
            }
        }
    }
});

grunt.loadNpmTasks('mockserver-node');

The request log is only captured when trace: true or verbose: true is set. You must enable one of these options to use the /retrieve endpoint for verification.

Download mockserver-netty-no-dependencies-5.15.0.jar from Maven Central, then run:

java -jar mockserver-netty-no-dependencies-5.15.0.jar -serverPort 1080

Available options

java -jar mockserver-netty-no-dependencies-5.15.0.jar \
  -serverPort <port> \
  [-proxyRemotePort <port>] \
  [-proxyRemoteHost <hostname>] \
  [-logLevel <level>] \
  [-jvmOptions <system parameters>]

Option	Required	Description
`-serverPort`	Yes	HTTP, HTTPS, and SOCKS port(s). Supports comma-separated list for multiple ports.
`-proxyRemotePort`	No	Enables port forwarding. Requests are forwarded to this port unless they match an expectation.
`-proxyRemoteHost`	No	Host for forwarded proxy requests. Defaults to `localhost` if not set.
`-logLevel`	No	SLF4J levels: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `OFF`. Defaults to `INFO`.
`-jvmOptions`	No	Generic JVM options or system properties.

Example — bind two ports with INFO logging

java -jar mockserver-netty-no-dependencies-5.15.0.jar \
  -serverPort 1080,1081 \
  -logLevel INFO

Homebrew (macOS)

brew install mockserver
mockserver -serverPort 1080

Add the JUnit 4 rule dependency:

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

Annotate a field in your test class with @Rule:

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

private MockServerClient mockServerClient;

MockServerRule starts MockServer on a free port before any test runs and stops it after all tests complete. An instance of MockServerClient is automatically assigned to any field of type org.mockserver.client.MockServerClient.Constructor options

// Dynamically allocate a free port
public MockServerRule(Object target);

// Control whether one instance is shared per JVM or per test class
public MockServerRule(Object target, boolean perTestSuite);

// Bind to specific port(s)
public MockServerRule(Object target, Integer... ports);

Add the JUnit 5 extension dependency:

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

Annotate your test class with @ExtendWith(MockServerExtension.class):

@ExtendWith(MockServerExtension.class)
class ExampleTestClass {
    private final ClientAndServer client;

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

    @Test
    void testSomething() {
        // use client to create expectations and verify requests
    }
}

MockServer starts before any test runs and stops after all tests complete. A MockServerClient or ClientAndServer instance is injected via JUnit 5 parameter resolution into constructors, @BeforeEach/@BeforeAll methods, and test methods.Bind to specific portsUse @MockServerSettings to control which ports MockServer binds to:

@ExtendWith(MockServerExtension.class)
@MockServerSettings(ports = {8787, 8888})
class ExampleTestClass {
    private final ClientAndServer client;

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

    @Test
    void testSomething() {
        // ...
    }
}

Add the Spring test listener dependency:

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

Annotate your test class with @MockServerTest:

@MockServerTest
@RunWith(SpringRunner.class)
public class ExampleSpringTest {

    private MockServerClient mockServerClient;

    @Test
    public void testSomething() {
        // use mockServerClient to create expectations and verify requests
    }
}

The mockserver-spring-test-listener registers a Spring TestExecutionListener that starts MockServer on a free port when the test class is annotated with @MockServerTest. MockServer resets after each test and closes via a shutdown hook after all tests complete.Inject the port into Spring propertiesUse the ${mockServerPort} placeholder to configure a Spring bean with the MockServer URL:

@RunWith(SpringRunner.class)
@MockServerTest("server.url=http://localhost:${mockServerPort}/path")
@ContextConfiguration(classes = MyTestConfig.class)
public class ExampleSpringTestWithUrl {

    @Autowired
    private MyClient client;

    private MockServerClient mockServerClient;

    @Test
    public void testSomething() {
        // ...
    }
}

Inject the port directly

@MockServerTest
@RunWith(SpringRunner.class)
public class ExampleSpringTestWithPort {

    @MockServerPort
    Integer mockServerPort;

    @Test
    public void testSomething() {
        // ...
    }
}

@MockServerTest does not support parallel test execution because the MockServer instance is shared across all test classes. To run tests in parallel, use a unique value in each request matcher to avoid conflicts.

Get Started

Mocking

Proxying

Configuration

Debugging