wiremock-mapper

DSL for setting up WireMock mappings

A TypeScript/JavaScript library that provides a fluent API for creating WireMock mappings. WireMock is a simulator for HTTP-based APIs that allows you to stub and mock web services during development and testing.

Prerequisites

• A running WireMock server (default: http://localhost:8080)
• Node.js 12+
• TypeScript (recommended)

Installation

npm install wiremock-mapper

Configuring

import { Configuration } from 'wiremock-mapper';

Configuration.wireMockBaseUrl = 'http://localhost:8080/some_path_prefix'; // default is 'http://localhost:8080'

Creating a global mapping

Global mappings are a way to predefine part of your request/response configuration that will be applied to all mappings created afterwards.

import { Configuration } from 'wiremock-mapper';

// Set up global configuration that applies to all future mappings
Configuration.createGlobalMapping((request, response) => {
  // Add common headers to all requests
  request.withHeader('Authorization').equalTo('Bearer token123');

  // Add common response headers
  response.withHeader('Content-Type').equalTo('application/json');
  response.withHeader('X-API-Version').equalTo('v1');
});

// Now all subsequent mappings will include these configurations

Reset global mapping

import { Configuration } from 'wiremock-mapper';

// Clear all global mappings
Configuration.reset();

Create a mapping

Import the library

import { WireMockMapper } from 'wiremock-mapper';

Mappings are created with WireMockMapper.createMapping() which takes a function argument defining the mock behavior. It asynchronously sends the configuration to the WireMock server.

await WireMockMapper.createMapping((req, res) => {});

Define matching parameters

All request modifiers are set from req provided by createMapping, and return an instance of RequestBuilder, MatchBuilder, or UrlMatchBuilder. These can be chained together to form a complete request expectation.

It should read like a sentence when set up properly.

await WireMockMapper.createMapping((req, res) => {
  req.isAGet.withUrlPath.matching('/my/.*/path');
});

Interfaces

RequestBuilder

Method	Argument(s)	Effect	Returns
isAGet	none	sets request method to GET	RequestBuilder
isAPost	none	sets request method to POST	RequestBuilder
isAPut	none	sets request method to PUT	RequestBuilder
isADelete	none	sets request method to DELETE	RequestBuilder
isAHead	none	sets request method to HEAD	RequestBuilder
isAnOptions	none	sets request method to OPTIONS	RequestBuilder
isATrace	none	sets request method to TRACE	RequestBuilder
isAnyVerb	none	sets request method to ANY	RequestBuilder
withBody	none	sets request body	RequestBuilder
withBasicAuth	username: string, password: string	sets basic auth	RequestBuilder
withUrl	none	sets expected URL	UrlMatchBuilder
withUrlPath	none	sets URL path match to urlPathPattern	UrlMatchBuilder
withCookie	key: string	sets request cookie	MatchBuilder
withHeader	key: string	sets request header	MatchBuilder
withQueryParam	key: string	sets request query parameter	MatchBuilder

UrlMatchBuilder

Method	Arguments	Effect	Returns
equalTo	url: string	Matches text given	RequestBuilder
matching	regexp: string	Matches with regular expression	RequestBuilder

MatchBuilder

Method	Argument(s)	Returns
absent	none	RequestBuilder
containing	value: string	RequestBuilder
equalTo	value: string	RequestBuilder
equalToJson	json: any, ignoreArrayOrder: boolean, ignoreExtraElements: boolean	RequestBuilder
equalToXml	xml: string	RequestBuilder
matching	value: string	RequestBuilder
matchingJsonPath	path: string	RequestBuilder
matchingXPath	xpath: string	RequestBuilder
notMatching	value: string	RequestBuilder

Define response behavior

Responses are created from res provided by WireMockMapper.createMapping()

await WireMockMapper.createMapping((req, res) => {
  res
    .withJsonBody({
      someKey: 'theValue',
      otherKey: 'otherValue'
    })
    .withStatus(200)
    .withStatusMessage('ok');
});

Interface

ResponseBuilder

Method	Argument(s)	Returns
withBody	value: string	ResponseBuilder
withDelay	milliseconds: number	ResponseBuilder
withHeader	key: string	ResponseBuilder
withJsonBody	value: object	ResponseBuilder
withStatus	statusCode: object	ResponseBuilder
withStatusMessage	statusMessage: string	ResponseBuilder
withTransformer	transformerName: string	ResponseBuilder

Example

await WireMockMapper.createMapping((req, res) => {
  req.isAGet.withUrlPath.equalTo('/my/api/path');
  res
    .withJsonBody({
      someKey: 'theValue',
      otherKey: 'otherValue'
    })
    .withStatus(200)
    .withStatusMessage('ok');
});

Get Requests Received

Get all requests

await WireMockMapper.getRequests();

Get all requests for a given stub id

await WireMockMapper.getRequests({ stubId: 'some_stub_id' });

The interface for the returned object can be found here.

Jest Matchers

The library provides custom Jest matchers for testing WireMock interactions with built-in retry logic for handling asynchronous operations.

Setup

import { wiremockMapperMatchers } from 'wiremock-mapper';

// Extend Jest with WireMock matchers
expect.extend(wiremockMapperMatchers);

Available Matchers

toHaveBeenRequested(options?)

Verifies that a stub received at least one request.

const stubId = await WireMockMapper.createMapping((req, res) => {
  req.isAGet.withUrlPath.equalTo('/api/users');
  res.withJsonBody([]).withStatus(200);
});

// Make API call
await fetch('http://localhost:8080/api/users');

// Verify the stub was called
await expect(stubId).toHaveBeenRequested();

// With custom retry options
await expect(stubId).toHaveBeenRequested({ retries: 5, delay: 100 });

toHaveBeenRequestedWith(expected, options?)

Verifies that a stub received a request with the specified payload.

const stubId = await WireMockMapper.createMapping((req, res) => {
  req.isAPost.withUrlPath.equalTo('/api/users');
  res.withJsonBody({ id: 123 }).withStatus(201);
});

const userData = { name: 'John Doe', email: '[email protected]' };

// Make API call with payload
await fetch('http://localhost:8080/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(userData)
});

