Java extensions
Load compiled WireMock extensions – transformers, matchers, admin routes – from JARs. No JDK needed.
| Method | Registers |
|---|---|
withExtensionJar(jar), withExtensionJars([...]) | A JAR, or every *.jar of a directory – any file source |
withExtension(ext), withExtensions([...]) | A fully qualified class name – or a TypeScript extension |
withExtensionOptions({ scanning, verifyClassNames }) | How extensions load |
Load a JAR and name its classes
wiremock = await new WiremockContainer()
.withExtensionJar("./__mocks__/extensions/example-extensions.jar") // onto WireMock's class path
.withExtension("com.hellaweb3.wiremock.extensions.UppercaseTransformer") // --extensions <class>
.withExtension(shortJournal)
.withMapping("shout", SHOUT) // the stub opts in: transformers: ["uppercase"]
.start();
Source: examples/extensions/java-extensions.e2e.test.ts (lines 34–39)
Class names share one --extensions option, in registration order. Stubs opt in by the
extension's name:
/** The stub opts in to the transformer by its WireMock name. */
const SHOUT = { json: { request: { url: "/shout" }, response: { body: "hey", transformers: ["uppercase"] } } };
Source: examples/extensions/java-extensions.e2e.test.ts (lines 17–18)
An extension that only sets WireMock options – no Java – is an object:
/** A one-off extension as an object literal: the journal keeps only the 2 newest requests. */
const shortJournal: WireMockExtension = {
getName: () => "short-journal",
getOptions: () => ["--max-request-journal=2"],
};
Source: examples/extensions/java-extensions.e2e.test.ts (lines 22–26)
Load every JAR of a directory
wiremock = await new WiremockContainer()
.withExtensionJars(["./__mocks__/extensions"]) // example-extensions.jar and powered-by-extension.jar
.withExtension("com.hellaweb3.wiremock.extensions.UppercaseTransformer")
.withMapping("shout", SHOUT)
.start();
Source: examples/extensions/java-extensions.e2e.test.ts (lines 67–71)
Rely on extension scanning
Classes a JAR lists in META-INF/services/com.github.tomakehurst.wiremock.extension.Extension
load without a class name:
it("loads classes by name, and scans JARs for the ones they declare in META-INF/services", async () => {
const response = await fetch(wiremock.getUrl("/shout"));
expect(await response.text()).toBe("HEY"); // UppercaseTransformer: named with withExtension()
expect(response.headers.get("X-Powered-By")).toBe("wiremock-extensions"); // PoweredByTransformer: scanned
});
Source: examples/extensions/java-extensions.e2e.test.ts (lines 81–85)
Control how extensions load
withExtensionOptions() takes WiremockExtensionOptions:
| Option | Default | false |
|---|---|---|
scanning | true | Ignore META-INF/services: only named classes load |
verifyClassNames | true | Skip the start-up check that each class is in a registered JAR – for classes a custom image provides |
/** Load only the classes named with withExtension(); skip the check for JARs copied by other means. */
const options: WiremockExtensionOptions = { scanning: false, verifyClassNames: false };
Source: examples/extensions/java-extensions.e2e.test.ts (lines 93–94)
wiremock = await new WiremockContainer()
.withExtensionJar("./__mocks__/extensions/powered-by-extension.jar") // not scanned: its transformer stays off
// A JAR the library does not know about – like one baked into a custom image:
.withCopyFilesToContainer([
{ source: "./__mocks__/extensions/example-extensions.jar", target: "/var/wiremock/extensions/acme.jar" },
])
.withExtension("com.hellaweb3.wiremock.extensions.UppercaseTransformer") // unverifiable: in no registered JAR
.withExtensionOptions(options)
.withMapping("shout", SHOUT)
.start();
Source: examples/extensions/java-extensions.e2e.test.ts (lines 99–108)
Validation rules
Checked before anything starts:
- JARs exist and end in
.jar; names are unique – rename with{ file, name: "other.jar" }. - Class names are fully qualified:
com.acme.MyTransformer. - On
start(), each class is in a registered JAR or WireMock itself:
it("a class in none of the registered JARs fails start() with a suggestion", async () => {
const typo = new WiremockContainer().withExtensionJar(JARS.examples).withExtension("com.acme.UppercaseTransformer");
await expect(typo.start()).rejects.toThrow(`did you mean "${JAVA_PACKAGE}.UppercaseTransformer"?`);
});
Source: examples/extensions/extensions.test.ts (lines 200–203)
withCommand()does not set--extensionsor repeat an extension's option.- JARs target Java 11 (WireMock 3's runtime). Custom images keep
/var/wiremock/extensions.
Start-up failures: troubleshooting.