MockServer Clients

MockServer can be controlled in the following ways:

REST API
Java
JavaScript (both browser API & Node.js module)

The following activities are supported:

creating expectations
verifying which requests have been received
clearing or resetting recorded request, expectations or logs (selectively)
Retrieving the following items:
- recorded requests
- recorded requests and responses
- active expectations
- recorded expectations
- logs
bind additional ports for MockServer to listen on

REST API

The REST API is documented using Open API 3

Java Client

The Java client has the following versions:

org.mockserver.client.MockServerClient - makes HTTP requests to a remote MockServer instance
org.mockserver.integration.ClientAndServer - starts a local MockServer instance and makes HTTP requests to it

JavaScript Client

The JavaScript client has the following version:

a browser based API file mockServerClient.js
a Node.js npm module mockserver-client

To include the browser based client in an HTML page as follows:

<script src="https://raw.githubusercontent.com/mock-server/mockserver-client-node/mockserver-5.10.0/mockServerClient.js"></script>

new MockServerClient("localhost", 1080)
    .when(
        request()
            .withMethod("GET")
            .withPath("/view/cart")
            .withCookies(
                cookie("session", "4930456C-C718-476F-971F-CB8E047AB349")
            )
            .withQueryStringParameters(
                param("cartId", "055CA455-1DF7-45BB-8535-4F83E7266092")
            )
    )
    .respond(
        response()
            .withBody("some_response_body")
    );

new ClientAndServer(1080)
    .when(
        request()
            .withMethod("GET")
            .withPath("/view/cart")
            .withCookies(
                cookie("session", "4930456C-C718-476F-971F-CB8E047AB349")
            )
            .withQueryStringParameters(
                param("cartId", "055CA455-1DF7-45BB-8535-4F83E7266092")
            )
    )
    .respond(
        response()
            .withBody("some_response_body")
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .mockAnyResponse({
    "httpRequest": {
      "method": "GET",
      "path": "/view/cart",
      "queryStringParameters": {
        "cartId": ["055CA455-1DF7-45BB-8535-4F83E7266092"]
      },
      "cookies": {
        "session": "4930456C-C718-476F-971F-CB8E047AB349"
      }
    },
    "httpResponse": {
      "body": "some_response_body"
    }
  })
  .then(
    function () {
      console.log("expectation created");
    },
    function (error) {
      console.log(error);
    }
  );

<script src="https://raw.githubusercontent.com/mock-server/mockserver-client-node/mockserver-5.10.0/mockServerClient.js"></script>
<script>
  mockServerClient("localhost", 1080)
    .mockAnyResponse({
      "httpRequest": {
        "method": "GET",
        "path": "/view/cart",
        "queryStringParameters": {
          "cartId": ["055CA455-1DF7-45BB-8535-4F83E7266092"]
        },
        "cookies": {
          "session": "4930456C-C718-476F-971F-CB8E047AB349"
        }
      },
      "httpResponse": {
        "body": "some_response_body"
      }
    })
    .then(
      function () {
        console.log("expectation created");
      },
      function (error) {
        console.log(error);
      }
    );
</script>

curl -v -X PUT "http://localhost:1080/mockserver/expectation" -d '{
  "httpRequest" : {
    "method" : "GET",
    "path" : "/view/cart",
    "queryStringParameters" : {
      "cartId" : [ "055CA455-1DF7-45BB-8535-4F83E7266092" ]
    },
    "cookies" : {
      "session" : "4930456C-C718-476F-971F-CB8E047AB349"
    }
  },
  "httpResponse" : {
    "body" : "some_response_body"
  }
}'

new MockServerClient("localhost", 1080)
    .withSecure(true)
    .when(
        request()
            .withMethod("GET")
            .withPath("/view/cart")
            .withCookies(
                cookie("session", "4930456C-C718-476F-971F-CB8E047AB349")
            )
            .withQueryStringParameters(
                param("cartId", "055CA455-1DF7-45BB-8535-4F83E7266092")
            )
    )
    .respond(
        response()
            .withBody("some_response_body")
    );

new ClientAndServer(1080)
    .withSecure(true)
    .when(
        request()
            .withMethod("GET")
            .withPath("/view/cart")
            .withCookies(
                cookie("session", "4930456C-C718-476F-971F-CB8E047AB349")
            )
            .withQueryStringParameters(
                param("cartId", "055CA455-1DF7-45BB-8535-4F83E7266092")
            )
    )
    .respond(
        response()
            .withBody("some_response_body")
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080, undefined, true)
  .mockAnyResponse({
    "httpRequest": {
      "method": "GET",
      "path": "/view/cart",
      "queryStringParameters": {
        "cartId": ["055CA455-1DF7-45BB-8535-4F83E7266092"]
      },
      "cookies": {
        "session": "4930456C-C718-476F-971F-CB8E047AB349"
      }
    },
    "httpResponse": {
      "body": "some_response_body"
    }
  })
  .then(
    function () {
      console.log("expectation created");
    },
    function (error) {
      console.log(error);
    }
  );

curl -v -k -X PUT "https://localhost:1080/mockserver/expectation" -d '{
  "httpRequest" : {
    "method" : "GET",
    "path" : "/view/cart",
    "queryStringParameters" : {
      "cartId" : [ "055CA455-1DF7-45BB-8535-4F83E7266092" ]
    },
    "cookies" : {
      "session" : "4930456C-C718-476F-971F-CB8E047AB349"
    }
  },
  "httpResponse" : {
    "body" : "some_response_body"
  }
}'

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

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

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

