Configuring the container
Pin the image
new WiremockContainer(image?) defaults to wiremock/wiremock:latest. Pin a tag:
/** 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:
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)
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:
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
| Method | Use |
|---|---|
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()):
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');
});