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.
- 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 | – |
Other extra validations:
pickRandomis reported when only a single item is specifiedmathis reported if an unsupported operation is specified
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
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.
Code completion
Code completion is available for WireMock’s custom Handlebars helpers:
- helper names
- hash names of helpers that support hashes
- string literal hash values where a list of applicable values can be determined
- request attributes based on the WireMock request model
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:
NOTE: Completion of non-string literal hash values and simple parameters are not supported at the moment.
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.
NOTE: 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.