Response templating

[hide]

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 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		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’	–
val	1		or, default, assign	–
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 specified
math: unsupported operations are reported
truncateDate: unsupported date-time truncation values are reported
val: having specified simultaneously the or and default hashes are reported
random (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 the RandomHelper behind the scenes.
state (for the wiremock-state-extension) reports:
- empty context hash value
- if both property and list hashes are specified
- if neither property nor list hash is specified

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
- 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 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 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.