Registering stubs
| Method | Registers | In the container |
|---|---|---|
withMappings(directory) | A directory's mappings/ and optional __files/ | mappings/…, __files/… |
withMapping(name, source) | One mapping file, or stubs inline | mappings/<name>.json |
withFiles(...sources) | Response bodies | __files/<name> |
Combine them freely, before start(). Each call is validated immediately –
see registration rules.
return new WiremockContainer()
.withMappings("./__mocks__/wiremock") // a directory: mappings/ and __files/
.withMapping("health", HEALTH_STUB) // one mapping file → mappings/health.json
.withMapping("accounts", ACCOUNT_STUB)
.withMapping("statements", STATEMENT_STUBS) // a file may hold { "mappings": [...] }
.withMapping("exchange-rates", EXCHANGE_RATE_STUB)
.withMapping("ping", { json: PING_STUB }) // inline: an object…
.withMapping("maintenance", { json: MAINTENANCE_STUB }) // …or a JSON string
.withMapping("payments/refunds", REFUND_STUBS) // "/" nests: mappings/payments/refunds.json
.withFiles(STATEMENT_BODY, INVOICE_BODY, EXCHANGE_RATES_BODY); // bodies → __files/
Source: examples/stubs/stubs.ts (lines 59–68)
Load a recorded directory
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)
mappings/is required,__files/optional; subdirectories are included.- The path is relative to the working directory.
- Fits the output of WireMock's record and playback.
Register a mapping file
withMapping(name, source) copies one file to mappings/<name>.json. name may contain /.
The source is any file source. A file holds one stub or several:
{
"mappings": [
{
"request": { "method": "GET", "url": "/statements/2026-10" },
"response": {
"status": 200,
"headers": { "Content-Type": "text/csv" },
"bodyFileName": "statement.csv"
}
},
{
"request": { "method": "GET", "url": "/invoices/inv-001" },
"response": {
"status": 200,
"headers": { "Content-Type": "application/json" },
"bodyFileName": "invoices/inv-001.json"
}
}
]
}
Source: examples/stubs/fixtures/statements.json
Register stubs inline
Pass { json }. An object – checked against WiremockStubMapping with satisfies:
/** One stub, written in TypeScript: `satisfies` checks its shape and keeps its literal types. */
export const PING_STUB = {
request: { method: "GET", url: "/ping" },
response: { status: 200, body: "pong" },
} satisfies WiremockStubMapping;
Source: examples/stubs/stubs.ts (lines 23–27)
Several stubs – WiremockMappingSource types any withMapping() source:
/** Several stubs in one registration – `{ mappings: [...] }`, like a WireMock mapping file. */
export const REFUND_STUBS: WiremockMappingSource = {
json: {
mappings: [
{
request: { method: "POST", url: "/refunds" },
response: { status: 202, jsonBody: { id: "ref-1", status: "ACCEPTED" } },
},
{
request: { method: "GET", urlPathPattern: "/refunds/ref-[0-9]+" },
response: { status: 200, jsonBody: { status: "REFUNDED" } },
},
],
},
};
Source: examples/stubs/stubs.ts (lines 31–45)
A JSON string, copied verbatim:
/** A stub as a JSON string – e.g. generated elsewhere – is copied verbatim. */
export const MAINTENANCE_STUB = JSON.stringify({
request: { method: "GET", url: "/maintenance" },
response: { status: 503, headers: { "Retry-After": "120" } },
});
Source: examples/stubs/stubs.ts (lines 49–53)
Add response bodies
withFiles(...sources) puts files in __files/, where a stub's response.bodyFileName finds
them: at their base name, or at name. All or nothing; binary files are fine.
/** `{ file }`; `name` sets the path below `__files/` – the base name otherwise. */
export const INVOICE_BODY: WiremockStaticFile = { file: "./stubs/fixtures/invoice.json", name: "invoices/inv-001.json" };
/** Any source works for bodies, too: this one lands at `__files/rates.json`. */
export const EXCHANGE_RATES_BODY: WiremockStaticFile = { package: "@examples/payments-stubs", file: "__files/rates.json" };
/** A plain path lands at `__files/statement.csv`. */
export const STATEMENT_BODY: WiremockStaticFile = "./stubs/fixtures/statement.csv";
Source: examples/stubs/sources.ts (lines 33–38)
it("withFiles(): bodies are served byte for byte", async () => {
const statement = await get("/statements/2026-10");
expect(statement.type).toBe("text/csv");
expect(statement.body).toBe(readFileSync("./stubs/fixtures/statement.csv", "utf8"));
});
Source: examples/stubs/stubs.e2e.test.ts (lines 47–51)
Registration rules
- A container path registered from another source throws; the same file again is a no-op.
- Stub ids must be unique – WireMock refuses to start otherwise.
- Invalid input throws at once, naming the method: see troubleshooting.
it("registering the same file under the same name again is a no-op", () => {
expect(() => new WiremockContainer().withMapping("health", HEALTH_STUB).withMapping("health", HEALTH_STUB)).not.toThrow();
});
it("a name already taken by another source is rejected – nothing is silently overwritten", () => {
const container = new WiremockContainer().withMapping("ping", { json: PING_STUB });
expect(() => container.withMapping("ping", HEALTH_STUB)).toThrow(
'"/home/wiremock/mappings/ping.json" is already registered from inline JSON',
);
});
it("stub ids must be unique across registrations – WireMock refuses to start otherwise", () => {
const stub = { id: "8f2b0c55-6a57-4d8e-9d4e-6c1f3e1f0a01", ...PING_STUB };
const container = new WiremockContainer().withMapping("ping", { json: stub });
expect(() => container.withMapping("ping-again", { json: stub })).toThrow(
'stub id "8f2b0c55-6a57-4d8e-9d4e-6c1f3e1f0a01" in inline JSON is already used by "/home/wiremock/mappings/ping.json"',
);
});
it("withFiles() is all or nothing: one missing file rejects the whole call", () => {
const container = new WiremockContainer();
expect(() => container.withFiles("./stubs/fixtures/statement.csv", "./stubs/fixtures/missing.csv")).toThrow("does not exist");
expect(() => container.withFiles("./stubs/fixtures/statement.csv")).not.toThrow(); // nothing was registered
});
Source: examples/stubs/stubs.test.ts (lines 24–47)
List the loaded stubs
it("the admin API lists every registered stub", async () => {
const { mappings } = (await (await fetch(wiremock.getMappingUrl())).json()) as { mappings: unknown[] };
expect(mappings).toHaveLength(11); // 2 recorded + 1 + 1 + 2 + 1 + 1 + 1 + 2
});
Source: examples/stubs/stubs.e2e.test.ts (lines 69–72)
To add a stub for one test only, see stubs added at runtime.