Running MockServer

MockServer is flexible and support numerous usage patterns.

MockServer can be run:

programmatically via a Java API in an @Before or @After method
using a JUnit 4 @Rule via a @Rule annotated field in a JUnit 4 test
using a JUnit 5 Test Extension via a @ExtendWith annotated JUnit 5 class
using a Spring Test Execution Listener via a @MockServerTest annotated test class
as a Docker container in any Docker enabled environment
via a Helm chart in any Kubernetes environment
from the command line as a stand-alone process in a test environment
via a Maven Plugin as part of a Maven build cycle
as a Node.js (npm) module from any Node.js code
as a Grunt plugin as part of a Grunt build cycle
as a deployable WAR to an existing application server

To simplify configuration all versions (except the deployable WAR) use a single port to support the control plane and data plane in HTTP, HTTPS or SOCKS.

MockServer is available in the following formats:

java dependency
Docker container
Helm chart for Kubernetes
executable jar
Homebrew package
maven plugin
npm plugin
Grunt plugin
deployable WAR that runs on JEE web servers

It is also possible to build and run MockServer directly from source code

MockServer UI:

MockServer has a UI that can be used to view the internal state within MockServer, including:

logs
active expectations
requests received
proxied requests

Maven Plugin

To run MockServer as part of your build add the following 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 will start MockServer during the process-test-classes phase and will stop MockServer during the verify phase. For more details about Maven build phases see: Introduction to the Build Lifecycle.

This ensures that any integration tests you run during the test or integration-test phases can use MockServer on the port specified.

It is also possible to run MockServer as a forked JVM using the runForked and stopForked goals as follows:

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

Stop MockServer Even When Tests Fail

If you use the runForked goal as above and the test phase fails (because a test has failed) MockServer will not be stopped as Maven does not run any more phases after a phase has failed. In the case above the verify phase is not run if a test fails so the forked MockServer will not be stopped.

If you want to ensure MockServer is stopped even when there are test failures make sure you use start and stop goals as these run MockServer on a separate thread that is stopped however maven exits (even if a test fails).

Alternatively a TestListener can be used with maven-surefire-plugin to ensure that MockServer is stopped even when a test fails, as follows:

 <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-surefire-plugin</artifactId>
    <version>3.5.5</version>
    <configuration>
        <properties>
            <property>
                <name>listener</name>
                <value>org.mockserver.maven.StopMockServerTestListener</value>
            </property>
        </properties>
    </configuration>
</plugin>

The Maven plugin can also be used from the command line to start and stop MockServer, as follows:

To run MockServer synchronously and block:

mvn mockserver:run

To run MockServer asynchronously as a forked JVM:

mvn mockserver:runForked

Or:

mvnw org.mock-server:mockserver-maven-plugin:5.15.0:runForked -DserverPort=1080

To stop a forked instance of MockServer running on the same machine:

mvn mockserver:stopForked

Or:

mvnw org.mock-server:mockserver-maven-plugin:5.15.0:stopForked -DserverPort=1080

The stopForked goal assumes that MockServer is running on the same physical machine as it uses 127.0.0.1 to communicate with MockServer stop socket.

The Maven plugin has the following goals:

start - start MockServer, do not block, but stop when build ends
stop - stop a MockServer started earlier as part of the current build
run - run MockServer and block waiting for requests (timeout config if provided limits how long to block for)
runForked - run MockServer as separate forked JVM, do not block, stay alive when build ends
stopForked - stop a forked MockServer, previously started by a runForked goal

The Maven plugin can be configured with the following properties:

serverPort - The port the MockServer listens for incoming request. Port unification is used to support both HTTP and HTTPS on the same port (required: true)
proxyRemotePort - The port proxied requests are forwarded to (required: false)
proxyRemoteHost - The host proxied requests are forwarded to (required: false)
timeout - How long to block waiting for MockServer, after the timeout the plugin will shutdown MockServer, used by run goal, 0 means wait indefinitely (required: false, default: 0)
logLevel - The logging level (required: false, default: INFO)
skip - Prevent the plugin from running (required: false, default: false)
initializationClass - To enable the creation of default expectations a class can be specified to initialize expectations in MockServer, this class must implement org.mockserver.client.initialize.PluginExpectationInitializer interface. The initializeExpectations(MockServerClient mockServerClient) method will be called once MockServer has been started. Note: that the plugin must be started during the process-test-classes to ensure that the initialization class has been compiled from either src/main/java or src/test/java locations. In addition the initializer can only be used with start and run goals, it will not work with the runForked goal as a JVM is forked with a separate classpath. (required: false, default: false)

Client API - starting and stopping

Use the client API to run or interact with MockServer programmatically.

For more details about the different dependency versions see the page on Maven Central

For example add the following maven dependency:

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

To start the server or proxy create a client, for example by using one of the start factory methods ClientAndServer.startClientAndServer as follows:

Add includes:

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

Add fields:

private ClientAndServer mockServer;

Use factory method to start server and client when appropriate, for example in @Before method:

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

Stop server and client when appropriate, for example in @After method:

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

The mockserver-example project contains an example test called BookPageIntegrationTest that demonstrates a fully working example.

