Registry / testing / mockserver-client

mockserver-client

JSON →
library7.1.0jsnpmunverified

The `mockserver-client` is a Node.js and browser client library designed to facilitate interaction with a running MockServer instance. It allows developers to programmatically define, update, and verify HTTP/HTTPS expectations against a MockServer. Key functionalities include setting simple or complex request/response pairs, forwarding requests, and verifying received requests. The current stable version is 5.15.0, which was last published over three years ago. While the core MockServer project remains actively developed, this specific client library exhibits a slower release cadence, suggesting it is in maintenance mode rather than active development for new features or compatibility updates. A key characteristic is that MockServer itself is a Java-based application, which needs to be running separately, often managed by `mockserver-node` or other methods. This client is a declarative mocking tool, meaning expectations are hand-written, which can lead to 'mock drift' if the real APIs evolve significantly without corresponding updates to the mock definitions.

npm install mockserver-client
INSTALL
IMPORT
SIG · MOCKSERVER-CLIENT
M
mockserver-client
testingjavascriptv7.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

mockServerClient
import { mockServerClient } from 'mockserver-client';
const mockServerClient = require('mockserver-client'); // Missing '.mockServerClient' property access const mockServerClient = require('mockserver-client')(); // Incorrectly assuming direct function export
The primary function to instantiate a MockServer client. While written for CommonJS, TypeScript declarations enable named ESM imports. For older CJS, `const { mockServerClient } = require('mockserver-client');` is also correct.
HttpRequest
import { HttpRequest } from 'mockserver-client';
import { HttpRequest } from 'mockserver-client/models';
Interface for defining HTTP request matchers in expectations. Type definitions are bundled with the package and typically available from the main entry point.
HttpResponse
import { HttpResponse } from 'mockserver-client';
import { HttpResponse } from 'mockserver-client/types';
Interface for defining HTTP responses in expectations. Like `HttpRequest`, it's generally available as a named export from the main package.

Demonstrates how to initialize the MockServer client, set up both simple and complex HTTP expectations, and verify that requests were received, including error handling for connection issues.

import { mockServerClient, HttpRequest, HttpResponse, Expectation } from 'mockserver-client'; const host = 'localhost'; const port = 1080; const client = mockServerClient(host, port); async function setupAndVerifyMocks() { try { // Ensure a clean slate before setting new expectations await client.reset(); console.log('MockServer reset to clear previous expectations.'); // 1. Set up a simple expectation for a GET request const simpleRequest: HttpRequest = { method: 'GET', path: '/api/users/123', }; const simpleResponse: HttpResponse = { statusCode: 200, body: JSON.stringify({ id: 123, name: 'Jane Doe' }), headers: [{ name: 'Content-Type', values: ['application/json'] }], }; await client.mockSimpleResponse(simpleRequest.path, simpleResponse.body, simpleResponse.statusCode); console.log('Simple GET expectation set for /api/users/123.'); // 2. Set up a more complex expectation for a POST request with specific body matching const complexExpectation: Expectation = { httpRequest: { method: 'POST', path: '/api/orders', body: { type: 'JSON', json: { productId: 'P456', quantity: 2 }, matchType: 'STRICT', }, }, httpResponse: { statusCode: 201, body: JSON.stringify({ orderId: 'ORD789', status: 'created' }), delay: { timeUnit: 'MILLISECONDS', value: 100 }, }, times: { remainingTimes: 1 }, // This expectation will only be matched once }; await client.mockAnyResponse(complexExpectation); console.log('Complex POST expectation set for /api/orders.'); // In a real testing scenario, you would now make HTTP requests via your application // which would hit the MockServer based on the configured expectations. // Example: Verify that a specific request was made to the mock server // (This step would typically follow the actual application calls). await client.verify(simpleRequest, 1); // Verify /api/users/123 was called once console.log('Verified that /api/users/123 was called once.'); // Clean up specific expectations await client.clear({ path: '/api/users/123' }); await client.clear({ path: '/api/orders' }); console.log('Specific expectations cleared.'); } catch (error: any) { console.error('An error occurred during MockServer interaction:', error); if (error.code === 'ECONNREFUSED') { console.error(`ERROR: MockServer is likely not running or inaccessible at ${host}:${port}.`); console.error('Please ensure MockServer is started, for example, using ' + '`npm install -g mockserver-node` and then `mockserver-node -p 1080`.'); } } } setupAndVerifyMocks();
Debug
Known issues
gotchaThe `mockserver-client` npm package has not been updated in over three years (since v5.15.0). While the core MockServer project may have newer versions and features, this client might not support them or may have compatibility issues with recent Node.js versions or modern JavaScript syntax/tooling.
fix
Review the MockServer documentation for alternatives or newer client implementations if compatibility issues arise. Consider direct interaction with MockServer's REST API if the client library becomes a blocker for newer Node.js features.
affects: >=5.15.0
gotchaMockServer itself is a Java-based application and *must be running separately* for this client library to function. This client only provides an interface to an already-running MockServer instance, it does not start the server.
fix
Ensure MockServer is started before running code that uses `mockserver-client`. This can be done via Docker, a standalone JAR, or using the `mockserver-node` npm package (a separate project) to manage the server lifecycle from Node.js.
affects: >=0.8.0
gotchaDefining expectations using declarative JSON objects (as is common with MockServer and this client) can lead to 'mock drift'. This occurs when the actual API behavior changes, but the hand-written mock definitions are not updated, leading to tests passing against outdated mocks while real-world integration fails.
fix
Regularly review and update mock definitions to reflect current API specifications. Consider integrating contract testing or using traffic-recording/replay tools in conjunction with (or as an alternative to) declarative mocks to minimize drift.
affects: >=0.8.0
gotchaThe package's `engines` field specifies `"node": ">= 0.8.0"`, which is extremely old. While it might still run on newer Node.js versions, it has not been officially tested or updated for modern Node.js runtimes (e.g., Node.js 18, 20, 22).
fix
Exercise caution when using with very recent Node.js versions. Test thoroughly in your target environment. Be prepared for potential runtime issues due to breaking changes or deprecated APIs in Node.js itself.
affects: >=5.15.0
Errors
Common errors & fixes
connect ECONNREFUSED 127.0.0.1:1080
The MockServer instance is not running or is not accessible at the specified host and port.
fix
Start the MockServer application on the correct host and port before executing client code. For example, using `mockserver-node -p 1080` if `mockserver-node` is installed globally. Verify network connectivity if running in a container or remote environment.
TypeError: client.mockSimpleResponse is not a function
The `client` variable was not correctly initialized as a `mockServerClient` instance.
fix
Ensure `mockServerClient('localhost', 1080)` is called and its return value is assigned to `client`. Also, ensure `mockServerClient` itself is imported correctly (e.g., `import { mockServerClient } from 'mockserver-client';` or `const { mockServerClient } = require('mockserver-client');`).
Promise rejection without an error message (when interacting with MockServer)
MockServer returns an error response (e.g., bad request, server error) that the client's promise-based API rejects without a clear message in some cases, or the promise chain is missing a `.catch()` handler.
fix
Always include `.catch(error => console.error(error))` in your promise chains when interacting with `mockserver-client` methods. Inspect the `error` object for more details, which often contains an `httpResponse` or a `message` property from the MockServer. Check MockServer logs for more specific server-side errors.
Upgrade
Version history
7.1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources
mockserver-client — npm install mockserver-client · libregistry