JavaScript Client

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
yarn

npm install mockserver-client --save-dev

yarn add mockserver-client --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().

REST API

Client SDKs

Installation

Creating a client

Node.js

Browser

Connecting over TLS

Creating expectations

Simple shorthand

Limit how many times an expectation fires

Set expectation priority

Verifying requests

Verify by count

Verify a sequence

Retrieving recorded requests

Clearing and resetting state

Clear matching state

Reset all state

Starting MockServer from Node.js

Basic start and stop

With JVM options and version pin

Grunt plugin

​Installation

​Creating a client

​Node.js

​Browser

​Connecting over TLS

​Creating expectations

​Simple shorthand

​Limit how many times an expectation fires

​Set expectation priority

​Verifying requests

​Verify by count

​Verify a sequence

​Retrieving recorded requests

​Clearing and resetting state

​Clear matching state

​Reset all state

​Starting MockServer from Node.js

​Basic start and stop

​With JVM options and version pin

​Grunt plugin

Installation

Creating a client

Node.js

Browser

Connecting over TLS

Creating expectations

Simple shorthand

Limit how many times an expectation fires

Set expectation priority

Verifying requests

Verify by count

Verify a sequence

Retrieving recorded requests

Clearing and resetting state

Clear matching state

Reset all state

Starting MockServer from Node.js

Basic start and stop

With JVM options and version pin

Grunt plugin