Skip to main content

TypeScript extensions

Register one object instead of JAR paths, class names and options – with typed helpers for the stubs that use it. It only configures the container; nothing runs in Node.js.

Implement the contract​

WireMockExtension: getName() plus at least one other member.

MemberRequiredWireMock gets
getName()YesNothing – it identifies the extension; the same name twice must be configured alike
getClassNames()One of theseClass names, merged into one --extensions
getJars()″JARs or directories – any file source
getOptions()″Options, one per entry: "--flag" or "--option=value"

The smallest extension:

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)

Classes: authoring extensions.

Register extensions​

withExtension() takes an ExtensionInput: a class name, an extension object, or an ExtensionConstructor – a class with a no-argument constructor, instantiated for you. withExtensions() takes several, all or nothing.

examples/extensions/registry.ts
/** Extension classes with a no-argument constructor: `withExtensions()` instantiates them. */
export const EXTENSION_CLASSES: readonly ExtensionConstructor[] = [
UppercaseTransformer,
BodyLengthMatcher,
StubCountAdminApi,
PoweredByTransformer,
];

Source: examples/extensions/registry.ts (lines 14–20)

examples/extensions/registry.ts
/** Classes, configured instances and Java class names mix freely: each is an `ExtensionInput`. */
export const PAYMENTS_EXTENSIONS: readonly ExtensionInput[] = [
...EXTENSION_CLASSES,
new GlobalResponseTemplating({ maxCacheEntries: 100 }),
];

Source: examples/extensions/registry.ts (lines 24–28)

examples/extensions/extensions.e2e.test.ts
wiremock = await new WiremockContainer()
// Classes are instantiated for you; the JAR they share is copied once.
.withExtensions(EXTENSION_CLASSES) // [UppercaseTransformer, BodyLengthMatcher, StubCountAdminApi, PoweredByTransformer]
// An instance carries configuration.
.withExtension(new GlobalResponseTemplating({ maxCacheEntries: 100 }))
.withMapping("payments-extended", { json: { mappings: PAYMENT_STUBS } })
.start();

Source: examples/extensions/extensions.e2e.test.ts (lines 53–59)

JARs are validated on registration, class names on start().

Use typed stub helpers​

A response transformer:

examples/extensions/extensions.e2e.test.ts
{
request: { method: "GET", url: "/payments/status" },
response: { status: 200, body: "all systems go", ...UppercaseTransformer.transform({ suffix: "!" }) },
},

Source: examples/extensions/extensions.e2e.test.ts (lines 22–25)

A request matcher:

examples/extensions/extensions.e2e.test.ts
{
request: { method: "POST", url: "/payments/notes", ...BodyLengthMatcher.longerThan(20) },
response: { status: 413, jsonBody: { error: "note too long" } },
},

Source: examples/extensions/extensions.e2e.test.ts (lines 32–35)

Assert with the extension's constants:

examples/extensions/extensions.e2e.test.ts
it("UppercaseTransformer upper-cases bodies, with and without a suffix", async () => {
const status = await fetch(wiremock.getUrl("/payments/status"));
expect(status.headers.get(UppercaseTransformer.HEADER)).toBe(UppercaseTransformer.NAME);
expect(await status.text()).toBe("ALL SYSTEMS GO!");
expect(await (await fetch(wiremock.getUrl("/payments/motto"))).text()).toBe("PAY ON TIME");
});

Source: examples/extensions/extensions.e2e.test.ts (lines 75–80)

Call an admin route through its client:

examples/extensions/extensions.e2e.test.ts
it("StubCountAdminApi adds an admin route, called through its typed client", async () => {
expect(await StubCountAdminApi.count(wiremock)).toBe(PAYMENT_STUBS.length);
});

Source: examples/extensions/extensions.e2e.test.ts (lines 91–93)