Skip to main content

Quick start

Test an HTTP client against WireMock serving recorded stubs.

1. Add stubs​

A stub pairs a request pattern with a response. Put stubs in mappings/, response bodies in __files/:

__mocks__/wiremock/
├── mappings/
│ ├── create-payment.json POST /payments → 201
│ └── get-payments.json GET /payments → 200, body from __files/
└── __files/
└── body-payments.json
examples/__mocks__/wiremock/mappings/get-payments.json
{
"request": {
"method": "GET",
"urlPath": "/payments"
},
"response": {
"status": 200,
"bodyFileName": "body-payments.json",
"headers": {
"Content-Type": "application/json"
}
}
}

Source: examples/__mocks__/wiremock/mappings/get-payments.json

2. Write the suite​

examples/getting-started/quick-start.e2e.test.ts
import { afterAll, afterEach, beforeAll, expect, it } from "vitest"; // or Jest
import { type StartedWiremockContainer, WiremockContainer } from "@hellaweb3/wiremock-testcontainers-nodejs";
import { PaymentsClient } from "../app/payments-client"; // the code under test

let wiremock: StartedWiremockContainer;

beforeAll(async () => {
wiremock = await new WiremockContainer()
.withMappings("./__mocks__/wiremock") // mappings/ + __files/
.start();
await wiremock.waitUntilReady();
}, 120_000); // the first image pull can be slow

afterEach(() => wiremock.reset()); // pristine stubs, empty journal – no restart
afterAll(() => wiremock?.stop());

it("lists the recorded payments", async () => {
const page = await new PaymentsClient(wiremock.getUrl()).list();

expect(page.meta.totalItems).toBe(2);
expect(await wiremock.countRequests({ method: "GET", url: "/payments" })).toBe(1);
});

Source: examples/getting-started/quick-start.e2e.test.ts (lines 8–29)

  • start() once per file; waitUntilReady() waits for WireMock's health check. The long hook timeout covers the first image pull.
  • Pass wiremock.getUrl() to the code under test – here a fetch-based client.
  • reset() after each test restores the registered stubs and empties the journal.

3. Run it​

npx vitest run

No container runtime? See running without Docker.

Share the mock between suites​

Define the container once:

examples/getting-started/payments-api.ts
import { WiremockContainer } from "@hellaweb3/wiremock-testcontainers-nodejs";

/** Stubs recorded from the payments API: `mappings/` plus the `__files/` they reference. */
export const PAYMENTS_STUBS = "./__mocks__/wiremock";

/** A WireMock container serving the payments API – call `.start()` on it. */
export function paymentsApi(): WiremockContainer {
return new WiremockContainer().withMappings(PAYMENTS_STUBS);
}

Source: examples/getting-started/payments-api.ts (lines 9–17)

Start it in each suite:

examples/getting-started/shared-definition.e2e.test.ts
import { paymentsApi } from "./payments-api";

let wiremock: StartedWiremockContainer;

beforeAll(async () => {
wiremock = await paymentsApi().start();
await wiremock.waitUntilReady();
}, 120_000);

Source: examples/getting-started/shared-definition.e2e.test.ts (lines 11–18)

Validate it without Docker​

Registrations throw as they are made, so a unit test catches a broken path or stub:

examples/getting-started/payments-api.test.ts
it("registers the recorded stubs", () => {
expect(paymentsApi()).toBeInstanceOf(WiremockContainer);
});

it("fails fast on a fixture directory without mappings/", () => {
expect(() => new WiremockContainer().withMappings("./__mocks__/missing")).toThrow(
'WiremockContainer.withMappings: "__mocks__/missing/mappings" does not exist',
);
});

Source: examples/getting-started/payments-api.test.ts (lines 13–21)

Next​