Skip to main content

Registering stubs

MethodRegistersIn the container
withMappings(directory)A directory's mappings/ and optional __files/mappings/…, __files/…
withMapping(name, source)One mapping file, or stubs inlinemappings/<name>.json
withFiles(...sources)Response bodies__files/<name>

Combine them freely, before start(). Each call is validated immediately – see registration rules.

examples/stubs/stubs.ts
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​

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)

  • 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:

examples/stubs/fixtures/statements.json
{
"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:

examples/stubs/stubs.ts
/** 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:

examples/stubs/stubs.ts
/** 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:

examples/stubs/stubs.ts
/** 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.

examples/stubs/sources.ts
/** `{ 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)

examples/stubs/stubs.e2e.test.ts
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.
examples/stubs/stubs.test.ts
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​

examples/stubs/stubs.e2e.test.ts
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.