Communicate with a MockServer from any node or grunt build
- Roadmap:
- Feature Requests:
- Issues / Bugs:
- Discussions:
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:
var mockServer = require('mockserver-client'),
mockServerClient = mockServer.mockServerClient // MockServer and proxy clientNote: this assumes you have an instance of MockServer running on port 1080. For more information on how to do so check mockserver-node.
A simple expectation can be set up as follows:
mockServerClient("localhost", 1080)
.mockSimpleResponse('/somePath', { name: 'value' }, 203)
.then(
function(result) {
// do something next
},
function(error) {
// handle error
}
);A more complex expectation can be set up like this:
mockServerClient("localhost", 1080)
.mockAnyResponse(
{
'httpRequest': {
'method': 'POST',
'path': '/somePath',
'queryStringParameters': [
{
'name': 'test',
'values': [ 'true' ]
}
],
'body': {
'type': "STRING",
'value': 'someBody'
}
},
'httpResponse': {
'statusCode': 200,
'body': JSON.stringify({ name: 'value' }),
'delay': {
'timeUnit': 'MILLISECONDS',
'value': 250
}
},
'times': {
'remainingTimes': 1,
'unlimited': false
}
}
)
.then(
function(result) {
// do something next
},
function(error) {
// handle error
}
);For the full documentation see MockServer - Creating Expectations.
The same expectation can also be built with a chainable API that mirrors the Java
client's when(...) / ForwardChainExpectation:
mockServerClient("localhost", 1080)
.when({ path: '/somePath' })
.respond({ statusCode: 200, body: 'some_response_body' });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:
mockServerClient("localhost", 1080)
.when({ path: '/somePath' })
.withTimes(2)
.withTimeToLive({ unlimited: false, timeToLive: 60, timeUnit: 'SECONDS' })
.withPriority(10)
.withId('my-id')
.forward({ host: 'localhost', port: 8081 });
⚠️ Positional argument order differs from the procedural methods.when(...)takes its optional arguments aswhen(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 particularwhen(req, 2, 5)setstimeToLive = 5(which expects an object, so it is ignored) and leaves the priority unset — it does not set the priority to5. 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):
mockServerClient("localhost", 1080)
.when({ path: '/somePath' }, 2, { unlimited: false, timeToLive: 60, timeUnit: 'SECONDS' }, 10)
.respond({ statusCode: 201 });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(...).
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:
// Server-Sent Events (SSE)
client.respondWithSse('/events', {
events: [
{ event: 'message', data: 'first' },
{ event: 'message', data: 'second' }
],
closeConnection: true
});
// WebSocket
client.respondWithWebSocket('/ws', {
messages: [ { text: 'hello' } ],
closeConnection: false
});
// DNS
client.respondWithDns('example.com', {
answerRecords: [
{ name: 'example.com', type: 'A', ttl: 300, value: '127.0.0.1' }
],
responseCode: 'NOERROR'
});
// Raw binary
client.respondWithBinary('/binary', {
binaryData: Buffer.from('hello').toString('base64')
});
// gRPC server-streaming
client.respondWithGrpcStream('/my.Service/StreamItems', {
statusName: 'OK',
messages: [
{ json: '{"value":"first"}' },
{ json: '{"value":"second"}' }
],
closeConnection: true
});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).
// Mock an A2A agent: a static agent-card document over GET plus JSON-RPC 2.0
// tasks/send, tasks/get and tasks/cancel over POST.
client.a2aMock('/a2a')
.withAgentName('TranslatorAgent')
.withAgentDescription('Translates text between languages')
.withSkill('translate')
.withName('Translation')
.withDescription('Translates text')
.withTag('i18n')
.withExample('Translate hello to Spanish')
.and()
// optional SSE streaming (advertises capabilities.streaming and streams
// status-update / artifact-update events):
.withStreaming()
// optional push notifications (echoes the config and POSTs each completed
// task to the webhook while still replying to the caller):
.withPushNotifications('http://localhost:1234/callback')
// custom handler matched by a regex over the inbound message text:
.onTaskSend()
.matchingMessage('translate.*')
.respondingWith('Hola')
.and()
.applyTo(); // returns a promise; omit the client arg to use this clientverifySLO(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).
// Evaluate SLOs over the last 60s of forwarded traffic
client.verifySLO({
name: 'checkout-slo',
window: { type: 'LOOKBACK', lookbackMillis: 60000 },
minimumSampleCount: 10,
objectives: [
{ sli: 'LATENCY_P95', comparator: 'LESS_THAN', threshold: 250 },
{ sli: 'ERROR_RATE', comparator: 'LESS_THAN_OR_EQUAL', threshold: 0.01 }
]
}).then(
function (verdict) { /* verdict.result === 'PASS' | 'INCONCLUSIVE' */ },
function (failure) { /* FAIL verdict body, or enablement guidance */ }
);
// Run a two-stage chaos experiment against an upstream host
client.startChaosExperiment({
name: 'rolling-brownout',
stages: [
{ durationMillis: 30000, profiles: { 'api.example.com': { errorStatus: 503, errorProbability: 0.25 } } },
{ durationMillis: 30000, profiles: { 'api.example.com': { latency: { value: 500, timeUnit: 'MILLISECONDS' } } } }
]
});It is also possible to verify that request were made:
mockServerClient("localhost", 1080)
.verify(
{
'method': 'POST',
'path': '/somePath',
'body': 'someBody'
},
1, true
)
.then(
function() {
// do something next
},
function(failure) {
// handle verification failure
}
);It is furthermore possible to verify that sequences of requests were made in a specific order:
mockServerClient("localhost", 1080)
.verifySequence(
{
'method': 'POST',
'path': '/somePathOne',
'body': 'someBody'
},
{
'method': 'GET',
'path': '/somePathTwo'
},
{
'method': 'GET',
'path': '/somePathThree'
}
)
.then(
function() {
// do something next
},
function(failure) {
// handle verification failure
}
);For the full documentation see MockServer - Verifying Requests.
The client supports matcher-driven interactive breakpoints over the callback WebSocket. Register a breakpoint matcher to pause forwarded/proxied exchanges at specific phases and inspect/modify/continue them via callback handlers.
// REQUEST phase only
client.addRequestBreakpoint(
{ path: '/api/.*' },
function (request) {
// inspect or modify the request; return a request to continue or a response to abort
request.path = '/api/modified';
return request;
}
).then(function (breakpointId) {
console.log('Breakpoint registered:', breakpointId);
});
// REQUEST + RESPONSE phases
client.addRequestAndResponseBreakpoint(
{ path: '/api/.*' },
function (request) { return request; }, // REQUEST handler
function (request, response) { return response; } // RESPONSE handler
).then(function (breakpointId) {
console.log('Breakpoint registered:', breakpointId);
});
// All phases with stream frame handler
client.addBreakpoint(
{ path: '/stream/.*' },
['REQUEST', 'RESPONSE', 'RESPONSE_STREAM', 'INBOUND_STREAM'],
function (request) { return request; },
function (request, response) { return response; },
function (pausedFrame) {
// pausedFrame has: correlationId, streamId, sequenceNumber, direction, phase, body (base64)
return { action: 'CONTINUE' };
// Other actions: MODIFY (with body), DROP, INJECT (with body), CLOSE
}
).then(function (breakpointId) {
console.log('Breakpoint registered:', breakpointId);
});// List all matchers
client.listBreakpointMatchers().then(function (result) {
console.log(result.matchers);
});
// Remove a specific matcher
client.removeBreakpointMatcher(breakpointId);
// Clear all matchers
client.clearBreakpointMatchers();The client supports TC39 explicit resource management, so a using / await using
binding resets the server automatically when it goes out of scope — no manual
afterEach(() => client.reset()) needed:
const { mockServerClient } = require('mockserver-client');
it('records the request', async () => {
await using client = mockServerClient('localhost', 1080);
// ... register expectations, make requests ...
// the server is reset when `client` goes out of scope
});If your runtime/transpiler does not yet support await using, reset explicitly
in a Jest/Mocha hook:
const { mockServerClient } = require('mockserver-client');
const client = mockServerClient('localhost', 1080);
afterEach(() => client.reset());This package (mockserver-client) is the REST/WebSocket client for communicating with a running MockServer. To download and launch a local MockServer instance (no Java or Docker required), use the companion mockserver-node package:
npx -p mockserver-node mockserver run -p 1080mockserver-node downloads a self-contained platform bundle (mockserver-<version>-<os>-<arch>) from the GitHub Release, verifies its SHA-256, caches it per-user, and starts it. See the mockserver-node README for full details including environment variables (MOCKSERVER_BINARY_BASE_URL, MOCKSERVER_BINARY_CACHE, MOCKSERVER_SKIP_BINARY_DOWNLOAD) and supported platforms (linux/darwin/windows on x86_64/aarch64).
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
All notable and significant changes are detailed in the MockServer changelog
Task submitted by James D Bloom
MockServer includes a built-in MCP (Model Context Protocol) server that enables AI coding assistants to create expectations, verify requests, and debug HTTP traffic programmatically.
- MCP Endpoint:
http://localhost:1080/mockserver/mcp - AI Documentation: llms.txt
- Setup Guide: AI Integration