Skip to main content

Java extensions

Load compiled WireMock extensions – transformers, matchers, admin routes – from JARs. No JDK needed.

MethodRegisters
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​

examples/extensions/java-extensions.e2e.test.ts
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:

examples/extensions/java-extensions.e2e.test.ts
/** 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:

examples/extensions/java-extensions.e2e.test.ts
/** 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​

examples/extensions/java-extensions.e2e.test.ts
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:

examples/extensions/java-extensions.e2e.test.ts
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:

OptionDefaultfalse
scanningtrueIgnore META-INF/services: only named classes load
verifyClassNamestrueSkip the start-up check that each class is in a registered JAR – for classes a custom image provides
examples/extensions/java-extensions.e2e.test.ts
/** 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)

examples/extensions/java-extensions.e2e.test.ts
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:
examples/extensions/extensions.test.ts
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 --extensions or repeat an extension's option.
  • JARs target Java 11 (WireMock 3's runtime). Custom images keep /var/wiremock/extensions.

Start-up failures: troubleshooting.