<script src="https://raw.githubusercontent.com/mock-server/mockserver-client-node/mockserver-5.10.0/mockServerClient.js"></script>
<script>
  mockServerClient("localhost", 1080)
    .verify(
      {
        'path': '/some/path'
      }, 2, false)
    .then(
      function () {
        console.log("request found exactly 2 times");
      },
      function (error) {
        console.log(error);
      }
    );
</script>

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

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

new ClientAndServer(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);
    }
  );

<script src="https://raw.githubusercontent.com/mock-server/mockserver-client-node/mockserver-5.10.0/mockServerClient.js"></script>
<script>
  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);
      }
    );
</script>

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

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

HttpRequest[] recordedRequests = new ClientAndServer(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);
    }
  );

<script src="https://raw.githubusercontent.com/mock-server/mockserver-client-node/mockserver-5.10.0/mockServerClient.js"></script>
<script>
  mockServerClient("localhost", 1080)
    .retrieveRecordedRequests({
      "path": "/some/path",
      "method": "POST"
    })
    .then(
      function (recordedRequests) {
        console.log(JSON.stringify(recordedRequests));
      },
      function (error) {
        console.log(error);
      }
    );
</script>

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

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

Expectation[] recordedExpectations = new ClientAndServer(1080)
    .retrieveRecordedExpectations(
        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);
    }
  );

<script src="https://raw.githubusercontent.com/mock-server/mockserver-client-node/mockserver-5.10.0/mockServerClient.js"></script>
<script>
  mockServerClient("localhost", 1080)
    .retrieveRecordedRequests({
      "path": "/some/path",
      "method": "POST"
    })
    .then(
      function (recordedRequests) {
        console.log(JSON.stringify(recordedRequests));
      },
      function (error) {
        console.log(error);
      }
    );
</script>

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

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

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

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .retrieveLogMessages({
    "path": "/some/path",
    "method": "POST"
  })
  .then(
    function (logMessages) {
      // logMessages is a String[]
      console.log(logMessages);
    },
    function (error) {
      console.log(error);
    }
  );

<script src="https://raw.githubusercontent.com/mock-server/mockserver-client-node/mockserver-5.10.0/mockServerClient.js"></script>
<script>
  mockServerClient("localhost", 1080)
    .retrieveLogMessages({
      "path": "/some/path",
      "method": "POST"
    })
    .then(
      function (logMessages) {
        // logMessages is a String[]
        console.log(logMessages);
      },
      function (error) {
        console.log(error);
      }
    );
</script>

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

new MockServerClient("localhost", 1080).clear(
    request()
        .withPath("/some/path")
        .withMethod("POST")
);

new ClientAndServer(1080).clear(
    request()
        .withPath("/some/path")
        .withMethod("POST")
);

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .clear({
    'path': '/some/path'
  })
  .then(
    function () {
      console.log("cleared state that matches request matcher");
    },
    function (error) {
      console.log(error);
    }
  );

<script src="https://raw.githubusercontent.com/mock-server/mockserver-client-node/mockserver-5.10.0/mockServerClient.js"></script>
<script>
  mockServerClient("localhost", 1080)
    .clear({
      'path': '/some/path'
    })
    .then(
      function () {
        console.log("cleared state that matches request matcher");
      },
      function (error) {
        console.log(error);
      }
    );
</script>

curl -v -X PUT "http://localhost:1080/mockserver/clear" -d '{
    "path": "/some/path"
}'

new MockServerClient("localhost", 1080).clear(
    request()
        .withPath("/some/path")
        .withMethod("POST"),
    ClearType.LOG
);

new ClientAndServer(1080).clear(
    request()
        .withPath("/some/path")
        .withMethod("POST"),
    ClearType.LOG
);

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .clear({
    'path': '/some/path'
  }, 'LOG')
  .then(
    function () {
      console.log("cleared state that matches request matcher");
    },
    function (error) {
      console.log(error);
    }
  );

<script src="https://raw.githubusercontent.com/mock-server/mockserver-client-node/mockserver-5.10.0/mockServerClient.js"></script>
<script>
  mockServerClient("localhost", 1080)
    .clear({
      'path': '/some/path'
    }, 'LOG')
    .then(
      function () {
        console.log("cleared state that matches request matcher");
      },
      function (error) {
        console.log(error);
      }
    );
</script>

curl -v -X PUT "http://localhost:1080/mockserver/clear?type=LOGS" -d '{
    "path": "/some/path"
}'

new MockServerClient("localhost", 1080).reset();

new ClientAndServer(1080).reset();

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .reset()
  .then(
    function () {
      console.log("reset all state");
    },
    function (error) {
      console.log(error);
    }
  );

<script src="https://raw.githubusercontent.com/mock-server/mockserver-client-node/mockserver-5.10.0/mockServerClient.js"></script>
<script>
  mockServerClient("localhost", 1080)
    .reset()
    .then(
      function () {
        console.log("reset all state");
      },
      function (error) {
        console.log(error);
      }
    );
</script>

curl -v -X PUT "http://localhost:1080/mockserver/reset

List<Integer> boundPorts = new MockServerClient("localhost", 1080).bind(
            0
        );

List<Integer> boundPorts = new ClientAndServer(1080).bind(
            0
        );

curl -v -X PUT "http://localhost:1080/mockserver/bind -d '{
    "ports": [
        0,
        0
    ]
}'

List<Integer> boundPorts = new MockServerClient("localhost", 1080).bind(
            1081, 1082
        );

List<Integer> boundPorts = new ClientAndServer(1080).bind(
            1081, 1082
        );

curl -v -X PUT "http://localhost:1080/mockserver/bind -d '{
    "ports": [
        1081,
        1082
    ]
}'