Container lifecycle
start() resolves to a StartedWiremockContainer: URLs, health, reset
and verification – plus every Testcontainers method, e.g. stop()
and logs().
Start and wait until ready
One container per test file:
beforeAll(async () => {
wiremock = await paymentsApi().start(); // resolves once the port listens…
await wiremock.waitUntilReady(READINESS); // …and this once WireMock answers healthily
}, 120_000);
afterAll(async () => {
await wiremock?.stop(); // `?.`: beforeAll may have failed
});
Source: examples/lifecycle/lifecycle.e2e.test.ts (lines 15–22)
start()resolves once the port listens. It first validates extensions and options; a failed start names the extensions in use.waitUntilReady(options?)polls WireMock's health until it answers, and throws on timeout.- Give
beforeAlla timeout that covers the first image pull.
Tune polling with WaitUntilReadyOptions – defaults: timeout 30 s, interval 250 ms:
/** Poll WireMock's health every 500 ms, for up to a minute – the defaults are 250 ms and 30 s. */
export const READINESS: WaitUntilReadyOptions = { timeout: 60_000, interval: 500 };
Source: examples/lifecycle/lifecycle.ts (lines 9–10)
Build URLs
WireMock listens on a random port – never hard-code it:
it("builds URLs from paths – no string formatting in tests", () => {
expect(wiremock.rpcUrl).toMatch(/^http:\/\/[^/]+:\d+$/u); // e.g. http://localhost:32768
expect(wiremock.getUrl()).toBe(wiremock.rpcUrl);
expect(wiremock.getUrl("/payments")).toBe(`${wiremock.rpcUrl}/payments`);
expect(wiremock.getUrl("payments?page=2")).toBe(`${wiremock.rpcUrl}/payments?page=2`); // "/" added
expect(wiremock.getAdminUrl()).toBe(`${wiremock.rpcUrl}/__admin`);
expect(wiremock.getMappingUrl()).toBe(`${wiremock.rpcUrl}/__admin/mappings`);
});
Source: examples/lifecycle/lifecycle.e2e.test.ts (lines 26–33)
| Member | Returns |
|---|---|
rpcUrl | Base URL, e.g. http://localhost:32768 |
getUrl(path?) | rpcUrl + path – a missing leading / is added |
getAdminUrl() | <rpcUrl>/__admin – the admin API |
getMappingUrl() | <rpcUrl>/__admin/mappings – add stubs at runtime |
Point your app at WireMock
Pass the URL the way production configures it. Helpers that only need URLs take
Pick<StartedWiremockContainer, "getUrl">:
/**
* Points the application under test at WireMock – e.g. the environment of a server a test starts.
* Only `getUrl()` is needed, so unit tests can pass a fake.
*/
export function paymentsEnvironment(wiremock: Pick<StartedWiremockContainer, "getUrl">): Record<string, string> {
return {
PAYMENTS_API_URL: wiremock.getUrl(),
PAYMENTS_WEBHOOK_URL: wiremock.getUrl("/webhooks/payments"),
};
}
Source: examples/lifecycle/lifecycle.ts (lines 14–23)
So unit tests can pass a fake:
it("paymentsEnvironment() needs nothing but getUrl()", () => {
const fake = { getUrl: (path = "") => `http://localhost:8080${path}` };
expect(paymentsEnvironment(fake)).toEqual({
PAYMENTS_API_URL: "http://localhost:8080",
PAYMENTS_WEBHOOK_URL: "http://localhost:8080/webhooks/payments",
});
});
Source: examples/lifecycle/lifecycle.test.ts (lines 12–18)
Check health
isRunning() resolves true while WireMock is healthy, false otherwise. It never throws.
Stop
stop() in afterAll, with ?. in case start-up failed. Testcontainers removes leftovers when
the test process ends.
Stop automatically with await using
Stops the container when the block ends, even if an assertion throws. Needs TypeScript ≥ 5.2 and a runtime or transpiler with explicit resource management (Vitest, Node.js 24).
it("`await using` stops the container when the block ends", async () => {
let stopped: StartedWiremockContainer;
{
await using wiremock = await paymentsApi().start();
await wiremock.waitUntilReady();
expect(await wiremock.isRunning()).toBe(true);
stopped = wiremock;
} // ← wiremock.stop() runs here, even if an assertion failed
expect(await stopped.isRunning()).toBe(false); // never throws
}, 120_000);
Source: examples/lifecycle/lifecycle.e2e.test.ts (lines 47–56)