Skip to main content

Configuring the container

Pin the image​

new WiremockContainer(image?) defaults to wiremock/wiremock:latest. Pin a tag:

examples/container/container.ts
/** Pin the image – the default, `wiremock/wiremock`, floats with every WireMock release. */
export const WIREMOCK_IMAGE = "wiremock/wiremock:3.13.2";

Source: examples/container/container.ts (lines 10–11)

Custom images must keep the official layout: /home/wiremock/mappings, /home/wiremock/__files, /var/wiremock/extensions, port 8080.

Pass WireMock options​

withCommand(args) takes WireMock's command-line options, one per entry. Any GenericContainer method works too:

examples/container/container.ts
return new WiremockContainer(WIREMOCK_IMAGE)
.withCommand(["--global-response-templating", "--max-request-journal=1000"]) // WireMock CLI options
.withEnvironment({ JAVA_OPTS: "-Xmx256m" }) // options for WireMock's JVM
.withLabels({ "com.example.suite": "payments" }) // any GenericContainer method…
.withStartupTimeout(120_000) // …e.g. to wait longer for a slow machine
.withMapping("greeting", { json: GREETING_STUB });

Source: examples/container/container.ts (lines 23–28)

examples/container/container.e2e.test.ts
it("templates every response: --global-response-templating is on", async () => {
const response = await fetch(wiremock.getUrl("/greeting?name=Ada"));
expect(await response.text()).toBe("Hello, Ada!");
});

Source: examples/container/container.e2e.test.ts (lines 26–29)

Pass options through the environment​

The image also reads WIREMOCK_OPTIONS:

examples/container/container.ts
return new WiremockContainer(WIREMOCK_IMAGE)
.withEnvironment({ WIREMOCK_OPTIONS: "--global-response-templating" })
.withMapping("greeting", { json: GREETING_STUB });

Source: examples/container/container.ts (lines 35–37)

Use Testcontainers builder methods​

MethodUse
withEnvironment({ JAVA_OPTS })JVM options, e.g. a heap limit
withStartupTimeout(ms)Wait longer for the port
withLabels()Find the container in docker ps – prefer it to withName(), which clashes between parallel test files
withNetwork(), withNetworkAliases()Reach WireMock from other containers
withCopyFilesToContainer()Copy files the library does not manage, e.g. an extension JAR

All of them: Testcontainers' docs.

Avoid conflicting options​

WireMock refuses options given twice, so start() rejects – before starting anything – an option that extensions set with a different value, and --extensions (use withExtension()):

examples/container/container.test.ts
it("an option set twice with different values fails start() – WireMock would crash", async () => {
const journal = { getName: () => "journal", getOptions: () => ["--max-request-journal=5"] };
const container = new WiremockContainer().withCommand(["--max-request-journal=1000"]).withExtension(journal);
await expect(container.start()).rejects.toThrow(
'option "--max-request-journal=5" conflicts with "--max-request-journal=1000" set by withCommand() or WIREMOCK_OPTIONS',
);
});

it("--extensions belongs to withExtension(), not withCommand()", async () => {
const container = new WiremockContainer()
.withCommand(["--extensions", "com.example.Other"])
.withExtension("com.github.tomakehurst.wiremock.extension.responsetemplating.ResponseTemplateTransformer");
await expect(container.start()).rejects.toThrow('"--extensions" is already set by withCommand() or WIREMOCK_OPTIONS');
});

Source: examples/container/container.test.ts (lines 23–36)