Creating and Calling Stateful Stubs
state
Handlebars helper
to render it in a Handlebars template. Instead, it lives only for the lifetime of the request, and is accessible at
the top level of the Handlebars model. It can be used in State Operations and Variable Definitions, and rendered in
response bodies and webhook request bodies. It is typically defined dynamically using a Handlebars template. It cannot
be one of our reserved words: request
, response
, parameters
, data
, event
, config
, originalRequest
or
originalResponse
.
itemId
. A State Value is stored and looked up using a Key. A Key references
different State Values in different Contexts. For keys defined on state operations, a Handlebars template that has
access to the request model, such as {{ request.path.userId }}
, can be used to build the key. This is not the case
for keys defined on request variables, which must be plain strings.
SET
operation uses a Handlebars template that has access to
the request model and the previousValue
(null
if not present in that Context) of the State Value in order to emit
the new State Value.
POST
and the path to /itemName
.
Open the “State” section and toggle on “Dynamic state”:
SET
. Add a Key called itemName
with a value of
“Socks”:
POST
to /setAnItemName
- you should get a response with a body “State itemName was set to Socks”.
You can now use the Handlebars helper {{ state 'itemName' }}
in the Response body of any stub to return the state
value currently associated with the itemName
key in the default context. For instance if you add a new stub for
GET /someItemName
, check “Enable dynamic response templating” and put the following in the body
text area:
SET
State operation supports Handlebars templating in order to dynamically set the value based
on the contents of an incoming request. The model available in the template is the same request data model that is provided in the response template,
along with a previousValue
containing the value of the Key in this Context before the operation was run, or null
if
it had no value.
For example, we could change the “Value” in the example above to {{ request.body }}
. Now the
itemName
state key in the default context will be associated with the request body that was last sent as a POST
to
/setAnItemName
. For instance a POST
to /setAnItemName
with body “Shoes” will return “State itemName was set to
Shoes”, and a subsequent GET
to /someItemName
will then return “The current itemName is Shoes”.
While state values are stored as strings, it is normally convenient to make those strings valid JSON and use
WireMock Cloud’s rich set of JSON helpers to manipulate those values using the template
in the “Value” field.
{{ state '<key>' }}
you will be rendering the value from the Mock API’s default context.
You can specify an explicit context both when setting state and when rendering it.
POST
to /setAnItemName
with a body of “Shirts” and a header x-test-id: 1
, and a POST
to /setAnItemName
with a body
of “Trousers” and a header x-test-id: 2
will set itemName
to “Shirts” in the context called “1” and to “Trousers” in
the context called “2”.
state
helper. You can see it can be a template, allowing you to set the
context dynamically on render just as you could set it dynamically when making a State operation.
Block:
state
helpers within the stateContext
block are evaluated with the context specified in that block, saving
unnecessary repetition.
listState
helper.
Template:
listState
helper returns a collection containing every state value within the provided context. In the case above,
the context to list items from is request.headers.x-test-id
, which will resolve to the request’s x-test-id
header.
Authorization
header so that they are isolated from changes made by any other user.
Having to specify {{request.headers.Authorization}}
as the context of every state SET operation, and wrap every
template that uses state in {{#stateContext request.headers.Authorization}}{{/stateContext}}
would be tedious.
Consequently WireMock Cloud allows setting a template for the default context
In the Mock API’s Settings, find the State section. Here you can set the Default context to e.g.
{{request.headers.x-test-id}}
. State operations using the Default context will now use that value as the context, and
{{ state }}
helpers which do not specify a context and are not nested in a {{#stateContext}}
block will also use that
value as the context.
DELETE
. The “Context” & “Key” fields are the same as for a SET
operation. Whenever this stub matches it will now
delete the given key from the given context.
DELETE_CONTEXT
. The “Context” field is the same as for a SET
or DELETE
operation. Whenever this
stub matches it will now delete all keys from the given context.
GET /someItemName
stubs, the existing one which returns a 200
with the itemName
value if it exists, and one which returns a 404 if it does not.
Under “State -> Request matching” click “Add request matcher”.
For the 200
stub add a matcher with Key: itemId
NOT is absent
.
For the 404
stub add a matcher with Key: itemId
is absent
.
previousValue
; for instance you might store a requestCount
state value, and make the SET operation increment it as
so: {{math previousValue '+' 1}}
. WireMock Cloud guarantees that SET operations on a particular
Key in a particular Context will happen sequentially, so 5 concurrent requests to that stub would increment the
requestCount
5 times.