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
mockserver-client-node

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.14.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.14.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.14.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.14.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.14.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.14.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.14.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.14.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.14.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=log" -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.14.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
 ]
}'