Response templating
Handlebars Helpers
This document details the various integrations that are added to WireMock’s custom Handlebars helpers.
Validation of Handlebars helpers
Performs validation on custom Handlebars helpers provided by WireMock. Currently, it performs the following checks:
- Minimum and maximum number of parameters in simple mustaches, sub-expressions and block helpers.
- The inspection messages either show the required number of parameters, or when possible, the combined descriptions of mandatory parameters.
- Whether a hash name is supported by the given helper, or if there is any hash supported by a helper at all.
- Quick fix: to remove the unsupported hash, or all hashes, respectively.
- Incorrect hash values.
- Redundant default hash values. Quick fix: to remove the hash.
- Undefined mandatory hashes. Quick fix: to add missing mandatory hashes.
- Whether a helper is supposed to be used as a block helper.
These rules are based both on WireMock’s Response Templating documentation and on the actual implementations of those helpers.
Helper | # of params | # of params in block (no value means same as in non-blocks) | Hashes | Can be block helper? |
---|---|---|---|---|
xPath | 2 | – | – | |
soapXPath | 2 | – | – | |
jsonPath | 2 | default | – | |
randomValue | 0 | type – default value: ‘ALPHANUMERIC’ length – default value: 36 uppercase – default value: false | – | |
hostname | 0 | – | – | |
date | 1 | offset, timezone, format | – | |
now | 0 | offset, timezone, format | – | |
parseDate | 1 | format – code completed values: ‘epoch’, ‘unix’ | – | |
truncateDate | 2 | – | – | |
trim | 1 | 0 | – | Yes |
base64 | 1 | 0 | decode, padding | Yes |
urlEncode | 1 | 0 | decode encoding – default value: ‘utf-8’ | Yes |
formData | 1-2 | urlDecode encoding – default value: ‘utf-8’ | – | |
regexExtract | 2-3 | default | – | |
size | 1 | – | – | |
pickRandom | 1-INF | – | – | |
randomInt | 0 | lower, upper | – | |
randomDecimal | 0 | lower, upper | – | |
range | 2 | – | – | |
array | 0-INF | – | – | |
parseJson | 1-2 | 0-1 | – | Yes |
matches | 2 | – | Yes | |
contains | 2 | – | Yes | |
math | 3 | – | – | |
systemValue | 0 | type – default value: ‘ENVIRONMENT’, – allowed values: ‘ENVIRONMENT’, ‘PROPERTY’ key – non-empty string | – | |
random | 1 | – | – | |
state | 0 | context – non-empty string list property – allowed values: ‘updateCount’, ‘listSize’, ‘list’ | – |
Other extra validations:
pickRandom
is reported when only a single item is specifiedmath
: unsupported operations are reportedtruncateDate
: unsupported date-time truncation values are reportedrandom
(for the wiremock-faker-extension): the faker expression is reported when the value is wrapped in#{
and}
. It is superfluous because the wrapping is done by theRandomHelper
behind the scenes.state
(for the wiremock-state-extension) reports:- empty
context
hash value - if both
property
andlist
hashes are specified - if neither
property
norlist
hash is specified
- empty
Notes on the table above:
- The number of params include the so-called
context
parameter too. - Hash names in italics are optional ones, while hashes in bold are mandatory ones.
- Separate handling of param count for block helpers is necessary, since in that case the context is not defined as the first parameter of the mustache, instead as the body of the block helper.
Other resources:
- WireMockHelpers.java on GitHub
Navigation to the implementations of helpers
With this functionality, users are able to navigate to the implementations of WireMock’s custom Handlebars helpers via Ctrl+Click and similar actions. References are provided for helper name elements, and resolve
- either to
com.github.tomakehurst.wiremock.extension.responsetemplating.helpers.SystemValueHelper
- or to enum constants of
com.github.tomakehurst.wiremock.extension.responsetemplating.helpers.WireMockHelpers
org.wiremock.extensions.state.extensions.StateHandlerbarHelper
in case of the wiremock-state-extension
This differentiation for the built-in classes is needed because there is no enum constant in WireMockHelpers
for SystemValueHelper
.
This also makes it possible that, if you search for the usages of e.g. WireMockHelpers#jsonPath
, all its usages in WireMock mapping files are returned too.
Notes:
- All helpers, listed in the previous section, are supported.
{{
(simple mustache),{{#
(block helper),{{{
(HTML escaping),{{{{
(raw block) are all supported.- Subexpressions are currently not supported.
Navigation to the implementation of date-time truncations
With this reference implementation users can navigate to the date-time truncation enum constants in com.github.tomakehurst.wiremock.common.DateTimeTruncation
from the truncation parameter of the truncateDate
Handlebars helper.
Code completion
Built-in helpers
Code completion is available for WireMock’s custom Handlebars helpers:
- helper names
- hash names of helpers that support hashes
- certain hashes are also configured to be completed only if the correct version of WireMock is available
- string literal hash values where a list of applicable values can be determined
- request attributes based on the WireMock request model, and data from the original request in webhooks and callbacks.
- date-time truncation values in the truncation parameter of the
truncateDate
helper
Helper name items also include short descriptions of them about their purposes:
When a block helper {{#
is code completed, only helpers that can be used as block helpers are suggested.
Hash names include the fact if they are mandatory or optional:
Hash value items doesn’t have additional contextual information:
Request attributes:
Response attributes as per the wiremock-state-extension:
NOTE: Completion of non-string literal hash values and simple parameters are not supported at the moment.
‘random’ helper from the wiremock-faker-extension
WireMock provides a random
helper via its wiremock-faker-extension that can generate random data using the Data Faker library.
In order to make the discovery of data faker providers easier, this feature provides code completion for
- provider names in the Base group
- names of most data types in the Base, Food, Sport, Videogame and Entertainment groups
Completion is not available for DateAndTime
, FakeDuration
and ProviderRegistration
, nor for non-Base provider groups.
Inlay hint for ResponseTemplateTransformer.Builder#maxCacheEntries
According to the Template caching documentation for maxCacheEntries()
:
Setting the limit to 0 will disable caching completely
Thus, when 0L
is provided as argument to maxCacheEntries()
, an inlay hint is displayed to inform users that caching is disabled.
NOTES:
- In case of constants as arguments, no hint is displayed, since possibly they have a name that signals that caching is disabled. An inlay hint would provide no useful information in that case.
- This inlay hint is no longer valid since WireMock 3.0.0, since
ResponseTemplateTransformer.Builder
has been removed in 3.0.0-beta-11.
If you are using WireMock 3.0.0, it is advised to turn the inlay hint off underSettings
/Editor
/Inlay Hints
/Other
/Java
/WireMock: ResponseTemplateTransformer.maxCacheEntries
.
Inlay hints for mustache parameters in JSON stub mapping files
Parameter name hints, similar to Java method parameter name hints, are available for certain WireMock specific Handlebars helpers. The aim of these hints is to provide additional context of what data is passed in, and make the mustaches less cryptic where feasible.
This feature is disabled by default and can be enabled in Settings
/ Editor
/ Inlay Hints
/ Parameter names
/ JSON
.
A few things to know about the hints:
- The following helpers are supported:
xPath
,soapXPath
,jsonPath
,formData
,regexExtract
,range
,parseJson
. - No hint is added when a helper accepts at least one parameter, and there is only one parameter specified. E.g.:
{{parseJson someSource}}
. This is, so that hints are not displayed when they wouldn’t actually provide useful extra information. - The parameter names are designed to be as short as possible to minimize the ‘noise’ in the injected Handlebars fragments.
- Sub-expressions are also supported. Those hints are disabled by default and can be enabled in the plugin settings under
Settings
/Tools
/WireMocha
.
Currently, helper parameter hints are not supported in the Java DSL.