Response templating
Handlebars Helpers
This document details the various integrations that are added to WireMock’s custom Handlebars helpers.
Language injection
Both WireMocha and the JetBrains WireMock plugin provide Handlebars language injection but there are a few differences when and where they work.
| Plugin | Java DSL support | JSON stub mapping support | JSON support in __files directory | Application |
|---|---|---|---|---|
| WireMocha | + | + | – | Automatic. JSON stub mapping may be enabled/disabled in plugin settings. |
| JetBrains WireMock | – | + | + | On-demand via floating toolbar |
There are features, for example Handlebars helper name code completion, in which some data is provided by WireMocha, some others by JetBrains WireMock, so they are quite complementary, and enhance each other’s feature sets.
In case you experience issues when both WireMocha’s and JetBrains WireMock’s Handlebars language injection is enabled, you have the following options:
- either disable the WireMock plugin’s injection via the floating toolbar
- or disable WireMocha’s one in Settings > Languages & Frameworks > WireMocha > Injection Handlebars language in JSON stub mapping files. This leaves other Handlebars related features, like code completion and inspections, enabled.
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 block params (no value -> same as in non-blocks or blocks aren’t supported) | 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 | count | – | |
| 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 | – | |
| arrayJoin | 2-INF | 2 | prefix, suffix | Yes |
| arrayAdd | 2 | position – default value: ‘end’ | – | |
| arrayRemove | 1 | position – default value: ‘end’ | – | |
| formatJson | 1 | 0 | format – default value: ‘pretty’, – allowed values: ‘compact’, ‘pretty’ | |
| formatXml | 1 | 0 | format – default value: ‘pretty’, – allowed values: ‘compact’, ‘pretty’ | |
| jsonArrayAdd | 2 | 1 | jsonPath flatten – default value: ‘false’, – allowed values: true, false maxItems | |
| jsonMerge | 2 | 1 | removeNulls – default value: ‘false’ – allowed values: true, false | |
| jsonRemove | 2 | |||
| toJson | 2 | |||
| val | 1 | or, default, assign | – | |
| random | 1 | – | – | |
| state | 0 | context – non-empty string list property – allowed values: ‘updateCount’, ‘listSize’, ‘list’ | – |
Other extra validations:
pickRandomis reported when only a single item is specifiedmath: unsupported operations are reportedtruncateDate: unsupported date-time truncation values are reportedval: having specified simultaneously theoranddefaulthashes are reportedjsonArrayAdd:- the item to add must be a string
- the
jsonPathhash value must a non-empty string - the
flattenhash value must be a boolean - the
maxItemshas value must be a positive integer
jsonMerge: both parameters must be stringjsonRemove: the input JSON must be a string, the JSON path must be a non-empty stringrandom(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 theRandomHelperbehind the scenes.state(for the wiremock-state-extension) reports:- empty
contexthash value - if both
propertyandlisthashes are specified - if neither
propertynorlisthash is specified
- empty
Notes on the table above:
- The number of params include the so-called
contextparameter 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.StateHandlerbarHelperin 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
- eligible helper names are also configured to be completed only if a suitable version of WireMock is available
- hash names of helpers that support hashes
- certain hashes are also configured to be completed only if a suitable 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
truncateDatehelper
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 a description, and an icon if they are mandatory:
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 maxCacheEntries() and withMaxTemplateCacheEntries()
For maxCacheEntries() and withMaxTemplateCacheEntries(), when 0L is provided as argument, an inlay hint is displayed to inform users that caching is disabled. The same is true when null is provided, to signal that there is no limit on the number of cache entries.
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.
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.
Quick documentation popups on helper hashes
In order to have information available at users’ fingertips about Handlebars helper hashes, a Quick Documentation popup
is available when invoked with the Ctrl+Q or similar shortcut key.
The popup, depending on what the hash supports and represents, may show the following information and in the following format:
[hash name]
-------------------------------------
[description]
Type: [type]
Accepted values: [values]
Default value: [default]
Available: [version range]
Notes:
- For now, the type is not displayed for hashes that accept String or a broader range of types.
- The accepted values, the default value and the version range the hash is available in, are not displayed for hashes they are not applicable to.