Introduction to MockServer

1. Overview

MockServer is a tool for mocking/stubbing external HTTP APIs.

In this tutorial, we’ll learn how to set up a mock server and create expectations.

2. Maven Dependencies

To make use of MockServer in our application, let’s add the mockserver-netty-no-dependencies and mockserver-client-java-no-dependencies dependencies to the pom.xml:

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

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

These dependencies provide classes to create and start a MockServer. It also provides classes to create expectations. Expectations include the request path, bodies, and expected response.

3. MockServer Functionality

Simply put, the tool can:

• generate and return fixed responses
• forward a request to another server
• execute callbacks
• verify a request

4. How to Run MockServer

We can start the server in a few different ways – let’s explore some of these methods.

4.1. Launching via Maven Plugin

This will launch the server during the process-test-class phase and stop at the verify phase:

<plugin>
    <groupId>org.mock-server</groupId>
    <artifactId>mockserver-maven-plugin</artifactId>
    <version>3.10.8</version>
    <configuration>
        <serverPort>1080</serverPort>
        <proxyPort>1090</proxyPort>
        <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>

4.2. Launching via Java API

We can use the startClientAndServer() Java API to start the server. Typically, we would start a server before running all tests:

public class TestMockServer {

    private ClientAndServer mockServer;

    @BeforeClass
    public void startServer() {
        mockServer = startClientAndServer(1080);
    }
 
    @AfterClass 
    public void stopServer() { 
        mockServer.stop();
    }
 
    // ...
}

5. Mock Clients

MockServerClient API provides the capability to connect to the MockServer. It models requests and the corresponding responses from the server.

It supports multiple operations:

5.1. Creating Expectations With Mock Responses

Expectations are a mechanism by which we mock the request from a client and the resulting response from MockServer.

To create an expectation, we need to define a request matcher and the expected response.

Requests can be matched using:

• path – URL path
• query string – URL parameters
• headers – request headers
• cookies – client-side cookies
• body – POST request body with XPATH, JSON, JSON schema, regular expression, exact matching plain text or body parameters

All the above parameters can be specified using plain text or regular expressions.

A response contains:

• status codes – valid HTTP status codes e.g. 200, 400, etc.
• body – it is the sequence of bytes containing any content
• headers – response headers with name and one or more values
• cookies – response cookies with name and one or more values

Let’s see how we can create an expectation:

private void createExpectationForInvalidAuth() {
    new MockServerClient("127.0.0.1", 1080)
      .when(
        request()
          .withMethod("POST")
          .withPath("/validate")
          .withHeader("Content-type", "application/json")
          .withBody(json("{\"username\": \"foo\", \"password\": \"bar\"}")), exactly(1))
      .respond(
        response()
          .withStatusCode(401)
          .withHeaders(
            new Header("Content-Type", "application/json; charset=utf-8"),
            new Header("Cache-Control", "public, max-age=86400"))
          .withBody("{ message: 'incorrect username and password combination' }")
          .withDelay(TimeUnit.SECONDS, 1));
}

Here, we are stubbing a POST request to the server. We specify how often we need to make this request using exactly(1) call.

On receiving this request, we mocked a response with fields like status code, headers, and response body.

5.2. Forwarding a Request

An expectation can be set up to forward the request. A few parameters can describe the forward action:

• host – the host to forward to e.g. www.baeldung.com
• port – the port where the request is to be forwarded, the default port is 80
• scheme – protocol to use e.g. HTTP or HTTPS

Let’s see an example of a forwarding request:

private void createExpectationForForward(){
    new MockServerClient("127.0.0.1", 1080)
      .when(
        request()
          .withMethod("GET")
          .withPath("/index.html"),
          exactly(1))
      .forward(
        forward()
          .withHost("www.mock-server.com")
          .withPort(80)
          .withScheme(HttpForward.Scheme.HTTP)
      );
}

In the code above, we have mocked a request that hit the MockServer exactly once and then forwarded it to another server. The outer forward() method specifies the forward action and the inner forward() method call helps construct the URL and forwards the request.

5.3. Executing a Callback

The server can be set to execute a callback when receiving a particular request. Callback action can define a callback class that implements org.mockserver.mock.action.ExpectationCallback interface. It should have the default constructor and should be on the classpath.

Let’s see an example of expectation with a callback:

private void createExpectationForCallBack() {
    mockServer
      .when(
        request().withPath("/callback"))
      .respond(
        callback()
          .withCallbackClass("com.baeldung.mock.server.ExpectationCallbackHandler"));
}

Here the outer callback() specifies the callback action and the inner callback() method specifies the instance of the callback method class.

In this case, when MockServer receives a request with /callback, then the callback handle method implemented in the class specified will be executed:

public class TestExpectationCallback implements ExpectationCallback {

    public HttpResponse handle(HttpRequest httpRequest) {
        if (httpRequest.getPath().getValue().endsWith("/callback")) {
            return httpResponse;
        } else {
            return notFoundResponse();
        }
    }

    public static HttpResponse httpResponse = response()
      .withStatusCode(200);
}

5.4. Verifying Requests

MockServerClient has the ability to check if the system under test sent a request:

private void verifyPostRequest() {
     new MockServerClient("localhost", 1080)
      .verify(
        request()
          .withMethod("POST")
          .withPath("/validate")
          .withBody(json("{\"username\": \"foo\", \"password\": \"bar\"}")), VerificationTimes.exactly(1)
    );
}

Here, the org.mockserver.verify.VerificationTimes class is used to specify the number of times the Mock Server should match the request.

6. Conclusion

In this quick article, we have explored different functions of the MockServer. We have also explored the different APIs provided and how it can be used for testing complex systems.