WireMock REST Client

1.11.0 verified Sat Apr 25 auth: no javascript

Lightweight TypeScript REST client for interacting with a running WireMock server (v1.11.0) via its OpenAPI 3.0 endpoints. Provides programmatic access to stub mappings, recordings, requests, and scenarios. Supports TypeScript types, global reset, shutdown, and bulk operations from files/directories. Actively maintained with monthly releases. Key differentiators: full API coverage, TypeScript-first, file-based mapping creation, and proxy/header configuration.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Attempting to require('wiremock-rest-client') in CommonJS project.

fix

Change to ES module imports: use import { WireMockRestClient } from 'wiremock-rest-client' and set 'type': 'module' in package.json, or use dynamic import.

error TypeError: Cannot read properties of undefined (reading 'getAllMappings') ↓

cause Accessing wireMock.mappings before client is fully initialized (async issue).

fix

Ensure the client is instantiated before calling service methods. No async initialization needed; error typically due to null/undefined variable.

error HTTPError: Response code 404 (Not Found) ↓

cause WireMock server not running or wrong base URL provided to constructor.

fix

Verify WireMock server is started on expected host/port. Default is http://localhost:8080. Use console to log the URL.

error Mapping already exists with ID: ... ↓

cause Duplicate stub mapping IDs when using createMappingFromDir or createMappingFromFile with previously stored mappings.

fix

Call resetAllMappings() before bulk imports, or use updateMapping() to overwrite specific IDs.

error Timeout awaiting 'request' for 5000ms ↓

cause WireMock server not responding or network issue. Default timeout is 5000ms.

fix

Increase timeout via config: new WireMockRestClient(url, { timeout: 10000 }). Check server logs.

Warnings

breaking Version 1.0.0 changed all methods to return Promises. Synchronous calls will no longer work. ↓

fix Update code to use await or .then(). All methods now return Promise.

breaking Version 2.0.0 (future) may drop Node.js 12 support. End-of-life Node versions are not tested. ↓

fix Upgrade Node.js to >=14.15.0 or >=16.0.0 (LTS).

deprecated The mappings.createMapping method with plain object signature will be deprecated in favor of typed StubMapping. ↓

fix Use StubMapping type or follow OpenAPI spec shape explicitly.

gotcha When using createMappingFromFile, the file path is relative to process.cwd(), not the source file location. ↓

fix Use absolute paths or ensure correct working directory. Call path.resolve(__dirname, 'stubs/hello.json') if needed.

gotcha The global.shutdown() method will terminate the WireMock server process. Be careful in test suites where the server is shared. ↓

fix Only call shutdown() in cleanup hooks (e.g., afterAll) and ensure no other tests depend on the same server.

gotcha Recording operations (startRecording, stopRecording, etc.) require WireMock server to be running in record mode. Not available in standalone jar without --record-mappings flag. ↓

fix Start WireMock with --record-mappings or use snapshot functionality alternatively.

Install

npm install wiremock-rest-client

yarn add wiremock-rest-client

pnpm add wiremock-rest-client

Imports

WireMockRestClient

wrong

const WireMockRestClient = require('wiremock-rest-client')

correct

import { WireMockRestClient } from 'wiremock-rest-client'

Package is ESM-only; CommonJS require will fail. Default export is not available.

StubMapping
```
import { StubMapping } from 'wiremock-rest-client'
```
TypeScript type for stub mapping objects. Also exported: DelayDefinition, RecordSpec, RequestPattern, ContentPattern.

WireMockRestClient (with type import)

wrong

import { WireMockRestClient } from 'wiremock-rest-client' (for type-only usage)

correct

import type { WireMockRestClient } from 'wiremock-rest-client'

When only using type annotations, prefer type import to avoid runtime side effects.

new WireMockRestClient(url)
wrong
```
new WireMockRestClient()
```
correct
```
new WireMockRestClient('http://localhost:8080')
```
Constructor requires WireMock server base URL as first argument. Optional config object second.

Quickstart

Demonstrates client initialization, resetting server state, creating stub mappings via object and file, fetching all mappings, and graceful shutdown.

import { WireMockRestClient } from 'wiremock-rest-client';

async function main() {
  const wireMock = new WireMockRestClient('http://localhost:8080');

  // Reset all state
  await wireMock.global.resetAll();

  // Create a stub mapping
  const stubMapping = {
    request: {
      method: 'GET',
      urlPathPattern: '/api/hello'
    },
    response: {
      status: 200,
      jsonBody: { message: 'Hello World' },
      headers: {
        'Content-Type': 'application/json'
      }
    }
  };
  const created = await wireMock.mappings.createMapping(stubMapping);
  console.log('Created mapping:', created);

  // Get all mappings
  const allMappings = await wireMock.mappings.getAllMappings();
  console.log('Total mappings:', allMappings.meta?.total || 'N/A');

  // Create from file (relative to cwd)
  await wireMock.mappings.createMappingFromFile('./stubs/hello.json');

  // Shutdown server
  await wireMock.global.shutdown();
}

main().catch(console.error);