Response Actions

When a request matches an expectation, MockServer executes the expectation’s action. There are four action types:

Response

Return a fixed or templated HTTP response.

Forward

Proxy the request to another server, optionally modifying it.

Callback

Invoke a Java class or closure to generate the response dynamically.

Error

Return invalid bytes or drop the connection to simulate network failures.

Response

A response action returns an HTTP response you define. You can set the status code, reason phrase, headers, cookies, body, and delay.

Status code and reason phrase

new MockServerClient("localhost", 1080)
    .when(
        request()
            .withMethod("POST")
            .withPath("/some/path")
    )
    .respond(
        response()
            .withStatusCode(418)
            .withReasonPhrase("I'm a teapot")
    );

curl -v -X PUT "http://localhost:1080/mockserver/expectation" -d '{
    "httpRequest": {
        "method": "POST",
        "path": "/some/path"
    },
    "httpResponse": {
        "statusCode": 418,
        "reasonPhrase": "I'\''m a teapot"
    }
}'

Headers, cookies, and body

new MockServerClient("localhost", 1080)
    .when(request())
    .respond(
        response()
            .withBody("some_response_body")
            .withHeader("Content-Type", "plain/text")
            .withCookie("Session", "97d43b1e-fe03-4855-926a-f448eddac32f")
    );

curl -v -X PUT http://localhost:1080/mockserver/expectation -d '{
    "httpResponse": {
        "headers": {
            "Content-Type": ["plain/text"]
        },
        "cookies": {
            "Session": "97d43b1e-fe03-4855-926a-f448eddac32f"
        },
        "body": "some_response_body"
    }
}'

Delay

new MockServerClient("localhost", 1080)
    .when(
        request().withPath("/some/path")
    )
    .respond(
        response()
            .withBody("some_response_body")
            .withDelay(TimeUnit.SECONDS, 10)
    );

curl -v -X PUT "http://localhost:1080/mockserver/expectation" -d '{
    "httpRequest": { "path": "/some/path" },
    "httpResponse": {
        "body": "some_response_body",
        "delay": {
            "timeUnit": "SECONDS",
            "value": 10
        }
    }
}'

Connection options

Use connectionOptions to suppress or override automatically-added headers, or to close the socket:

response()
    .withBody("some_response_body")
    .withConnectionOptions(
        connectionOptions()
            .withSuppressConnectionHeader(true)
            .withSuppressContentLengthHeader(true)
    )

"httpResponse": {
    "body": "some_response_body",
    "connectionOptions": {
        "suppressContentLengthHeader": true,
        "suppressConnectionHeader": true
    }
}

Close the connection after sending the response:

"connectionOptions": { "closeSocket": true }

Close the connection after a delay:

"connectionOptions": {
    "closeSocket": true,
    "closeSocketDelay": { "timeUnit": "MILLISECONDS", "value": 500 }
}

Respond differently for the same request

Register multiple expectations with the same matcher and different times values. MockServer fires them in registration order:

# respond once with 200, then twice with 204
curl -v -X PUT "http://localhost:1080/mockserver/expectation" -d '{
    "httpRequest": { "path": "/some/path" },
    "httpResponse": { "statusCode": 200 },
    "times": { "remainingTimes": 1, "unlimited": false }
}'

curl -v -X PUT "http://localhost:1080/mockserver/expectation" -d '{
    "httpRequest": { "path": "/some/path" },
    "httpResponse": { "statusCode": 204 },
    "times": { "remainingTimes": 2, "unlimited": false }
}'

Response templates

You can use Mustache, Velocity, or JavaScript templates to generate responses dynamically from the incoming request. See Response Templates.

new MockServerClient("localhost", 1080)
    .when(request().withPath("/some/path"))
    .respond(
        template(
            HttpTemplate.TemplateType.JAVASCRIPT,
            "return {\n" +
            "    'statusCode': 200,\n" +
            "    'cookies': { 'session': request.headers['Session-Id'][0] },\n" +
            "    'headers': { 'Date': [ Date() ] },\n" +
            "    'body': JSON.stringify({ method: request.method, path: request.path })\n" +
            "};"
        )
    );

curl -v -X PUT "http://localhost:1080/mockserver/expectation" -d '{
    "httpRequest": { "path": "/some/path" },
    "httpResponseTemplate": {
        "template": "return { statusCode: 200, cookies: { session: request.headers[\"Session-Id\"] && request.headers[\"Session-Id\"][0] }, headers: { Date: [ Date() ] }, body: JSON.stringify({method: request.method, path: request.path}) };",
        "templateType": "JAVASCRIPT"
    }
}'

Forward

A forward action proxies the incoming request to another server.

Forward exact request

new MockServerClient("localhost", 1080)
    .when(
        request().withPath("/some/path")
    )
    .forward(
        forward()
            .withHost("mock-server.com")
            .withPort(80)
    );

curl -v -X PUT "http://localhost:1080/mockserver/expectation" -d '{
    "httpRequest": { "path": "/some/path" },
    "httpForward": {
        "host": "mock-server.com",
        "port": 80,
        "scheme": "HTTP"
    }
}'

