mockserver-node weekly downloads statistics

mockserver-node

Node module and grunt plugin to start and stop MockServer and MockServer proxy

Community

• Roadmap:                     <a href="https://github.com/orgs/mock-server/projects/1"><img height="20px" src="https://mock-server.com/images/GitHub_Logo-md.png" alt="GitHub Project"></a>
• Feature Requests:   <a href="https://github.com/mock-server/mockserver-monorepo/issues"><img height="20px" src="https://mock-server.com/images/GitHub_Logo-md.png" alt="Github Issues"></a>
• Issues / Bugs:           <a href="https://github.com/mock-server/mockserver-monorepo/issues"><img height="20px" src="https://mock-server.com/images/GitHub_Logo-md.png" alt="Github Issues"></a>
• Discussions:               <a href="https://github.com/mock-server/mockserver-monorepo/discussions"><img height="20px" src="https://mock-server.com/images/GitHub_Logo-md.png" alt="GitHub Discussions"></a>

Getting Started

This node module can be used to start and stop MockServer and the MockServer proxy as a node module or as a Grunt plugin. More information about the MockServer can be found at mock-server.com.

You may install this plugin / node module with the following command:

npm install mockserver-node --save-dev

Run without Java or Docker (binary bundle)

The mockserver command downloads a self-contained MockServer bundle (a trimmed Java runtime + the server + a launcher) for your platform on first use and runs it — no Java installation and no Docker required:

npx -p mockserver-node mockserver run -p 1080
npx -p mockserver-node mockserver --openapi ./petstore.yaml -p 1080
npx -p mockserver-node mockserver --help

The bundle is fetched from the MockServer GitHub Release, verified against its published SHA-256, and cached per-user. Environment overrides:

Variable	Purpose
MOCKSERVER_BINARY_BASE_URL	mirror host for the release assets (corporate / air-gapped)
MOCKSERVER_BINARY_CACHE	cache directory (default: per-OS user cache)
MOCKSERVER_SKIP_BINARY_DOWNLOAD	fail instead of downloading (use with a pre-seeded cache)
NODE_EXTRA_CA_CERTS	extra CA bundle for TLS-inspecting proxies (honoured by Node)
HTTPS_PROXY / HTTP_PROXY	used when an https/http proxy agent module is installed (otherwise set a mirror)

The SHA-256 is co-hosted with the archive, so it verifies download integrity (no corruption/truncation) but not provenance; a future release will add cosign signatures for provenance.

The bundle exposes the full MockServer CLI (run, proxy, openapi, version, help). This is the reference implementation of the on-demand-binary pattern for the MockServer client libraries.

Node Module

To start or stop the MockServer from any Node.js code you need to import this module using require('mockserver-node') as follows:

var mockserver = require('mockserver-node');

The package includes TypeScript typings, which use Node's own types and so need @types/node in the project. It is a CommonJS module, so in TypeScript import it with import mockserver = require('mockserver-node'), or with import mockserver from 'mockserver-node' when esModuleInterop is on. The option types are mockserver.StartServerOptions and mockserver.StopServerOptions.

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

The package's exports map names every path that can be imported or required: the package itself, index, downloadJar and downloadBinary, each with and without .js, and package.json. Any other path inside the package fails with ERR_PACKAGE_PATH_NOT_EXPORTED. The mockserver command and the Grunt tasks (grunt.loadNpmTasks('mockserver-node')) are found by their files, not through the map, and work as before.

Then you can use either the start_mockserver or stop_mockserver functions as follows:

mockserver.start_mockserver({
                serverPort: 1080,
                trace: true
            });

// do something

mockserver.stop_mockserver({
                serverPort: 1080
            });

The MockServer uses port unification to support HTTP, HTTPS, SOCKS, HTTP CONNECT, Port Forwarding Proxying on the same port. A client can then connect to the single port with both HTTP and HTTPS as the socket will automatically detected SSL traffic and decrypt it when required.

Requirements

start_mockserver runs MockServer with the java command, so Java 17 or later must be installed and its bin directory must be on the PATH of the Node.js process. JAVA_HOME is not used, and there is no option for the location of java. The mockserver command described above needs no Java.

When a start fails

start_mockserver returns a promise. It is rejected with an Error, and the same message is printed to stderr, when:…