> ## Documentation Index
> Fetch the complete documentation index at: https://moeck.io/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript Client

> Control MockServer from Node.js or the browser using the mockserver-client package.

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

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install mockserver-client --save-dev
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add mockserver-client --dev
    ```
  </Tab>
</Tabs>

To also start MockServer from Node.js, install `mockserver-node`:

```bash theme={null}
npm install mockserver-node --save-dev
```

## Creating a client

### Node.js

```javascript theme={null}
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:

```html theme={null}
<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:

```javascript theme={null}
var client = mockServerClient("localhost", 1080, undefined, true);
```

## Creating expectations

Use `.mockAnyResponse(expectation)` to register an expectation. The method returns a Promise.

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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.

```javascript theme={null}
// 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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
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, "  ")); }
  );
```

<Note>
  MockServer requires Java to be installed and available on `PATH`. The
  `mockserver-node` package downloads the MockServer JAR automatically.
</Note>

## 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`:

```javascript theme={null}
grunt.initConfig({
    start_mockserver: {
        start: {
            options: {
                serverPort: 1080,
                trace: true
            }
        }
    },
    stop_mockserver: {
        stop: {
            options: {
                serverPort: 1080
            }
        }
    }
});

grunt.loadNpmTasks('mockserver-node');
```

<Tip>
  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()`.
</Tip>