Skip to content

Templating

Response headers and bodies, bodyFileName, SSE events, callbacks, Kafka messages and scenario names are Handlebars templates. Templates can read the request and call helpers; they cannot read files, environment variables or the network, cannot run code, and every render is bounded in size.

Set "templated": false on a response to send {{ literally.

The template context

Path Value
request.method GET, POST, ...
request.url Path and query string as sent: /search?q=a%20b
request.path Percent-decoded path: /users/7
request.pathSegments.[0] Path segments: users
request.pathParams.id Parameters of urlPathTemplate
request.query.q First value of a query parameter
request.queryAll.id.[1] All values of a query parameter
request.headers.x-request-id First value of a header; names are lower-case (request.headers.[content-type])
request.headersAll.[x-multi].[1] All values of a header (lower-case names), for #each, size, join
request.cookies.session First value of a cookie
request.formParams.user First value of a form field (application/x-www-form-urlencoded bodies only)
request.body Body as text
request.json.items.[0].sku Body parsed as JSON (up to 200,000 nodes; null otherwise)
request.scheme, request.host, request.port https, api.example.com, 8443 (port defaults to 80/443 by scheme)
request.baseUrl https://api.example.com:8443
state.scenario, state.current Rendered scenario name and its state before this request (stubs with a scenario)
originalRequest The same object as request (WireMock webhook compatibility); added only to stubs that use it
{
  "request": {"method": "POST", "urlPathTemplate": "/carts/{cartId}/items"},
  "response": {
    "status": 201,
    "headers": {"location": "{{request.baseUrl}}/carts/{{request.pathParams.cartId}}/items/{{uuid}}"},
    "jsonBody": {
      "cart": "{{request.pathParams.cartId}}",
      "sku": "{{request.json.sku}}",
      "quantity": "{{json request.json.quantity}}",
      "client": "{{default request.headers.x-client 'unknown'}}"
    }
  }
}

Typed JSON values

In jsonBody (and callback and Kafka jsonBody/jsonValue) every string is rendered as text. A string that is exactly "{{json <expression>}}" keeps the JSON type of the value: numbers stay numbers, objects stay objects.

{"jsonBody": {"count": "{{json request.json.count}}", "items": "{{json request.json.items}}", "label": "{{request.json.count}}"}}

With the body {"count": 3, "items": [1, 2]} this renders {"count": 3, "items": [1, 2], "label": "3"}.

Conditions and loops

The Handlebars built-ins if, unless, each, with, lookup and len are available. The comparison helpers below work both as sub-expressions and as blocks:

{{#if (eq request.query.lang 'uk')}}Привіт{{else}}Hello{{/if}}
{{#eq request.method 'POST'}}created{{else}}read{{/eq}}
{{#each request.queryAll.id}}{{this}}{{#unless @last}},{{/unless}}{{/each}}
{{#contains request.headers.accept 'xml'}}<ok/>{{else}}{"ok": true}{{/contains}}

Partials ({{> name}}) and decorators ({{#* inline}}) are rejected.

Helper reference

Arguments are positional unless shown as name=value. Strings are quoted with ' or "; there are no escape sequences inside literals, so put text with backslashes or line breaks into the request or into a body file.

Request data

Helper Example Result
jsonPath value path {{jsonPath request.body '$.items[0].sku'}} First JSONPath result; value may be a JSON string. Objects and arrays render as JSON text ({"k":1}), as in WireMock; inside #each or a sub-expression they stay JSON values
xPath xml path {{xPath request.body '/order/id'}} Text of the selected node; an array when several match, null when none
formData text [var] urlDecode=true {{formData request.body 'form' urlDecode=true}}{{form.user}} Parses a=1&b=2; with a variable name the object is stored in that variable, otherwise it is returned: {{lookup (formData request.body) 'user'}}
val value default=x / or=x {{val request.query.page default='1'}} The value, or the default when it is missing (null)
default value fallback {{default request.query.page '1'}} The fallback when the value is missing or an empty string
size value {{size request.queryAll.id}} Length of a string (characters), array or object

formData cannot overwrite request, originalRequest or state; variable names are [A-Za-z0-9_], at most 64 characters.

Strings

Helper Example Result
upper / lower {{upper 'abc'}} ABC
capitalize s [fully=true] {{capitalize 'hello wORLD'}} / fully=true Hello WORLD / Hello World
capitalizeFirst s {{capitalizeFirst 'abc def'}} Abc def
trim s {{trim ' a b '}} a b
abbreviate s width {{abbreviate 'Hello world' 8}} Hello... (width at least 4)
replace s from to {{replace 'a-b-c' '-' '+'}} a+b+c
concat a b ... {{concat 'order-' request.pathParams.id}} order-7
substring s start [end] {{substring '380501234567' 0 3}} 380 (character positions)
split s separator {{#each (split 'a,b,c' ',')}}[{{this}}]{{/each}} [a][b][c]
join separator array / join separator a b ... {{join ', ' (array 'a' 'b') prefix='[' suffix=']'}} [a, b]
regexExtract s regex [group] {{regexExtract request.path '/users/([0-9]+)' 1}} 7
urlEncode s [decode=true] {{urlEncode 'a b&c'}} / {{urlEncode 'a+b%26c' decode=true}} a+b%26c / a b&c
base64 s [decode=true] [padding=false] {{base64 'hi'}} / {{base64 'aGk=' decode=true}} aGk= / hi
base64Decode s {{base64Decode 'aGk='}} hi
sha256 s {{sha256 request.body}} hex digest
hmac algorithm key data [encoding='base64'] {{hmac 'sha256' 'key' request.body}} hex (or base64) HMAC; sha256 or sha512

Comparisons and logic

All return true/false and can be used as blocks ({{#eq a b}}...{{else}}...{{/eq}}).

Helper Example Notes
eq a b, ne a b {{#if (eq request.method 'GET')}} Values that both look like numbers compare as numbers ('10' equals 10.0); otherwise as text
gt, gte, lt, lte {{#if (gt request.json.amount 1000)}} Numeric when both are numbers or numeric strings, else text order
and a b ..., or a b ..., not a {{#if (and (eq a 1) (not b))}} Falsy: null, false, 0, empty string, empty array
contains haystack needle {{#if (contains request.headers.accept 'json')}} Substring of a string, element of an array, or key of an object
matches s regex {{#matches request.query.id '[0-9]+'}}num{{/matches}} Anchored regular expression

Numbers and random values

Helper Example Result
math a op b {{math request.json.qty '*' 2}} + - * / %, // (integer division), ^ or pow, min, max; division by zero is an error
randomInt lower upper {{randomInt 1 6}} or {{randomInt lower=1 upper=6}} Integer, both bounds inclusive
randomDecimal lower=x upper=y {{randomDecimal lower=0.5 upper=2.5}} Float in [lower, upper)
randomDigits n {{randomDigits 6}} 048213 (at most 256 digits)
randomValue length=n type=T [uppercase=true] {{randomValue length=12 type='HEXADECIMAL' uppercase=true}} Types ALPHANUMERIC (default), ALPHABETIC, NUMERIC, HEXADECIMAL, ALPHANUMERIC_AND_SYMBOLS, UUID; length at most 4096 (default 36)
uuid {{uuid}} Random UUID v4
pickRandom a b c / pickRandom array {{pickRandom 'red' 'green'}} One of the values
array a b ... {{array 1 'two' true}} A JSON array, for join, each, jsonArrayAdd, ...

Dates and times

Dates are passed between helpers as ISO-8601 strings. format accepts iso (default, milliseconds, UTC Z), isoSeconds (no fraction of a second, as WireMock's default), isoNanos, epoch or unix (seconds, a number), epochMillis (a number), a Java pattern such as yyyy-MM-dd'T'HH:mm:ss (y M d D H h k m s S E a Z X x z w e c, text in '...'), or a strftime pattern containing % such as %d.%m.%Y. offset is <amount> <unit> (3 days, -24 seconds, 1 months; units as in date-time matchers). timezone is UTC, GMT, Z or a fixed offset (+02:00, -0530, UTC+3); region names such as Europe/Kyiv are not supported because their rules change over time.

Helper Example Result
now [offset=] [offsetSeconds=] [format=] [timezone=] {{now offset='1 days' format='yyyy-MM-dd'}} Tomorrow's date
date value [offset=] [format=] [timezone=] {{date request.json.created offset='-1 hours' timezone='+02:00' format='HH:mm'}} Shifted and formatted; value is an ISO string or epoch seconds (milliseconds when larger than 10^11)
parseDate text [format=] {{parseDate '10/11/2021' format='dd/MM/yyyy'}} 2021-11-10T00:00:00.000Z; null when it does not parse
dateFormat value [format] {{dateFormat (parseDate request.query.d) 'long'}} Named styles full, long, medium, short, or any format above
{{date (parseDate request.headers.[if-modified-since]) offset='1 days' format='EEE, dd MMM yyyy HH:mm:ss' }} GMT

JSON and XML

The JSON helpers accept JSON values or JSON text and return compact JSON text, so they nest: {{jsonPath (jsonMerge a b) '$.x'}}. In a jsonBody, use "{{json (parseJson (jsonMerge a b))}}" to insert the result as an object.

Helper Example Result
toJson value {{toJson request.json.items}} JSON text
parseJson text {{json (parseJson request.query.filter)}} JSON value (null when invalid)
jsonMerge a b [removeNulls=true] {{jsonMerge '{"a":1,"b":{"c":2}}' '{"b":{"d":3}}'}} {"a":1,"b":{"c":2,"d":3}} (deep merge of objects; removeNulls drops keys whose value is null)
jsonRemove json path {{jsonRemove request.body '$.password'}} The document without the JSONPath matches
jsonArrayAdd array item [flatten=true] [maxItems=n] {{jsonArrayAdd '[1,2]' '[3,4]' flatten=true maxItems=3}} [2,3,4] (maxItems keeps the last n)
formatJson json [format='compact'] {{formatJson request.body}} Pretty-printed (two spaces) or compact
formatXml xml [format='compact'] {{formatXml request.body}} Pretty-printed (two spaces) or compact XML; no DTDs

Fake data

Postman/Microcks-style generators for realistic test data. Without seed every call is random; with seed=<any value> the result is the same every time for that seed (and differs between helpers), which makes responses reproducible: {{randomFullName seed=request.pathParams.id}} always gives the same name for the same id.

Helper Example result
randomFirstName, randomLastName, randomFullName Olivia, Garcia, Liam Walker
randomUserName olivia512
randomEmail liam.walker@example.org
randomPhoneNumber +1-415-555-0172
randomCity, randomCountry, randomCountryCode Riverside, Poland, PL
randomStreetAddress 742 Maple Avenue
randomCompanyName, randomJobTitle Globex Labs, Architect
randomWord, randomColor tango, teal
randomBoolean true
randomAlphaNumeric [length=10] aZ3k9QpL0x
randomIP, randomIPv6 83.14.201.7, 2a1:9f:...
randomUUID 5b1c... (UUID v4 layout)
randomUrl https://example.com/delta
randomDateTime [days=365] 2026-03-02T11:20:45Z (within ±days of now)

Email and URL domains are always example.com, example.org or example.net.

{
  "request": {"method": "GET", "urlPathTemplate": "/customers/{id}"},
  "response": {
    "jsonBody": {
      "id": "{{request.pathParams.id}}",
      "name": "{{randomFullName seed=request.pathParams.id}}",
      "email": "{{randomEmail seed=request.pathParams.id}}",
      "address": {"street": "{{randomStreetAddress seed=request.pathParams.id}}", "city": "{{randomCity seed=request.pathParams.id}}"},
      "active": "{{json (randomBoolean)}}"
    }
  }
}

Limits and errors

Limit Value
Template size 256 KiB
Rendered output 8 MiB
Values produced by helpers during one render 32 MiB (each helper result, each JSON text parsed by a helper and each formData variable counts; sizes are checked before a result is built)
Request JSON parsed for request.json 200,000 nodes
JSON text parsed by jsonPath, parseJson, formatJson, jsonMerge, jsonRemove, jsonArrayAdd 200,000 nodes, 128 levels; larger text is treated as a plain string (parseJson returns null)
Steps per render (helper calls, #each iterations, output writes) 1,000,000
Render time 2 seconds
Nesting of blocks / subexpressions 64 / 32 levels (checked when the stub is saved)
Text returned by one xPath call 2 MiB in total over all results
Generated lengths (randomValue, randomAlphaNumeric) 4096 characters
Items produced by split, formData, jsonArrayAdd 10,000
Regular expressions in regexExtract and matches 1 MiB compiled
formatXml input 100,000 nodes, 256 levels

Templates are checked when the stub is saved (syntax, size, no partials). Errors that depend on the request (an invalid date, a bad regular expression in a request value, an exceeded budget, step limit or render time) answer 500 {"error": "stub evaluation failed"} and are counted in fastmock_stub_errors_total; the server log has the message under the request's trace id.