Running MockServer via a JUnit 4 @Rule

MockServer can be run using the MockServerRule. The MockServerRule starts MockServer (for both mocking and proxying) on a free port before the any test runs and stops MockServer after all tests have completed.

An instance of MockServerClient is assigned to any field in the unit test of type org.mockserver.client.MockServerClient. Alternatively an instance of MockServerClient can be retrieved from the MockServerRule using the method getClient().

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

private MockServerClient mockServerClient;

The MockServerRule can be added to your project by including the following maven dependency:

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

Any test method can now use the mockServerClient field to create expectation or verify requests.

The MockServerRule has the following constructors:

/**
 * Start MockServer prior to test execution and stop MockServer after the tests have completed.
 * This constructor dynamically allocates a free port for MockServer to use.
 *
 * @param target an instance of the test being executed
 */
public MockServerRule(Object target);

/**
 * Start MockServer prior to test execution and stop MockServer after the tests have completed.
 * This constructor dynamically allocates a free port for MockServer to use.
 *
 * @param target an instance of the test being executed
 * @param perTestSuite indicates how many instances of MockServer are created
 *                     if true a single MockServer is created per JVM
 *                     if false one instance per test class is created
 */
public MockServerRule(Object target, boolean perTestSuite);
/**
 * Start the proxy prior to test execution and stop the proxy after the tests have completed.
 * This constructor dynamically create a proxy that accepts HTTP(S) requests on the specified port
 *
 * @param target an instance of the test being executed
 * @param port the HTTP(S) port for the proxy
 */
public MockServerRule(Object target, Integer... ports);

/**
 * Start the proxy prior to test execution and stop the proxy after the tests have completed.
 * This constructor dynamically create a proxy that accepts HTTP(S) requests on the specified port
 *
 * @param target an instance of the test being executed
 * @param perTestSuite indicates how many instances of MockServer are created
 *                     if true a single MockServer is created per JVM
 *                     if false one instance per test class is created
 * @param port the HTTP(S) port for the proxy
 */
public MockServerRule(Object target, boolean perTestSuite, Integer... ports);

Running MockServer via a JUnit 5 Test Extension

MockServer can be run using the Test Extension MockServerExtension. The MockServerExtension starts MockServer (for both mocking and proxying) before the any test runs and stops MockServer after all tests have completed.

The port(s) MockServer uses can be controlled using MockServerSettings

An instance of MockServerClient or ClientAndServer is injected into any method using Parameter Resolution this includes: constructors, lifecycle methods (like @BeforeEach / @BeforeAll), or test methods.

The MockServerExtension Test Extension can be added to your project by including the following maven dependency:

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

Warning: @MockServerSettings already includes @ExtendWith(MockServerExtension.class) internally. Do not add both annotations to the same test class — doing so will cause MockServer to start twice, resulting in port conflicts or unexpected behaviour. Use @ExtendWith(MockServerExtension.class) alone for default settings, or @MockServerSettings alone when you need to configure ports or other options.

The following code examples show how to use the MockServerExtension Test Extension.

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

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

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

}

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

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

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

}

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

    @BeforeEach
    public void beforeEachLifecycleMethod(MockServerClient client) {
        this.client = client;
    }

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

}

@ExtendWith(MockServerExtension.class)
class ExampleTestClass {

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

}

Running MockServer via Spring TestExecutionListener @MockServerTest

MockServer can be run using @MockServerTest. The mockserver-spring-test-listener dependency registers a Spring TestExecutionListener which starts MockServer on a free port if the test class is annotated with @MockServerTest. MockServer is reset after each test and closed after all tests via a shutdown hook.

As the MockServer instance is shared between all test classes @MockServerTest does not support parallel test execution, unless each test uses a unique value in each request matcher.

The TestExecutionListener with @MockServerTest can be added to your project by including the following maven dependency:

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

An instance of MockServerClient is assigned to any field in the unit test of type org.mockserver.client.MockServerClient.

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

    private MockServerClient mockServerClient;

    @Test
    public void testSomething() {
        // test code
    }

}

If you want to configure a client (Spring Bean) to use MockServer you can create a test property with ${mockServerPort} placeholder. This is replaced by the chosen free port for MockServer.

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

    static class Client {
        @Value("${server.url}")
        private URI serverUrl;

        private final RestTemplate restTemplate = new RestTemplate();

        @Nullable
        public <T> T getResult(String path, Class<T> responseType) {
            return restTemplate.getForObject(serverUrl + path, responseType);
        }
    }

    static class Config {
        @Bean
        public Client client() {
            return new Client();
        }
    }

    @Autowired
    private Client client;

    private MockServerClient mockServerClient;

    @Test
    public void testSomething() {
        // test code
    }

}

Properties prefixed with mockserver. are applied to the MockServer Configuration object, allowing declarative configuration of MockServer directly in the annotation. All other properties are injected into the Spring Environment as test properties (with ${mockServerPort} substitution). This enables setting any configuration property such as initializationClass, logLevel, maxExpectations, etc. without needing separate system property setup.

Note: Because the MockServer instance is shared across all test classes, mockserver.* configuration properties from the first @MockServerTest class to run are used. If multiple test classes specify different mockserver.* properties, only the first class's configuration takes effect.

