WireMock gives you two powerful levers for dynamic responses: declarative Handlebars templates embedded in stubs, and imperative Java logic via the response builder APIs. They complement each other rather than compete.<\/p>\n
In real systems, responses rarely stay static: IDs echo from the URL, correlation IDs flow through headers, timestamps change, payloads depend on the request body, and so on. WireMock\u2019s response templating solves this by letting you:<\/p>\n
The design goal is: keep the simple<\/em> cases in configuration, and only push complex<\/em> behaviour into code.<\/p>\n Handlebars lets you embed Some of the most useful fields in the Rationale: this model gives you enough context to \u201cshape\u201d the response purely from the incoming HTTP request, without Java code.<\/p>\n In programmatic (local) mode, WireMock 3+ enables templating support out of the box, but actually applying<\/em> it depends on how your instance is configured:<\/p>\n This is intentional: it prevents accidental template evaluation on basic static stubs, while still allowing an \u201call templates\u201d mode when you know your mapping set depends heavily on it.<\/p>\n Below is a minimal, self-contained Java example using a modern WireMock 3.x style API, focusing only on the stub and response (no build configuration). It echoes data from path, query, and headers via Handlebars.<\/p>\n Why this shape:<\/p>\n Handlebars in WireMock is extended with a large set of helpers for dates, random values, JSON\/XML processing, math, array manipulation, and more. This lets templates stay expressive without turning into full programming languages.<\/p>\n Some particularly pragmatic helpers:<\/p>\n Rationale: you can keep test data generation in the template layer, avoiding brittle fixture code and making mocks self-describing.<\/p>\n While Handlebars owns the declarative side, the Java Response builder<\/strong> APIs give you full programmatic control. Conceptually, you work with:<\/p>\n A typical stub already uses the builder implicitly:<\/p>\n Here the builder is used in its simplest<\/strong> form: static status, headers, and body. The real power shows up when you combine it with extensions.<\/p>\n A common pattern is: start with the stub\u2019s definition, then refine the actual Conceptual example using a Key rationale:<\/p>\n A stub can then provide the template \u201cskeleton\u201d that this transformer fills:<\/p>\n Validation strategy:<\/p>\n This demonstrates the division of responsibilities<\/strong>: the stub defines the shape<\/em>, the transformer plus builder define the behaviour<\/em>.<\/p>\n To tie everything together, here is a minimal Java program that:<\/p>\n Again, no build tooling, only the code that matters for behaviour.<\/p>\n Why this example is structured this way:<\/p>\n In practice, a good rule of thumb is:<\/p>\n A lot of teams settle on a hybrid: templates for the bulk of the response, plus a few narrow custom transformers for cross-cutting concerns (IDs, timestamps, test data injection). That balance usually gives you both readability and power.<\/p>\n","protected":false},"excerpt":{"rendered":" WireMock gives you two powerful levers for dynamic responses: declarative Handlebars templates embedded in stubs, and imperative Java logic via the response builder APIs. They complement each other rather than compete. Why response templating exists In real systems, responses rarely stay static: IDs echo from the URL, correlation IDs flow through headers, timestamps change, payloads […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[76,96],"tags":[],"_links":{"self":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts\/2164"}],"collection":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=2164"}],"version-history":[{"count":1,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts\/2164\/revisions"}],"predecessor-version":[{"id":2166,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts\/2164\/revisions\/2166"}],"wp:attachment":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=2164"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=2164"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=2164"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}
\nHandlebars in WireMock: the declarative layer<\/h2>\n
{{expressions}}<\/code> directly in response headers, bodies, and even proxy URLs. At runtime, WireMock feeds a rich request model<\/strong> into the template engine so the template can \u201csee\u201d all relevant request data.<\/p>\nThe request model<\/h2>\n
request<\/code> model:<\/p>\n\n
request.url<\/code>, request.path<\/code>, request.pathSegments.[n]<\/code> and named path variables (e.g. request.path.customerId<\/code>).<\/li>\nrequest.query.foo<\/code> or request.query.foo.[n]<\/code> for multi-valued params.<\/li>\nrequest.headers.X-Request-Id<\/code>, request.cookies.session<\/code>, request.method<\/code>, request.baseUrl<\/code>.<\/li>\nrequest.body<\/code>, request.bodyAsBase64<\/code>, and multipart request.parts.*<\/code> for more advanced cases.<\/li>\n<\/ul>\nEnabling and scoping templating<\/h2>\n
\n
response-template<\/code> transformer.<\/li>\nBasic Handlebars example<\/h2>\n
import com.github.tomakehurst.wiremock.WireMockServer;\nimport com.github.tomakehurst.wiremock.core.WireMockConfiguration;\n\nimport static com.github.tomakehurst.wiremock.client.WireMock.*;\n\npublic class HandlebarsExample {\n\n public static void main(String[] args) {\n WireMockServer wm = new WireMockServer(\n WireMockConfiguration.options()\n \/\/ Local templating enabled by default in Java mode;\n \/\/ if you\u2019d changed it globally, you can toggle here.\n .templatingEnabled(true)\n );\n wm.start();\n\n configureFor("localhost", wm.port());\n\n wm.stubFor(\n get(urlPathMatching("\/customers\/(.*)"))\n .willReturn(\n aResponse()\n .withStatus(200)\n .withHeader("Content-Type", "application\/json")\n \/\/ Handlebars: use path segment, header, and query param\n .withBody("""\n {\n "id": "{{request.pathSegments.[1]}}",\n "correlationId": "{{request.headers.X-Correlation-Id}}",\n "greeting": "Hello, {{request.query.name}}"\n }\n """)\n \/\/ Ensure the response goes through the template engine:\n .withTransformers("response-template")\n )\n );\n\n \/\/ Simple validation (manual): curl the endpoint:\n \/\/ curl -H "X-Correlation-Id: abc-123" "http:\/\/localhost:8080\/customers\/42?name=Alice"\n \/\/ Response should contain id=42, correlationId=abc-123, greeting "Hello, Alice".\n }\n}<\/code><\/pre>\n\n
\nHandlebars helpers: beyond simple interpolation<\/h2>\n
\n
now<\/code> with format, timezone, and offsets; parseDate<\/code>, truncateDate<\/code> for consistent timestamps.<\/li>\nrandomValue<\/code>, randomInt<\/code>, pickRandom<\/code> for synthetic but realistic data.<\/li>\njsonPath<\/code>, parseJson<\/code>, toJson<\/code>, formatJson<\/code>, jsonArrayAdd<\/code>, jsonMerge<\/code>, jsonRemove<\/code>, jsonSort<\/code> for shaping JSON payloads.<\/li>\nxPath<\/code>, soapXPath<\/code>, formatXml<\/code>.<\/li>\nmath<\/code>, range<\/code>, contains<\/code>, matches<\/code>, numberFormat<\/code>, base64<\/code>, urlEncode<\/code>, formData<\/code>, regexExtract<\/code>, size<\/code>, and more.<\/li>\n<\/ul>\n
\nResponse builders: the imperative layer<\/h2>\n
\n
ResponseDefinitionBuilder<\/code> (via aResponse()<\/code> in stubs) at the configuration level.<\/li>\nResponse<\/code> and its Builder<\/code> when writing extensions like ResponseTransformerV2<\/code>.<\/li>\n<\/ul>\nwm.stubFor(\n get(urlEqualTo("\/hello"))\n .willReturn(\n aResponse()\n .withStatus(200)\n .withHeader("Content-Type", "text\/plain")\n .withBody("Hello from WireMock")\n )\n);<\/code><\/pre>\nCustom transformer with Response.Builder<\/h2>\n
Response<\/code> in a transformer. This is where Response.Builder<\/code> (or the like(response).but()<\/code> style) becomes useful.<\/p>\nResponseTransformerV2<\/code>, which takes the already-resolved Response<\/code> and lets you mutate it:<\/p>\nimport com.github.tomakehurst.wiremock.extension.ResponseTransformerV2;\nimport com.github.tomakehurst.wiremock.http.Request;\nimport com.github.tomakehurst.wiremock.http.Response;\nimport com.github.tomakehurst.wiremock.stubbing.ServeEvent;\n\npublic class UppercaseNameTransformer implements ResponseTransformerV2 {\n\n @Override\n public String getName() {\n return "uppercase-name-transformer";\n }\n\n @Override\n public Response transform(Response response, ServeEvent serveEvent) {\n String originalBody = response.getBodyAsString();\n Request request = serveEvent.getRequest();\n String name = request.queryParameter("name").isPresent()\n ? request.queryParameter("name").firstValue()\n : null;\n\n String effectiveName = (name != null && !name.isBlank())\n ? name.toUpperCase()\n : "UNKNOWN";\n\n String transformedBody = originalBody.replace("{{NAME}}", effectiveName);\n\n return Response.Builder\n .like(response)\n .but()\n .body(transformedBody)\n .build();\n }\n}<\/code><\/pre>\n\n
like(response).but()<\/code> copies status, headers, etc., so you only specify what changes.<\/li>\nwm.stubFor(\n get(urlPathEqualTo("\/greet"))\n .willReturn(\n aResponse()\n .withStatus(200)\n .withHeader("Content-Type", "text\/plain")\n .withBody("Hello, {{NAME}}!") \/\/ Placeholder, not Handlebars here\n .withTransformers("uppercase-name-transformer")\n )\n);<\/code><\/pre>\n\n
\/greet?name=alice<\/code> and assert you get Hello, ALICE!<\/code>.<\/li>\n\/greet<\/code> with no name<\/code> and assert you get Hello, UNKNOWN!<\/code>.<\/li>\n<\/ul>\n
\nExample: combining Handlebars and Response builders<\/h2>\n
\n
Response.Builder<\/code>.<\/li>\n<\/ul>\nimport com.github.tomakehurst.wiremock.WireMockServer;\nimport com.github.tomakehurst.wiremock.core.WireMockConfiguration;\nimport com.github.tomakehurst.wiremock.extension.ResponseTransformerV2;\nimport com.github.tomakehurst.wiremock.http.Request;\nimport com.github.tomakehurst.wiremock.http.Response;\nimport com.github.tomakehurst.wiremock.stubbing.ServeEvent;\n\nimport static com.github.tomakehurst.wiremock.client.WireMock.*;\n\npublic class WireMockTemplatingDemo {\n\n public static void main(String[] args) {\n WireMockServer wm = new WireMockServer(\n WireMockConfiguration.options()\n .port(8080)\n .templatingEnabled(true) \/\/ ensure Handlebars engine is available\n .extensions(new UppercaseNameTransformer())\n );\n wm.start();\n\n configureFor("localhost", 8080);\n\n \/\/ 1) Pure Handlebars-based response.\n wm.stubFor(\n get(urlPathMatching("\/customers\/(.*)"))\n .willReturn(\n aResponse()\n .withStatus(200)\n .withHeader("Content-Type", "application\/json")\n .withBody("""\n {\n "id": "{{request.pathSegments.[1]}}",\n "name": "{{request.query.name}}",\n "requestId": "{{request.headers.X-Request-Id}}"\n }\n """)\n .withTransformers("response-template")\n )\n );\n\n \/\/ 2) Response builder + custom transformer.\n wm.stubFor(\n get(urlPathEqualTo("\/welcome"))\n .willReturn(\n aResponse()\n .withStatus(200)\n .withHeader("Content-Type", "text\/plain")\n \/\/ Placeholder token; the transformer will replace it.\n .withBody("Welcome, {{NAME}}!")\n .withTransformers("uppercase-name-transformer")\n )\n );\n\n System.out.println("WireMock started on http:\/\/localhost:8080");\n\n \/\/ Manual validation:\n \/\/ 1) Handlebars endpoint:\n \/\/ curl -H "X-Request-Id: req-123" "http:\/\/localhost:8080\/customers\/42?name=Alice"\n \/\/ -> JSON with id=42, name=Alice, requestId=req-123\n \/\/\n \/\/ 2) Transformer + Response.Builder endpoint:\n \/\/ curl "http:\/\/localhost:8080\/welcome?name=alice"\n \/\/ -> "Welcome, ALICE!"\n \/\/ curl "http:\/\/localhost:8080\/welcome"\n \/\/ -> "Welcome, UNKNOWN!"\n }\n\n \/\/ Custom transformer using Response.Builder\n public static class UppercaseNameTransformer implements ResponseTransformerV2 {\n\n @Override\n public String getName() {\n return "uppercase-name-transformer";\n }\n\n @Override\n public Response transform(Response response, ServeEvent serveEvent) {\n String body = response.getBodyAsString();\n Request request = serveEvent.getRequest();\n String name = request.queryParameter("name").isPresent()\n ? request.queryParameter("name").firstValue()\n : null;\n\n String effectiveName = (name != null && !name.isBlank())\n ? name.toUpperCase()\n : "UNKNOWN";\n\n String newBody = body.replace("{{NAME}}", effectiveName);\n\n return Response.Builder\n .like(response)\n .but()\n .body(newBody)\n .build();\n }\n }\n}<\/code><\/pre>\n\n
\nWhen to prefer which approach<\/h2>\n
\n