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 | – |
Other extra validations:
pickRandomis reported when only a single item is specifiedmathis reported if an unsupported operator 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
NOTE: at the moment this works only in actual Handlebars files (physical, or via editing injected fragments), but not when working with Handlebars in Java and JSON files.
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, and data from the original request in webhooks and callbacks.
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.
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.Builderhas 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.