@RunWith(SpringRunner.class)
@MockServerTest({
    "server.url=http://localhost:${mockServerPort}/path",
    "mockserver.initializationClass=org.mockserver.server.initialize.ExpectationInitializerExample",
    "mockserver.logLevel=WARN"
})
public class ExampleSpringTestListenerTestWithConfiguration {

    private MockServerClient mockServerClient;

    @Test
    public void testSomething() {
        // expectations from ExpectationInitializerExample are available immediately
    }

}

The free port itself is also added as test property and can be retrieved with @MockServerPort.

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

    @MockServerPort
    Integer mockServerPort;

    @Test
    public void testSomething() {
        // test code
    }

}

Running From Command Line

MockServer can be run from the command line in the following ways:

using homebrew i.e. brew install mockserver && mockserver
using java directly i.e. java -jar mockserver-netty-5.15.0-no-dependencies.jar
using maven plugin i.e. mvn org.mock-server:mockserver-maven-plugin:5.15.0:runForked
using docker i.e. docker run -d --rm -p 1080:1080 mockserver/mockserver

Running From Command Line - Using Homebrew

Homebrew, a packaging manager for OS X (i.e. Apple Mac), can be used to install MockServer, as follows:

brew install mockserver

The MockServer formula in Homebrew performs the following actions:

installed the binaries and scripts
creates the log directory
add the scripts to the PATH variable

Once the MockServer has been installed by Homebrew it is available from any command shell as the mockserver command

The mockserver command supports the following options:

mockserver -serverPort <port> [-proxyRemotePort <port>]  [-proxyRemoteHost <hostname>] [-logLevel <level>] [-jvmOptions <system parameters>]

 valid options are:
    -serverPort <port>           The HTTP, HTTPS, SOCKS and HTTP CONNECT
                                 port(s) for both mocking and proxying
                                 requests.  Port unification is used to
                                 support all protocols for proxying and
                                 mocking on the same port(s). Supports
                                 comma separated list for binding to
                                 multiple ports.

    -proxyRemotePort <port>      Optionally enables port forwarding mode.
                                 When specified all requests received will
                                 be forwarded to the specified port, unless
                                 they match an expectation.

    -proxyRemoteHost <hostname>  Specified the host to forward all proxy
                                 requests to when port forwarding mode has
                                 been enabled using the proxyRemotePort
                                 option.  This setting is ignored unless
                                 proxyRemotePort has been specified. If no
                                 value is provided for proxyRemoteHost when
                                 proxyRemotePort has been specified,
                                 proxyRemoteHost will default to \"localhost\".

    -logLevel <level>            Optionally specify log level using SLF4J levels:
                                 TRACE, DEBUG, INFO, WARN, ERROR, OFF or Java
                                 Logger levels: FINEST, FINE, INFO, WARNING,
                                 SEVERE or OFF. If not specified default is INFO

    -jvmOptions <level>          Specified generic JVM options or system properties.

i.e. mockserver -logLevel INFO -serverPort 1080,1081 -proxyRemotePort 80 -proxyRemoteHost www.mock-server.com

For example run the MockServer, as follows:

mockserver -logLevel INFO -serverPort 1080

Running From Command Line - Using Java

MockServer can be run directly from the command line using java directly as follow:

download mockserver-netty-5.15.0-no-dependencies.jar from Maven Central
java -jar <path to mockserver-netty-5.15.0-no-dependencies.jar> -serverPort <port>

The command line supports the following options:

java -jar <path to mockserver-netty-no-dependencies-5.15.0.jar> -serverPort <port> [-proxyRemotePort <port>] [-proxyRemoteHost <hostname>] [-logLevel <level>]

 valid options are:
    -serverPort <port>           The HTTP, HTTPS, SOCKS and HTTP CONNECT
                                 port(s) for both mocking and proxying
                                 requests.  Port unification is used to
                                 support all protocols for proxying and
                                 mocking on the same port(s). Supports
                                 comma separated list for binding to
                                 multiple ports.

    -proxyRemotePort <port>      Optionally enables port forwarding mode.
                                 When specified all requests received will
                                 be forwarded to the specified port, unless
                                 they match an expectation.

    -proxyRemoteHost <hostname>  Specified the host to forward all proxy
                                 requests to when port forwarding mode has
                                 been enabled using the proxyRemotePort
                                 option.  This setting is ignored unless
                                 proxyRemotePort has been specified. If no
                                 value is provided for proxyRemoteHost when
                                 proxyRemotePort has been specified,
                                 proxyRemoteHost will default to \"localhost\".

    -logLevel <level>            Optionally specify log level using SLF4J levels:
                                 TRACE, DEBUG, INFO, WARN, ERROR, OFF or Java
                                 Logger levels: FINEST, FINE, INFO, WARNING,
                                 SEVERE or OFF. If not specified default is INFO

i.e. java -jar ./mockserver-netty-no-dependencies-5.15.0.jar -serverPort 1080 -proxyRemotePort 80 -proxyRemoteHost www.mock-server.com

For example:

