mockserver-client weekly downloads statistics

mockserver-client-node

Communicate with a MockServer from any node or grunt build

Community

• Roadmap: • Feature Requests: • Issues / Bugs: • Discussions:

Getting Started

MockServer allows you to mock any system you integrate with via HTTP or HTTPS (i.e. (REST) services, web sites, etc). Please note that it is a third party project that needs java.

This npm module allows any grunt or node project to easily communicate with a running MockServer instance.

As an addition to this module for communicating with a running MockServer there is a second project that can be used to start and stop a MockServer called mockserver-node.

The MockServer client can be created as follows:

Note: this assumes you have an instance of MockServer running on port 1080. For more information on how to do so check mockserver-node.

The package includes TypeScript typings. It is a CommonJS module. From CommonJS, or TypeScript compiled to it, import { mockServerClient, llm } from 'mockserver-client' works with or without esModuleInterop. The LLM builders can also be imported on their own: import llm = require('mockserver-client/llm'), import * as llm from 'mockserver-client/llm', or by name, import { llmMock, completion } from 'mockserver-client/llm'; import llm from 'mockserver-client/llm' needs esModuleInterop. That module has no default property.

From an ES module (.mjs, .mts, or a package with "type": "module") named imports work too, import { mockServerClient, llm } from 'mockserver-client', as do import * as and the default import, import mockServer from 'mockserver-client'. A module other than the package itself can be imported with or without its extension: import { llmMock, completion } from 'mockserver-client/llm'.

The package's exports map names every path that can be imported or required: the package itself, each of its modules with and without .js (llm, setupMockServer, mockServerClient, mcpMockBuilder, a2aMockBuilder, index, sendRequest, webSocketClient), the types-only llmTypes and mockServer (for import type), and package.json. Any other path inside the package, such as a .d.ts file or a test file, fails with ERR_PACKAGE_PATH_NOT_EXPORTED. Each path with typings names them under a types condition, so TypeScript finds them under the node16, nodenext and bundler module resolutions.

Setup Expectation

A simple expectation can be set up as follows:

A more complex expectation can be set up like this:

For the full documentation see MockServer - Creating Expectations.

Fluent when().respond() API

The same expectation can also be built with a chainable API that mirrors the Java client's when(...) / ForwardChainExpectation:

To set the number of matches, time-to-live, priority or expectation id, use the chainable .withTimes() / .withTimeToLive() / .withPriority() / .withId() builders before the terminal action — this is the recommended style because it is unambiguous and order-independent:

⚠️ Positional argument order differs from the procedural methods. when(...) takes its optional arguments as when(request, times, timeToLive, priority) to match the Java client. This is not the order used by the Node procedural methods (mockSimpleResponse, respondWith*, etc.), which take (…, times, priority, timeToLive, id). In particular when(req, 2, 5) sets timeToLive = 5 (which expects an object, so it is ignored) and leaves the priority unset — it does not set the priority to 5. To avoid this footgun, prefer the .withTimes() / .withTimeToLive() / .withPriority() builders shown above rather than positional arguments.

If you do pass them positionally, the order is (request, times, timeToLive, priority):

The chain returned by when(...) exposes the builders withTimes, withTimeToLive, withPriority, withId and the terminal actions respond (httpResponse, a template, or a class-callback), forward (httpForward, a template, a class-callback, or an override-forwarded-request), error (httpError), callback (a local JS response callback over the callback WebSocket) and forwardCallback (a local JS forward callback). The action is auto-detected from the object shape: a plain object with a string template/templateType becomes a template action, one with a callbackClass becomes a server-side class-callback, otherwise it is the natural response/forward action. Each terminal method returns the same promise as the procedural builders, so it can be awaited or used with .then(...).

Advanced Response Builders

For non-HTTP and streaming protocols there are dedicated builders that take a path (or full request matcher) plus the response action object, with optional times, priority, timeToLive, and id arguments:

AI Agent Mock Builders (MCP & A2A)

Declarative builders generate the full set of expectations needed to mock an AI agent endpoint. client.mcpMock(path) mocks an MCP (Model Context Protocol) server, and client.a2aMock(path) mocks an A2A (Agent-to-Agent) agent. Both return a fluent builder; call .applyTo() to register the generated expectations, or .build() to obtain the raw expectation array. They are also exported as standalone factories (require('mockserver-client').a2aMock).

SRE Helpers (SLO verdicts & chaos experiments)

verifySLO(criteria) evaluates service-level objectives over the recorded SLI samples and resolves the verdict (PASS / INCONCLUSIVE); it rejects on a FAIL verdict, and on a disabled/invalid request (start MockServer with sloTrackingEnabled=true). startChaosExperiment(experiment) runs a scheduled multi-stage chaos experiment (only one experiment is active at a time).

Diagnose Matching…

Description from the npm listing.