Getting Started

To use MockServer to analysis an existing system:

Start MockServer
Configure Clients
Run Scenarios
Analyse Behaviour

To use MockServer to verify requests:

Start MockServer
Configure Clients
Run Your Test Scenarios
Verify Requests

0. Start MockServer

MockServer is flexible and support numerous usage patterns.

MockServer can be run:

via a Maven Plugin as part of a Maven build cycle
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
from the command line as a stand-alone process in a test environment
as a deployable WAR to an existing application server
as a Node.js (npm) module from any Node.js code
as a Grunt plugin as part of a Grunt build cycle
as a Docker container in any Docker enabled environment
via a Helm chart in any Kubernetes environment

MockServer is available as:

a stand alone Netty web server that is fully self contained
a deployable WAR that runs on any JEE web server
a maven plugin
an npm plugin
a Grunt plugin
a fully encapsulated Docker container
a Helm chart
a Homebrew package

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

To simplify configuration all MockServer versions (except the deployable WAR) only use a single port to support HTTP, HTTPS and SOCKS. This is achieved by dynamically detecting if the client is using HTTP, HTTPS or SOCKS.

1. Configure Clients

The page on configuring clients gives full details on how to configure clients to proxy requests via MockServer and includes code examples for the following clients:

3. Analysing Behaviour

To analyse the requests that a system makes the proxy can be used to record all requests and their corresponding responses.

All requests and responses can be retrieved as expectations (called recorded expectations) in Java code or JSON. This allows an easy way to replay a recording from the proxy.

Unlike conventional record-replay approaches typically provided by other proxies, MockServer allows easy editing of the recorded requests because the recording is provided as Java code or JSON. This ensures that if minor changes are made to an API the recording can easily be modified and no re-recording required avoiding the need to update test assertions.

Retrieving Recorded Expectations

All proxied requests including those proxied using a forward actions are recorded containing the request received and response returned.

It is possible to retrieve the recorded requests and responses as expectations so that they can be easily used as expectations to simulation a system.

Expectations are returned in the order they have been recorded. The expectations are returned can be filter using a request matcher.

Expectation[] recordedExpectations = new MockServerClient("localhost", 1080)
    .retrieveRecordedExpectations(
        request()
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
    .retrieveRecordedExpectations({})
    .then(
        function (recordedExpectations) {
            console.log(JSON.stringify(recordedExpectations));
        },
        function (error) {
            console.log(error);
        }
    );

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS"

See REST API for full JSON specification

Expectation[] recordedExpectations = new MockServerClient("localhost", 1080)
    .retrieveRecordedExpectations(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).retrieveRecordedExpectations({
    "path": "/some/path",
    "method": "POST"
}).then(
    function (recordedExpectations) {
        console.log(JSON.stringify(recordedExpectations));
    },
    function (error) {
        console.log(error);
    }
);

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS" -d '{
    "path": "/some/path",
    "method": "POST"
}'

See REST API for full JSON specification

String recordedExpectations = new MockServerClient("localhost", 1080)
    .retrieveRecordedExpectations(
        request()
            .withPath("/some/path")
            .withMethod("POST"),
        Format.JAVA
    );

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS&format=JAVA" -d '{
    "path": "/some/path"
}'

See REST API for full JSON specification

String recordedExpectations = new MockServerClient("localhost", 1080)
    .retrieveRecordedExpectations(
        request()
            .withPath("/some/path")
            .withMethod("POST"),
        Format.JSON
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).retrieveRecordedExpectations({
    "path": "/some/path",
    "method": "POST"
}).then(
    function (recordedExpectations) {
        console.log(JSON.stringify(recordedExpectations));
    },
    function (error) {
        console.log(error);
    }
);

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS&format=JSON" -d '{
    "path": "/some/path"
}'

See REST API for full JSON specification

Retrieving Recorded Requests

All requests the MockServer receives are recorded, including both proxied requests and requests that have matched an expectation.

It is possible to retrieve the recorded requests, as show below in the code examples.

Requests are returned in the order they have been recorded. Which requests are returned can be filter using a request matcher.

HttpRequest[] recordedRequests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
    .retrieveRecordedRequests({})
    .then(
        function (recordedRequests) {
            console.log(JSON.stringify(recordedRequests));
        },
        function (error) {
            console.log(error);
        }
    );

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS"

See REST API for full JSON specification

HttpRequest[] recordedRequests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).retrieveRecordedRequests({
    "path": "/some/path",
    "method": "POST"
}).then(
    function (recordedRequests) {
        console.log(JSON.stringify(recordedRequests));
    },
    function (error) {
        console.log(error);
    }
);

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS" -d '{
    "path": "/some/path",
    "method": "POST"
}'

See REST API for full JSON specification

String recordedRequests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
            .withPath("/some/path")
            .withMethod("POST"),
        Format.JAVA
    );

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS&format=JAVA" -d '{
    "path": "/some/path"
}'

See REST API for full JSON specification