java -jar ~/Downloads/mockserver-netty-no-dependencies-5.15.0.jar -serverPort 1080,1081 -logLevel INFO

All interactions with the MockServer are logged including setting up expectations, matching expectations, clearing expectations and verifying requests. This log information can be particularly helpful when trying to debug why a test is failing or expectations are not being matched.

The argument logLevel can be used to set the log level, as shown above. It is also possible to further customise where loggers send log events by overriding the default logging configuration.

Running From Command Line - Using Maven Plugin

MockServer can be run directly from the command line and using the mockserver-maven-plugin as follow:

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

When run from the command line the Maven plugin can be configured with the following properties:

mockserver.serverPort - The port the MockServer listens for incoming request. Port unification is used to support both HTTP and HTTPS and proxying on the same port (required: false)
mockserver.logLevel - The logging level (required: false, default: INFO)

The runForked goal of the mockserver-maven-plugin will fork a JVM process containing the Netty based MockServer. To stop the forked JVM process use the stopForked goal, as follows:

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

For more information on the mockserver-maven-plugin see the section on MockServer Maven Plugin

Web Archive (WAR)

To run as a WAR deployed on any JEE web server:

download mockserver-war-5.15.0.war from Maven Central
deploy mockserver-war-5.15.0.war to any JEE web server

WAR Context Path

The WAR context path is ignored from all request matching for path.

The MockServerClient constructor includes an argument for the context path that the WAR has been deployed to, as follows:

public MockServerClient(String host, int port, String contextPath)

NPM Module & MockServer Grunt Plugin

The node module can be used to start and stop MockServer as a node module or as a Grunt plugin.

You may install this plugin / node module with the following command:

npm install mockserver-node --save-dev

Node Module

To start or stop the MockServer from any Node.js code you need to import this module using require('mockserver-node') as follows:

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

Then you can use either the start_mockserver or stop_mockserver functions as follows:

var mockserver = require('mockserver-node');
mockserver.start_mockserver({
                serverPort: 1080,
                verbose: true,
                trace: true
            });

// do something

mockserver.stop_mockserver({
                serverPort: 1080
            });

You can customize the JVM arguments and set configuration options as follows

var mockserver = require('mockserver-node');
mockserver.start_mockserver({
              serverPort: 1080,
              jvmOptions: [
                  '-Dmockserver.enableCORSForAllResponses=true',
                  '-Dmockserver.corsAllowMethods="CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE"',
                  '-Dmockserver.corsAllowHeaders="Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization"',
                  '-Dmockserver.corsAllowCredentials=true'
                  '-Dmockserver.corsMaxAgeInSeconds=300'
              ],
              mockServerVersion: "5.15.0",
              verbose: true
          });

MockServer uses port unification to support HTTP, HTTPS, SOCKS, HTTP CONNECT, Port Forwarding Proxying on the same port. A client can then connect to the single port with both HTTP and HTTPS as the socket will automatically detected SSL traffic and decrypt it when required.

Grunt Plugin

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins.

In your project's Gruntfile, add a section named start_mockserver and stop_mockserver to the data object passed into grunt.initConfig().

The following example will result in a both a MockServer being started on ports 1080 and 1080.

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

grunt.loadNpmTasks('mockserver-node');

Request Log

The request log will only be captured in MockServer if the log level is INFO (or more verbose, i.e. DEBUG or TRACE) therefore to capture the request log and use the /retrieve endpoint ensure either the option trace: true or the command line switch --verbose is set.

Grunt Plugin & NPM Module Options

options.serverPort

Type: Integer Default: undefined

The HTTP, HTTPS, SOCKS and HTTP CONNECT port(s) for both mocking and proxying requests. Port unification is used to support all protocols for proxying and mocking on the same port(s). Supports comma separated list for binding to multiple ports.

options.proxyRemotePort

Type: Integer Default: undefined

Optionally enables port forwarding mode. When specified all requests received will be forwarded to the specified port, unless they match an expectation.

options.proxyRemoteHost

Type: String Default: undefined

Specified the host to forward all proxy requests to when port forwarding mode has been enabled using the proxyRemotePort option. This setting is ignored unless proxyRemotePort has been specified. If no value is provided for proxyRemoteHost when proxyRemotePort has been specified, proxyRemoteHost will default to "localhost".

options.artifactoryHost

Type: String Default: oss.sonatype.org

This value specifies the name of the artifact repository host.

options.artifactoryPath

Type: String Default: /content/repositories/releases/org/mock-server/mockserver-netty/

This value specifies the path to the artifactory leading to the mockserver-netty jar with dependencies.

options.mockServerVersion

Type: String Default: 5.15.0

This value specifies the artifact version of MockServer to download.

Note: It is also possible to specify a SNAPSHOT version to get the latest unreleased changes.

options.verbose

Type: Boolean Default: false

This value indicates whether the MockServer logs should be written to the console. In addition to logging additional output from the grunt task this options also sets the logging level of the MockServer to INFO. At INFO level all interactions with the MockServer including setting up expectations, matching expectations, clearing expectations and verifying requests are written to the log.

Note: It is also possible to use the --verbose command line switch to enabled verbose level logging from the command line.

options.trace

Type: Boolean Default: false

