In WireMock, how do you build a stubbed reply out of the request that triggered it?

## The request model a template can see The point of response templating is that the reply is computed from the call rather than frozen when the stub was written. Once WireMock's `response-template` transformer is attached to a response, the Handlebars context handed to that body contains a `request` object describing the call currently being answered. For a snowplough dispatch API this is what lets one mapping serve `POST /dispatch/v1/assignments` for every depot and every route, echoing back the route the caller actually asked about instead of a hard-coded one. The parts of WireMock's `request` model you reach for most: - `{{request.path}}` — WireMock renders the path of the call, without the query string. - `{{request.url}}` — WireMock renders path and query string exactly as they arrived. - `{{request.method}}` — WireMock renders the HTTP method of the call. - `{{request.query.depot}}` — WireMock renders one named query-string parameter's value. - `{{request.headers.Accept}}` — WireMock renders one named request header's value. - `{{request.body}}` — WireMock renders the request payload, as raw text. That last entry is the one that trips people. WireMock hands the payload over as a string, not as a parsed object, so `{{request.body.routeId}}` does not reach a JSON field. Getting at a field is a helper's job. ## Pulling one field out of a JSON payload WireMock's `jsonPath` helper takes a source and a JSONPath expression, and the source is normally the raw body: ``` {{jsonPath request.body '$.routeId'}} ``` Written into a reply for the snowplough dispatch API, that turns a request of `{"routeId": "R-114", "ploughId": "P-7"}` into a confirmation quoting `R-114` back. The same helper reaches nested fields (`'$.crew.leadOperator'`) and array positions (`'$.passes[0].laneKm'`), so a stub can build a plausible confirmation document out of whatever the client submitted rather than a fixed one. Two properties of the helper are worth internalising: 1. It reads a **source expression**, not a literal string. WireMock treats `request.body` as the source and the quoted JSONPath as the expression evaluated against it. 2. A template problem does not fail the request. WireMock still answers with the status the stub declared; the damage appears in the body, which is why a stub that "returns 201 correctly" can still be wrong. ## Values that are not in the request Some of what a reply needs is neither literal nor derived from the caller — an environment name, a depot code, a base URL. WireMock lets you attach these to the stub itself: - WireMock's `withTransformerParameter("centre", "north")` on the response definition, read in the body as `{{parameters.centre}}`. - The same thing in a WireMock JSON mapping, as a `transformerParameters` object inside the response. This keeps one mapping reusable across environments without turning the body into string concatenation in the test code, and it keeps the varying part visible in the mapping rather than hidden in a Java helper method. ## What this buys, and what it costs | Approach | Reply agrees with the request | Where the reply's shape is visible | |---|---|---| | Literal body per case | only for the exact case you wrote | in the mapping, one file per case | | Templated body reading `request` | for every case the pattern matches | in the mapping, one file for all of them | | Body assembled in test code before stubbing | only for values known before the call | in the test, not in the mapping | The middle row is why templating exists, but it is not free: - A templated reply is harder to read than a literal one, and a mistake in it produces a plausible-looking wrong payload rather than an obvious failure. - A reply that echoes the request cannot contradict the client, so a test asserting "the service returned my route id" proves nothing about the real upstream. - Rendering is work per request, and a body with many helper calls is slower than a fixed payload — usually irrelevant in a test, occasionally relevant on a busy shared instance. The rule of thumb is to template the parts of a reply that genuinely must correlate with the call — identifiers, echoed paths, timestamps — and to leave the rest literal so the mapping still reads like an example of the real payload. ## Getting it right the first time 1. Attach the transformer before anything else. Without WireMock's `response-template` on that response, every expression below is inert text. 2. Decide where each value comes from: the path, the query string, the payload, or a transformer parameter. Mixing these up is the commonest cause of a blank field. 3. Reach into a JSON payload with WireMock's `{{jsonPath request.body '...'}}`, never by dotting into `request.body`. 4. Read the rendered reply once, by hand, against a real request. A field that renders empty looks exactly like a field the upstream genuinely omits.