Use "scheme": "HTTPS" to forward over TLS:

"httpForward": {
    "host": "mock-server.com",
    "port": 443,
    "scheme": "HTTPS"
}

Override the forwarded request

Replace specific fields of the request before forwarding:

new MockServerClient("localhost", 1080)
    .when(
        request().withPath("/some/path")
    )
    .forward(
        forwardOverriddenRequest(
            request()
                .withPath("/some/other/path")
                .withHeader("Host", "target.host.com")
        )
    );

curl -v -X PUT "http://localhost:1080/mockserver/expectation" -d '{
    "httpRequest": { "path": "/some/path" },
    "httpOverrideForwardedRequest": {
        "httpRequest": {
            "path": "/some/other/path",
            "headers": { "Host": ["target.host.com"] }
        }
    }
}'

Override both request and response

You can override the forwarded request and also replace the response body returned to the caller:

"httpOverrideForwardedRequest": {
    "httpRequest": {
        "path": "/some/other/path",
        "headers": { "Host": ["target.host.com"] }
    },
    "httpResponse": {
        "body": "some_overridden_body"
    }
}

Add delay to a forward

"httpOverrideForwardedRequest": {
    "httpRequest": { "path": "/some/other/path" },
    "delay": { "timeUnit": "SECONDS", "value": 10 }
}

Callback

A callback action dynamically generates the response (or the forwarded request) by invoking code you provide. There are two variants: a class callback (server-side, Java only) and a method/closure callback (client-side, via WebSocket).

Class callback

Implement ExpectationResponseCallback and register it by class name. The class must be on MockServer’s classpath and have a zero-argument constructor.

public class TestExpectationResponseCallback implements ExpectationResponseCallback {

    @Override
    public HttpResponse handle(HttpRequest httpRequest) {
        if (httpRequest.getPath().getValue().endsWith("/path")) {
            return response()
                .withStatusCode(202)
                .withBody("a_callback_response");
        } else {
            return notFoundResponse();
        }
    }
}

new ClientAndServer(1080)
    .when(
        request().withPath("/some.*")
    )
    .respond(
        callback()
            .withCallbackClass(TestExpectationResponseCallback.class)
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).mockAnyResponse({
    "httpRequest": { "path": "/some.*" },
    "httpResponseClassCallback": {
        "callbackClass": "org.mockserver.examples.mockserver.CallbackActionExamples$TestExpectationResponseCallback"
    }
});

curl -v -X PUT "http://localhost:1080/mockserver/expectation" -d '{
    "httpRequest": { "path": "/some.*" },
    "httpResponseClassCallback": {
        "callbackClass": "org.mockserver.examples.mockserver.CallbackActionExamples$TestExpectationResponseCallback"
    }
}'

When using the Maven plugin with forked goals, add callback classes as plugin dependencies so MockServer can load them from the classpath.

Error

An error action simulates network-level failures by sending invalid bytes or dropping the TCP connection.

Drop the connection

new MockServerClient("localhost", 1080)
    .when(
        request().withPath("/some/path")
    )
    .error(
        error()
            .withDropConnection(true)
    );

curl -v -X PUT "http://localhost:1080/mockserver/expectation" -d '{
    "httpRequest": { "path": "/some/path" },
    "httpError": { "dropConnection": true }
}'

Send random bytes then drop

byte[] randomByteArray = new byte[25];
new Random().nextBytes(randomByteArray);

new MockServerClient("localhost", 1080)
    .when(
        request().withPath("/some/path")
    )
    .error(
        error()
            .withDropConnection(true)
            .withResponseBytes(randomByteArray)
    );

curl -v -X PUT "http://localhost:1080/mockserver/expectation" -d '{
    "httpRequest": { "path": "/some/path" },
    "httpError": {
        "dropConnection": true,
        "responseBytes": "eQqmdjEEoaXnCvcK6lOAIZeU+Pn+womxmg=="
    }
}'

responseBytes is a base64-encoded byte array.

Get Started

Mocking

Proxying

Configuration

Debugging

Response

Forward

Callback

Error

Response

Status code and reason phrase

Headers, cookies, and body

Delay

Connection options

Respond differently for the same request

Response templates

Forward

Forward exact request

Override the forwarded request

Override both request and response

Add delay to a forward

Callback

Class callback

Error

Drop the connection

Send random bytes then drop

Response

Forward

Callback

Error

​Response

​Status code and reason phrase

​Headers, cookies, and body

​Delay

​Connection options

​Respond differently for the same request

​Response templates

​Forward

​Forward exact request

​Override the forwarded request

​Override both request and response

​Add delay to a forward

​Callback

​Class callback

​Error

​Drop the connection

​Send random bytes then drop

Response

Status code and reason phrase

Headers, cookies, and body

Delay

Connection options

Respond differently for the same request

Response templates

Forward

Forward exact request

Override the forwarded request

Override both request and response

Add delay to a forward

Callback

Class callback

Error

Drop the connection

Send random bytes then drop