This value sets the logging level of the MockServer to TRACE. At TRACE level (in addition to INFO level information) all matcher results, including when specific matchers fail (such as HeaderMatcher) are written to the log.

options.javaDebugPort

Type: Integer Default: undefined

This value indicates whether Java debugging should be enabled and if so which port the debugger should listen on. When this options is provided the following additional option is passed to the JVM:

"-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=" + javaDebugPort

Note: suspend=y is used so the MockServer will pause until the debugger is attached. The grunt task will wait 50 seconds for the debugger to be attached before it exits with a failure status.

options.jvmOptions

Type: String Default: undefined

This value allows any system properties to be passed to the JVM that runs MockServer, for example:

start_mockserver: {
    options: {
        serverPort: 1080,
        jvmOptions: "-Dmockserver.enableCORSForAllResponses=true"
    }
}

options.startupRetries

Type: Integer Default: if javaDebugPort is not set 110, but if javaDebugPort is set 500

This value indicates the how many times we will call the check to confirm if the mock server started up correctly. It will default to 110 which will take about 11 seconds to complete, this is normally long enough for the server to startup. The server can take longer to start up if Java debugging is enabled so this will default to 500. The default will, in some cases, need to be overridden as the JVM may take longer to start up on some architectures, e.g. Mac seems to take a little longer.

Docker Container

The typical sequence for running the MockServer docker image is as follows:

Install Docker
Pull (or Update) Image
Run Container

In addition it is possible to customise how the container is run.

Install Docker

To install Docker see the installation instructions.

Pull MockServer Image

To pull the MockServer Docker image use the pull command, as follows:

docker pull mockserver/mockserver

MockServer images are also available from AWS ECR Public, which avoids Docker Hub rate limits and provides lower latency for AWS-based CI/CD:

docker pull public.ecr.aws/mockserver/mockserver

This is not strictly necessary as the image will be automatically pulled if it does not exist when the run command is used. However, using the pull command will ensure the latest version of the image is downloaded.

Run MockServer Container

Then to run MockServer as a Docker container run the following command:

docker run -d --rm -P mockserver/mockserver

The -P switch in this command tells Docker to map all ports exported by the MockServer container to dynamically allocated ports on the host machine.

To view information about the MockServer container, including which dynamic ports have been used run the following command:

docker ps

No Interactive Shell

MockServer uses distroless as its based container for both size and security and so does not contain an interactive shell. This minimises the likelihood of vulnerabilities and to reduces the attack surface by ensuring only the JVM and MockServer code is inside the container.

Configure Port Mapping

This MockServer docker container exports the following port:

serverPort 1080

To specify which ports (on the host machine) should be mapped to the MockServer docker container use the -p <host port>:<container port> option, as follows:

docker run -d --rm -p <serverPort>:1080 mockserver/mockserver

For example:

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

Environment Variables

It is possible configure MockServer behaviour through environment variables, this includes port mappings, log level and lots of other properties for example:

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

JVM Heap Size

The default JVM heap size in the Docker container is determined by the JVM's container-aware defaults (typically 25% of the container's memory limit). For high-throughput use cases or large response bodies, you may need to increase the heap size using JAVA_TOOL_OPTIONS:

docker run -d --rm -p 1080:1080 --env JAVA_TOOL_OPTIONS="-Xmx512m" mockserver/mockserver

If MockServer becomes slow or unresponsive under sustained load, see the troubleshooting guide for recommended memory and logging configuration.

Modifying Default Command

The MockServer container entrypoint calls org.mockserver.cli.Main directly with CMD [] (no default arguments). The SERVER_PORT environment variable defaults to 1080 in the Dockerfile. Command line options can be explicitly provided, for example:

docker run --rm --name mockserver -p 1080:1090 mockserver/mockserver -logLevel INFO -serverPort 1090 -proxyRemotePort 443 -proxyRemoteHost mock-server.com

Detailed MockServer Configuration

To support configuring MockServer a mockserver.properties will be loaded from /config directory if it exists.

A mockserver.properties configuration file and other related configuration files such as json expectation initialization, or custom TLS CA, X.509 Certificate or Private Key should be mapping into the /config directory.

For example to add configuration files in the current directory, such as mockserver.properties, map $(pwd) into /config, as follows:

docker run -v $(pwd):/config -p 1080:1080  mockserver/mockserver -serverPort 1080

See MockServer Configuration for details of all configuration options.

As the Docker image is based from gcr.io/distroless/java17:nonroot and the user nonroot is used, we need to configure permissions in order to allow the user in the container read/write files in mounted volumes:

chmod o+r $(pwd)/mockserver.properties

Extending MockServer Classpath

To use class callbacks or an expectation initializer class the classpath for MockServer must include the specified classes.

To support adding classes to the classpath any jar files contained in the /libs directory will be added into MockServer classpath.

For example to add all jar files in the current directory, map $(pwd) into /libs, as follows:

docker run -v $(pwd):/libs -p 1080:1080  mockserver/mockserver -serverPort 1080

Docker Health Checks

MockServer Docker images include a built-in HEALTHCHECK instruction that uses a lightweight Java health check class to verify the server is running. Since the images are based on distroless containers (no shell, no curl), the health check runs as a small Java process that calls the PUT /mockserver/status endpoint internally.

