Skip to main content
The JavaScript client works in both Node.js and the browser. It communicates with a running MockServer instance over HTTP and returns Promises for every operation.

​
Installation

npm install mockserver-client --save-dev
To also start MockServer from Node.js, install mockserver-node: 
npm install mockserver-node --save-dev

​
Creating a client

​
Node.js

var mockServerClient = require('mockserver-client').mockServerClient;

var client = mockServerClient("localhost", 1080);

​
Browser

Include the browser bundle directly in your HTML, then call mockServerClient as a global: 
<script src="https://raw.githubusercontent.com/mock-server/mockserver-client-node/mockserver-5.15.0/mockServerClient.js"></script>
<script>
  var client = mockServerClient("localhost", 1080);
</script>

​
Connecting over TLS

Pass true as the fourth argument to enable HTTPS: 
var client = mockServerClient("localhost", 1080, undefined, true);

​
Creating expectations

Use .mockAnyResponse(expectation) to register an expectation. The method returns a Promise. 
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);
    }
  );

​
Simple shorthand

Use .mockSimpleResponse(path, responseBody, statusCode) for a quick GET-only mock: 
mockServerClient("localhost", 1080)
  .mockSimpleResponse('/some/path', { message: 'ok' }, 200)
  .then(
    function () {
      console.log("expectation created");
    },
    function (error) {
      console.log(error);
    }
  );

​
Limit how many times an expectation fires

Include a times object to cap the number of matches: 
mockServerClient("localhost", 1080)
  .mockAnyResponse({
    "httpRequest": {
      "path": "/some/path"
    },
    "httpResponse": {
      "body": "some_response_body"
    },
    "times": {
      "remainingTimes": 2
    },
    "timeToLive": {
      "unlimited": true
    }
  })
  .then(
    function () { console.log("expectation created"); },
    function (error) { console.log(error); }
  );

​
Set expectation priority

Use a priority field to control which expectations match first. Higher values match first; negative values act as catch-all defaults: 
mockServerClient("localhost", 1080)
  .mockAnyResponse({
    "httpRequest": {
      "path": "/some/path"
    },
    "httpResponse": {
      "body": "some_response_body"
    },
    "times": {
      "remainingTimes": 1,
      "unlimited": false
    },
    "timeToLive": {
      "timeUnit": "SECONDS",
      "timeToLive": 60,
      "unlimited": false
    },
    "priority": 10
  })
  .then(
    function () { console.log("expectation created"); },
    function (error) { console.log(error); }
  );

​
Verifying requests

​
Verify by count

.verify(requestMatcher, atLeast, atMost) checks how many times a request was received. 
// Received at least 2 times
mockServerClient("localhost", 1080)
  .verify({ 'path': '/some/path' }, 2)
  .then(
    function () { console.log("request found at least 2 times"); },
    function (error) { console.log(error); }
  );

// Received exactly 2 times
mockServerClient("localhost", 1080)
  .verify({ 'path': '/some/path' }, 2, 2)
  .then(
    function () { console.log("request found exactly 2 times"); },
    function (error) { console.log(error); }
  );

// Received at most 2 times
mockServerClient("localhost", 1080)
  .verify({ 'path': '/some/path' }, 0, 2)
  .then(
    function () { console.log("request found at most 2 times"); },
    function (error) { console.log(error); }
  );

// Never received
mockServerClient("localhost", 1080)
  .verify({ 'path': '/some/path' }, 0, true)
  .then(
    function () { console.log("request found zero times"); },
    function (error) { console.log(error); }
  );

​
Verify a sequence

Use .verifySequence() to assert that a set of requests was received in a specific order: 
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);
    }
  );

​
Retrieving recorded requests

Retrieve all recorded requests that match a filter: 
mockServerClient("localhost", 1080)
  .retrieveRecordedRequests({
    "path": "/some/path",
    "method": "POST"
  })
  .then(
    function (recordedRequests) {
      console.log(JSON.stringify(recordedRequests));
    },
    function (error) {
      console.log(error);
    }
  );
Retrieve recorded request-response pairs: 
mockServerClient("localhost", 1080)
  .retrieveRecordedRequestsAndResponses({
    "path": "/some/path",
    "method": "POST"
  })
  .then(
    function (recordedRequestsAndResponses) {
      console.log(JSON.stringify(recordedRequestsAndResponses));
    },
    function (error) {
      console.log(error);
    }
  );
Retrieve log messages: 
mockServerClient("localhost", 1080)
  .retrieveLogMessages({
    "path": "/some/path",
    "method": "POST"
  })
  .then(
    function (logMessages) {
      // logMessages is a String[]
      console.log(logMessages);
    },
    function (error) {
      console.log(error);
    }
  );

​
Clearing and resetting state

​
Clear matching state

Remove expectations and recorded requests that match a pattern: 
mockServerClient("localhost", 1080)
  .clear({ 'path': '/some/path' })
  .then(
    function () { console.log("cleared state that matches request matcher"); },
    function (error) { console.log(error); }
  );
Clear only the log, leaving expectations active: 
mockServerClient("localhost", 1080)
  .clear({ 'path': '/some/path' }, 'LOG')
  .then(
    function () { console.log("cleared log that matches request matcher"); },
    function (error) { console.log(error); }
  );

​
Reset all state

Remove all expectations and the request log: 
mockServerClient("localhost", 1080)
  .reset()
  .then(
    function () { console.log("reset all state"); },
    function (error) { console.log(error); }
  );

​
Starting MockServer from Node.js

Use the mockserver-node package to start and stop MockServer programmatically, without a separate process.

​
Basic start and stop

var mockserver = require('mockserver-node');

mockserver.start_mockserver({
    serverPort: 1080,
    verbose: true
});

// ... run tests ...

mockserver.stop_mockserver({ serverPort: 1080 });

​
With JVM options and version pin

var mockserver = require('mockserver-node');

mockserver
  .start_mockserver({
    serverPort: 1080,
    jvmOptions: [
      '-Dmockserver.enableCORSForAllResponses=true',
      '-Dmockserver.corsAllowMethods="CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE"',
      '-Dmockserver.corsAllowHeaders="Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization"',
      '-Dmockserver.corsAllowCredentials=true',
      '-Dmockserver.corsMaxAgeInSeconds=300'
    ],
    mockServerVersion: "5.15.0",
    verbose: true
  })
  .then(
    function () { console.log("started MockServer"); },
    function (error) { console.log(JSON.stringify(error, null, "  ")); }
  );
MockServer requires Java to be installed and available on PATH. The mockserver-node package downloads the MockServer JAR automatically.

​
Grunt plugin

If your project uses Grunt, mockserver-node doubles as a Grunt plugin. Add start_mockserver and stop_mockserver tasks to your Gruntfile.js: 
grunt.initConfig({
    start_mockserver: {
        start: {
            options: {
                serverPort: 1080,
                trace: true
            }
        }
    },
    stop_mockserver: {
        stop: {
            options: {
                serverPort: 1080
            }
        }
    }
});

grunt.loadNpmTasks('mockserver-node');
Set trace: true (or pass --verbose on the CLI) to enable INFO-level logging. MockServer only records requests in its log at INFO level or above, so this setting is required if you plan to use the /retrieve endpoint or call .retrieveRecordedRequests().