String recordedRequests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
            .withPath("/some/path")
            .withMethod("POST"),
        Format.JSON
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).retrieveRecordedRequests({
    "path": "/some/path",
    "method": "POST"
}).then(
    function (recordedRequests) {
        console.log(JSON.stringify(recordedRequests));
    },
    function (error) {
        console.log(error);
    }
);

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS&format=JSON" -d '{
    "path": "/some/path"
}'

See REST API for full JSON specification

Retrieve Recorded Requests & Responses

All requests the MockServer receives are recorded, including both proxied requests and requests that have matched an expectation.

It is possible to retrieve the recorded requests and their responses, as show below in the code examples.

Requests and responses are returned in the order they have been recorded. Which requests are returned can be filter using a request matcher.

HttpRequestAndHttpResponse[] httpRequestAndHttpResponse = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequestsAndResponses(
        request()
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
    .retrieveRecordedRequestsAndResponses({})
    .then(
        function (recordedRequestsAndResponses) {
            console.log(JSON.stringify(recordedRequestsAndResponses));
        },
        function (error) {
            console.log(error);
        }
    );

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUEST_RESPONSES"

See REST API for full JSON specification

HttpRequestAndHttpResponse[] httpRequestAndHttpResponse = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequestsAndResponses(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).retrieveRecordedRequestsAndResponses({
    "path": "/some/path",
    "method": "POST"
}).then(
    function (recordedRequestsAndResponses) {
        console.log(JSON.stringify(recordedRequestsAndResponses));
    },
    function (error) {
        console.log(error);
    }
);

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUEST_RESPONSES" -d '{
    "path": "/some/path",
    "method": "POST"
}'

See REST API for full JSON specification

3. Verify Requests

MockServer supports verification of requests is has received, including both proxied requests and requests that have matched an expectation.

Verification can be specified as follows:

a request matcher and a condition indicating the number of times the request should be matched
a sequence of request matchers that is matched in order

Verifying Repeating Requests

Verify that a request has been received by MockServer a specific number of times using a Verification

new MockServerClient("localhost", 1080)
    .verify(
        request()
            .withPath("/some/path"),
        VerificationTimes.atLeast(2)
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .verify(
    {
      'path': '/some/path'
    }, 2)
  .then(
    function () {
      console.log("request found exactly 2 times");
    },
    function (error) {
      console.log(error);
    }
  );

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/verify" -d '{
    "httpRequest": {
        "path": "/simple"
    },
    "times": {
        "atLeast": 2
    }
}'

See REST API for full JSON specification

new MockServerClient("localhost", 1080)
.verify(
    request()
        .withPath("/some/path"),
    VerificationTimes.atMost(2)
);

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
.verify(
{
  'path': '/some/path'
}, 0, 2)
.then(
function () {
  console.log("request found exactly 2 times");
},
function (error) {
  console.log(error);
}
);

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/verify" -d '{
"httpRequest": {
    "path": "/simple"
},
"times": {
    "atMost": 2
}
}'

See REST API for full JSON specification

new MockServerClient("localhost", 1080)
    .verify(
        request()
            .withPath("/some/path"),
        VerificationTimes.exactly(2)
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .verify(
    {
      'path': '/some/path'
    }, 2, 2)
  .then(
    function () {
      console.log("request found exactly 1 times");
    },
    function (error) {
      console.log(error);
    }
  );

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/verify" -d '{
    "httpRequest": {
        "path": "/simple"
    },
    "times": {
        "atLeast": 2,
        "atMost": 2
    }
}'

See REST API for full JSON specification

new MockServerClient("localhost", 1080)
    .verify(
        request()
            .withPath("/some/path"),
        VerificationTimes.exactly(0)
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .verify(
    {
      'path': '/some/path'
    }, 0, true)
  .then(
    function () {
      console.log("request found zero times");
    },
    function (error) {
      console.log(error);
    }
  );

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/verify" -d '{
    "httpRequest": {
        "path": "/simple"
    },
    "times": {
        "atMost": 0
    }
}'

See REST API for full JSON specification

Verifying Request Sequences

Verify that a sequence of requests has been received by MockServer in the specified order using a VerificationSequence

The each request in the sequence will be verified to have been received at least once, in the exact order specified.

new MockServerClient("localhost", 1080)
    .verify(
        request()
            .withPath("/some/path/one"),
        request()
            .withPath("/some/path/two"),
        request()
            .withPath("/some/path/three")
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .verifySequence(
    {
      'path': '/some/path/one'
    },
    {
      'path': '/some/path/two'
    },
    {
      'path': '/some/path/three'
    }
  )
  .then(
    function () {
      console.log("request sequence found in the order specified");
    },
    function (error) {
      console.log(error);
    }
  );

See REST API for full JSON specification

curl -v -X PUT "http://localhost:1080/mockserver/verifySequence" -d '{
   "httpRequests":[
      {
         "path":"/some/path/one"
      },
      {
         "path":"/some/path/two"
      },
      {
         "path":"/some/path/three"
      }
   ]
}'

See REST API for full JSON specification