The built-in health check works automatically with no configuration required:

HEALTHCHECK --interval=10s --timeout=5s --start-period=120s --retries=3
  CMD ["java", "-cp", "/mockserver-netty-jar-with-dependencies.jar", "org.mockserver.cli.HealthCheck"]

The health check reads the SERVER_PORT or MOCKSERVER_SERVER_PORT environment variable to determine the correct port (defaults to 1080). Docker reports the container as healthy once MockServer is ready to accept requests.

Using with Docker Compose

The built-in health check integrates with Docker Compose depends_on conditions:

services:
  mockserver:
    image: mockserver/mockserver:5.15.0
    ports:
      - "1080:1080"

  app:
    image: my-app:latest
    depends_on:
      mockserver:
        condition: service_healthy

To override or disable the built-in health check, use the healthcheck key in your Compose file.

Kubernetes Liveness and Readiness Probes

In Kubernetes, use httpGet probes with the configurable liveness endpoint:

containers:
  - name: mockserver
    image: mockserver/mockserver:5.15.0
    ports:
      - containerPort: 1080
    env:
      - name: MOCKSERVER_LIVENESS_HTTP_GET_PATH
        value: "/liveness/probe"
    livenessProbe:
      httpGet:
        path: /liveness/probe
        port: 1080
      initialDelaySeconds: 10
      periodSeconds: 5
    readinessProbe:
      httpGet:
        path: /liveness/probe
        port: 1080
      initialDelaySeconds: 5
      periodSeconds: 5

The MockServer Helm chart configures these probes automatically.

Amazon ECS Health Check

For ECS task definitions, the built-in HEALTHCHECK in the Docker image is used automatically. Alternatively, configure an explicit health check:

{
  "containerDefinitions": [{
    "name": "mockserver",
    "image": "mockserver/mockserver:5.15.0",
    "healthCheck": {
      "command": ["CMD-SHELL", "curl -f http://localhost:1080/mockserver/status -X PUT || exit 1"],
      "interval": 10,
      "timeout": 5,
      "retries": 3,
      "startPeriod": 120
    }
  }]
}

Note: The ECS CMD-SHELL health check runs on the host, not inside the distroless container, so curl is available.

For more information on the liveness endpoint configuration, see liveness configuration properties.

Docker Compose

MockServer can be run using docker compose by adding the container as a service.

The MockServer container uses an entrypoint, so it is possible to configure the MockServer by specifying the command line flags using by specifying the command, as follows:

services:
  mockServer:
    image: mockserver/mockserver:5.15.0
    command: -logLevel DEBUG -serverPort 1090 -proxyRemotePort 80 -proxyRemoteHost www.mock-server.com
    ports:
      - 1080:1090

It is also possible to configure the MockServer by setting environment variables, as follows:

services:
  mockServer:
    image: mockserver/mockserver:5.15.0
    ports:
      - 1080:1090
    environment:
      MOCKSERVER_MAX_EXPECTATIONS: 100
      MOCKSERVER_MAX_HEADER_SIZE: 8192

It is also possible to configure the MockServer by mounting a volume containing a properties file or JSON expectation initializer, as follows:

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

To initialise MockServer using an OpenAPI specification file, mount the file and set the MOCKSERVER_INITIALIZATION_OPENAPI_PATH environment variable:

services:
  mockServer:
    image: mockserver/mockserver:5.15.0
    ports:
      - 1080:1080
    environment:
      MOCKSERVER_INITIALIZATION_OPENAPI_PATH: /config/petstore.yaml
    volumes:
      - type: bind
        source: .
        target: /config

Deploying MockServer Helm Chart

There are three ways to deploy the MockServer helm chart:

via chart repository
via package
via local source

Deploy Via Chart Repository

You can add the MockServer chart repository as follows:

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

Then the helm chart can be installed as follows:

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

If using get the following error:

Error: failed to download "mockserver/mockserver" at version "5.15.0"

Then update local cache of helm charts:

helm repo update

Deploy Via Package

To run MockServer in Kubernetes the easiest way is to use the existing MockServer helm chart.

This is available by using www.mock-server.com as a chart repo, with the following command:

helm upgrade --install --namespace mockserver mockserver http://www.mock-server.com/mockserver-5.15.0.tgz

Deploy Via Local Source

If you have helm chart source folder (i.e. you have the repository cloned):

helm upgrade --install --namespace mockserver mockserver helm/mockserver

The commands above will install MockServer into a namespace called mockserver with default configuration (as per the embedded values.yaml).

MockServer will then be available on domain name mockserver.mockserver.svc.cluster.local, as long as the namespace you are calling from isn't prevented (by network policy) to call the mockserver namespace.

Chart Deployment Status

To view the logs:

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

or open the UI

To wait until the deployment is complete run:

kubectl -n mockserver rollout status deployments mockserver

To check the status of the deployment without waiting, run the following command and confirm the mockserver has the Running status:

kubectl -n mockserver get po -l release=mockserver

To undeploy the helm chart:

helm delete -n mockserver mockserver

Basic MockServer Configuration

