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:

var mockServer = require('mockserver-client'),
    mockServerClient = mockServer.mockServerClient // MockServer and proxy client

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

Setup Expectation

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.

Fluent when().respond() API

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 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):

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(...).

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:

// 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
});

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).

// 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 client

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).

// 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' } } } }
    ]
});

Verify Requests

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.

Interactive Breakpoints

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.

Register a breakpoint

// 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);
});

Manage breakpoints

// List all matchers
client.listBreakpointMatchers().then(function (result) {
    console.log(result.matchers);
});

// Remove a specific matcher
client.removeBreakpointMatcher(breakpointId);

// Clear all matchers
client.clearBreakpointMatchers();

Using in tests

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());

Start / Launch MockServer

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 1080

mockserver-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).

Contributing

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.

Changelog

All notable and significant changes are detailed in the MockServer changelog

Task submitted by James D Bloom

AI Assistant Integration

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