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 afetch-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
- Register stubs from files, packages or inline JSON
- Verify requests
- Isolate tests, including stateful scenarios