Modify the arguments used to start the docker container by setting values explicitly using --set, as follows:

helm upgrade --install --namespace mockserver --set app.serverPort=1080 --set app.logLevel=INFO mockserver http://www.mock-server.com/mockserver-5.15.0.tgz

The following values are supported:

app.serverPort (default: 1080)
app.logLevel (default: INFO)
app.proxyRemoteHost (no default)
app.proxyRemotePort (no default)
app.jvmOptions (no default)
image.snapshot (default: false) - set true to use latest snapshot version
podLabels (default: {}) - additional labels to add to the MockServer pods
imagePullSecrets (default: []) - list of image pull secrets for private registries

For example configure a proxyRemoteHost and proxyRemotePort, as follows:

helm upgrade --install --namespace mockserver --set app.serverPort=1080 --set app.proxyRemoteHost=www.mock-server.com --set app.proxyRemotePort=443 mockserver http://www.mock-server.com/mockserver-5.15.0.tgz

Double check the correct arguments have been passed to the pod, as follows:

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

Detailed MockServer Configuration

There are two ways to provide MockServer configuration (properties file, expectation initialization JSON, TLS certificates, etc.):

Inline configuration (recommended) — provide configuration directly in values.yaml
External ConfigMap — create a ConfigMap separately (manually, via CI, or using the example mockserver-config chart)

Both approaches mount configuration into the container at /config. See MockServer Configuration for details of all configuration options.

Option 1: Inline Configuration (single chart install)

Set app.config.enabled=true and provide configuration content directly in values. This creates a ConfigMap as part of the main chart — no separate chart or manual ConfigMap creation is needed.

Using --set-string (commas in JSON must be escaped as \,):

helm upgrade --install --namespace mockserver \
  --set app.config.enabled=true \
  --set app.config.properties="mockserver.initializationJsonPath=/config/initializerJson.json" \
  --set-string 'app.config.initializerJson=[{"httpRequest":{"path":"/example"}\,"httpResponse":{"body":"response"}}]' \
  mockserver helm/mockserver

Note: Helm's --set flag treats commas as key/value separators, which corrupts JSON values. Use --set-string with escaped commas (\,) for simple cases, or a values.yaml file (recommended) for anything non-trivial.

Or using a values.yaml file (recommended for complex configuration):

app:
  config:
    enabled: true
    properties: |
      mockserver.initializationJsonPath=/config/initializerJson.json
      mockserver.enableCORSForAPI=true
      mockserver.enableCORSForAllResponses=true
    initializerJson: |
      [
        {
          "httpRequest": { "path": "/example" },
          "httpResponse": { "body": "some response" }
        }
      ]

helm upgrade --install --namespace mockserver -f values.yaml mockserver helm/mockserver

When using inline configuration, pods are automatically restarted on helm upgrade whenever the configuration content changes. This ensures MockServer always runs with the latest configuration.

The following inline config values are supported:

app.config.enabled (default: false) - set true to create a ConfigMap from inline values
app.config.properties (default: "") - content of mockserver.properties
app.config.initializerJson (default: "") - content of initializerJson.json
app.config.extraFiles (default: {}) - map of additional filenames to content (e.g. TLS certificates)

Option 2: External ConfigMap

If a ConfigMap called mockserver-config (or a custom name) exists in the same namespace, it will be mounted into the MockServer container under the mountPath /config.

This ConfigMap can be used to configure MockServer by containing a mockserver.properties file and other related configuration files such as:

json expectation initialization, or
custom TLS CA, X.509 Certificate or Private Key

The mockserver.properties file should load these additional files from the directory /config which is the mountPath for the ConfigMap.

The mapping of the configuration ConfigMap can be configured as follows:

app.mountedConfigMapName (default: mockserver-config) - name of the configuration ConfigMap (in the same namespace) to mount
app.propertiesFileName (default: mockserver.properties) - name of the property file in the ConfigMap

For example:

helm upgrade --install --namespace mockserver --set app.mountedConfigMapName=other-mockserver-config --set app.propertiesFileName=other-mockserver.properties mockserver helm/mockserver

An example of a helm chart to create this ConfigMap is helm/mockserver-config

Extending MockServer Classpath

To use class callbacks or an expectation initializer class the classpath for MockServer must include the specified classes.

To support adding classes to the classpath if a configmap called mockserver-config exists in the same namespace any jar files contained in this configmap will be added into MockServer classpath.

The mapping of the libs configmap can be configured as follows:

app.mountedLibsConfigMapName (default: mockserver-config) - name of the libs configmap (in the same namespace) to mount

For example:

helm upgrade --install --namespace mockserver --set app.mountedLibsConfigMapName=mockserver-libs mockserver helm/mockserver

Persistent Storage

By default, MockServer holds expectations in memory only. On Kubernetes, this means expectations are lost when a pod restarts. To persist expectations across pod restarts, enable persistent storage. This creates (or references) a PersistentVolumeClaim and automatically configures MockServer to save and reload expectations from it.

Quick Start

The simplest way to enable persistence is with a single --set flag:

helm upgrade --install --namespace mockserver \
  --set app.persistence.enabled=true \
  mockserver helm/mockserver

