Skip to main content

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:

examples/lifecycle/lifecycle.e2e.test.ts
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 beforeAll a timeout that covers the first image pull.

Tune polling with WaitUntilReadyOptions – defaults: timeout 30 s, interval 250 ms:

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

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

MemberReturns
rpcUrlBase 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">:

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

examples/lifecycle/lifecycle.test.ts
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).

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