// Verify the stub was called with expected payload
await expect(stubId).toHaveBeenRequestedWith(userData);

toHaveBeenRequestedTimes(expectedCount, options?)

Verifies that a stub received exactly the specified number of requests.

const stubId = await WireMockMapper.createMapping((req, res) => {
  req.isAGet.withUrlPath.equalTo('/api/health');
  res.withBody('OK').withStatus(200);
});

// Make multiple API calls
await fetch('http://localhost:8080/api/health');
await fetch('http://localhost:8080/api/health');
await fetch('http://localhost:8080/api/health');

// Verify the stub was called exactly 3 times
await expect(stubId).toHaveBeenRequestedTimes(3);

Global Matcher Configuration

You can configure global defaults for all matchers:

import { Configuration } from 'wiremock-mapper';

// Set global retry options
Configuration.setMatcherOptions({
  retries: 10, // Number of retry attempts (default: 15)
  delay: 100 // Delay between retries in milliseconds (default: 200)
});

Individual matchers can override global settings:

// Override global settings for this specific assertion
await expect(stubId).toHaveBeenRequested({ retries: 3, delay: 50 });

Matcher Options

Option	Type	Default	Description
retries	number	15	Number of retry attempts when waiting for requests
delay	number	200	Delay in milliseconds between retry attempts

Example Test

import {
  WireMockMapper,
  Configuration,
  wiremockMapperMatchers
} from 'wiremock-mapper';

expect.extend(wiremockMapperMatchers);

describe('API Tests', () => {
  beforeAll(() => {
    Configuration.wireMockBaseUrl = 'http://localhost:8080';
  });

  beforeEach(async () => {
    await WireMockMapper.clearAllMappings();
  });

  it('should handle user creation', async () => {
    const stubId = await WireMockMapper.createMapping((req, res) => {
      req.isAPost.withUrlPath.equalTo('/api/users');
      res.withJsonBody({ id: 123, name: 'John Doe' }).withStatus(201);
    });

    const userData = { name: 'John Doe', email: '[email protected]' };

    await fetch('http://localhost:8080/api/users', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(userData)
    });

    await expect(stubId).toHaveBeenRequestedWith(userData);
  });
});

Troubleshooting

Common Issues

WireMock server not running

• Ensure WireMock is running on the expected port (default: 8080)
• Check if the Configuration.wireMockBaseUrl is correctly set

Connection refused errors

• Verify the WireMock server URL and port
• Check if there are any firewall restrictions
• Ensure the WireMock server is accessible from your application

Mapping not working as expected

• Check the WireMock server logs for any errors
• Verify your request matching patterns are correct
• Use WireMockMapper.getRequests() to see what requests were actually received

TypeScript compilation errors

• Ensure you have the latest version of TypeScript installed
• Check that your tsconfig.json includes the necessary type definitions

Getting Help

• Check the GitHub Issues for existing problems
• Review the WireMock documentation for underlying concepts
• Create a new issue with a minimal reproduction case if needed