This creates a 256Mi PersistentVolumeClaim using the cluster's default StorageClass, and automatically configures MockServer to persist expectations to it.

How It Works

When app.persistence.enabled=true, the chart:

Creates a PersistentVolumeClaim (unless app.persistence.existingClaimName is set)
Mounts the PVC into the container at /persistence (configurable via app.persistence.mountPath)
Sets the following environment variables to enable persistence automatically:
- MOCKSERVER_PERSIST_EXPECTATIONS=true
- MOCKSERVER_PERSISTED_EXPECTATIONS_PATH=/persistence/persistedExpectations.json
- MOCKSERVER_INITIALIZATION_JSON_PATH=/persistence/persistedExpectations.json

Important: These environment variables provide defaults. Any matching property in your mockserver.properties file takes precedence over environment variables. If you need custom paths or want to disable auto-initialization, set the equivalent properties in your properties file. See MockServer Configuration for the full property precedence rules.

Persistence Values

The following values control persistent storage:

app.persistence.enabled (default: false) — set true to enable persistent storage
app.persistence.existingClaimName (default: "") — name of an existing PVC to use; if empty, the chart creates one
app.persistence.storageClass (default: "") — StorageClass for the PVC; if empty, the cluster default is used
app.persistence.accessModes (default: [ReadWriteOnce]) — access modes for the PVC
app.persistence.size (default: 256Mi) — size of the PVC
app.persistence.mountPath (default: /persistence) — mount path inside the container
app.persistence.annotations (default: {}) — annotations for the PVC (only used when creating a new PVC)

Example: Chart-Managed PVC

Let the chart create and manage the PVC:

app:
  persistence:
    enabled: true
    storageClass: "gp3"
    size: 1Gi

helm upgrade --install --namespace mockserver -f values.yaml mockserver helm/mockserver

Example: Existing PVC

If you manage PVCs separately (e.g. via GitOps or Terraform), reference an existing PVC by name:

helm upgrade --install --namespace mockserver \
  --set app.persistence.enabled=true \
  --set app.persistence.existingClaimName=my-mockserver-data \
  mockserver helm/mockserver

Example: Clustering with Shared Storage

For clustered MockServer deployments, use a ReadWriteMany access mode with a shared filesystem such as NFS, AWS EFS, or Azure Files:

replicaCount: 3

app:
  persistence:
    enabled: true
    accessModes:
      - ReadWriteMany
    storageClass: "efs-sc"

See Persisting & Clustering Expectations for more details on how MockServer clustering works.

MockServer URL

Local Kubernetes Cluster (i.e. minikube, microk8s)

If the service type hasn't been modified the following will provide the MockServer URL from outside the cluster.

export NODE_PORT=$(kubectl get -n mockserver -o jsonpath="{.spec.ports[0].nodePort}" services mockserver)
export NODE_IP=$(kubectl get nodes -n mockserver -o jsonpath="{.items[0].status.addresses[0].address}")
export MOCKSERVER_HOST=$NODE_IP:$NODE_PORT
echo http://$MOCKSERVER_HOST

To test the installation the following curl command should return the ports MockServer is bound to:

curl -v -X PUT http://$MOCKSERVER_HOST/status

Docker for Desktop

Docker for Desktop automatically exposes LoadBalancer services.

On MacOS Docker for Desktop runs inside Hyperkit so the node IP address is not reachable, therefore the only way to call services is via the exposed LoadBalancer service added by Docker for Desktop.

To ensure that Docker for Desktop exposes MockServer update the service type to LoadBalancer using --set service.type=LoadBalancer and set the exposed port using --set service.port=1080, as follows:

helm upgrade --install --namespace mockserver --set service.type=LoadBalancer --set service.port=1080 mockserver http://www.mock-server.com/mockserver-5.15.0.tgz

MockServer will then be reachable on http://localhost:1080

For LoadBalancer services it is possible to query kubernetes to programmatically determine the MockServer base URL as follows:

export SERVICE_IP=$(kubectl get svc --namespace mockserver mockserver -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
export MOCKSERVER_HOST=$SERVICE_IP:1081
echo http://$MOCKSERVER_HOST

Outside Remote Kubernetes Cluster (i.e. Azure AKS, AWS EKS, etc) via Port Forward

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

Inside Kubernetes Cluster

If a DNS server has been installed in the Kubernetes cluster the following DNS name should be available mockserver.<namespace>.svc.cluster.local, i.e. mockserver.mockserver.svc.cluster.local

Helm Delete

To completely remove the chart:

helm delete mockserver --purge

Build & Run From Source

MockServer is written in Java and built using maven. The maven wrapper is used so maven does not need to be installed but Java JDK 11 or higher must be installed.

First clone the repository as follows:

git clone https://github.com/mock-server/mockserver-monorepo.git
cd mockserver-monorepo/mockserver

Next use maven to build an executable jar containing all dependencies as follows:

./mvnw clean package

This will produce an executable jar file under the target directory called, as follows:

mockserver-netty-no-dependencies/target/mockserver-netty-no-dependencies-5.15.0.jar

Run MockServer then using the executable jar as per the instruction above in Running From The Command Line