WireMock State extension
Adds support to transport state across different stubs.
Feature summary
- Store a state for a context
- overwrite states
- append new states a state list
- Delete a state
- delete states from state list (first, last, by index, by state propery comparison)
- Request matching against context existance/non-existance
- Response templating integration
- get state for a given context
- get state list entry by index
- Templating support in all configuration options of this extension
Glossary
| Term | Description |
|---|---|
context |
States are scoped by a context. Behavior is similar to a key in a map. |
state |
The actual state. There can be only one per context - but it can be overwritten. |
property |
A property of a state. A state can have multiple properties. |
list |
Next to the singularic state, a context can have a list of states. The list of states can be modified but states within the list can't. |
classDiagram
direction LR
Store "1" *-- "*" Context
Context "1" *-- "1" State
Context "1" *-- "1" List
List "1" *-- "*" State
State "1" *-- "*" Property
class Property {
+String key
+String value
}
Background
WireMock supports Response Templating and Scenarios to add dynamic behavior and state. Both approaches have limitations:
Response templatingonly allows accessing data submitted in the same requestScenarioscannot transport any data other than the state value itself
In order to mock more complex scenarios which are similar to a sandbox for a web service, it can be required to use parts of a previous request.
Example use cases
Create a sandbox for a webservice. The web service has two APIs:
CRUD
POSTto create a new identity (POST /identity)- Request:
json { "firstName": "John", "lastName": "Doe" } - Response:
json { "id": "kn0ixsaswzrzcfzriytrdupnjnxor1is", # Random value "firstName": "John", "lastName": "Doe" }
- Request:
-
GETto retrieve this value (GET /identity/kn0ixsaswzrzcfzriytrdupnjnxor1is) -
Response:
json
{
"id": "kn0ixsaswzrzcfzriytrdupnjnxor1is",
"firstName": "John",
"lastName": "Doe"
}
The sandbox should have no knowledge of the data that is inserted. While the POST can be achieved
with Response Templating,
the GET won't have any knowledge of the previous post.
Queue
POSTadd a new item (POST /queue)- Request:
json { "firstName": "John", "lastName": "Doe" } - Response:
json { "id": "kn0ixsaswzrzcfzriytrdupnjnxor1is", # Random value "firstName": "John", "lastName": "Doe" }
- Request:
2POST add another new item (POST /queue)
- Request:
```json { "firstName": "Jane", "lastName": "Doe"
}
```
- Response:
json
{
"id": "54owywgurlqepq1wc5xvyc2hipe8xp4u",
#
Random
value
"firstName": "Jane",
"lastName": "Doe"
}
-
GETto retrieve the first value (GET /queue) -
Response:
```json { "id": "kn0ixsaswzrzcfzriytrdupnjnxor1is", "firstName": "John", "lastName": "Doe"
}
```
-
GETto retrieve the second value (GET /queue) -
Response:
json
{
"id": "54owywgurlqepq1wc5xvyc2hipe8xp4u",
"firstName": "Jane",
"lastName": "Doe"
}
Usage
Compatibility matrix
wiremock-extension-state version |
WireMock version |
|---|---|
0.0.3+ |
3.0.0-beta-11+ |
0.0.6+ |
3.0.0-beta-14+ |
0.1.0+ |
3.0.0+ |
Installation
Gradle
repositories {
maven {
url = uri("https://maven.pkg.github.com/wiremock/wiremock-extension-state")
}
}
dependencies {
testImplementation("org.wiremock:wiremock-state-extension:<your-version>")
}
Maven
Follow the instructions on GitHub Docs to add authentication to GitHub packages.
<repositories>
<repository>
<id>github-wiremock-extension-state</id>
<name>WireMock Extension State Apache Maven Packages</name>
<url>https://maven.pkg.github.com/wiremock/wiremock-extension-state</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>org.wiremock</groupId>
<artifactId>wiremock-state-extension</artifactId>
<version>your-version</version>
<scope>test</scope>
</dependency>
</dependencies>
Register extension
Java
This extension makes use of WireMock's ExtensionFactory, so only one extension has to be registered: StateExtension.
In order to use them, templating has to be enabled as well. A store for all state data has to be provided. This extension
provides a CaffeineStore which can be used - or you can provide your own store:
public class MySandbox {
private final WireMockServer server;
public MySandbox() {
var stateRecordingAction = new StateRecordingAction();
var store = new CaffeineStore();
server = new WireMockServer(
options()
.dynamicPort()
.templatingEnabled(true)
.globalTemplating(true)
.extensions(new StateExtension(store))
);
server.start();
}
}
Standalone
This extension uses the ServiceLoader extension to be loaded by WireMock. As Standalone version, it will use CaffeineStore for
storing any data.
The standalone jar can be downloaded from GitHub .
java -cp "wiremock-state-extension-standalone-0.0.5.jar:wiremock-standalone-3.0.0-beta-11.jar" wiremock.Run
Docker
Using the extension with docker is similar to its usage with usage standalone: it just has to be available on
the classpath to be loaded automatically - it does not have to be added via --extensions .
Note: This extension depends on the current WireMock beta development, thus the tag 3x has to be used:
docker run -it --rm \
-p 8080:8080 \
--name wiremock \
-v $PWD/extensions:/var/wiremock/extensions \
wiremock/wiremock:3x \
-- --global-response-templating
Record a state
The state is recorded in serveEventListeners of a stub. The following functionalities are provided:
state: stores a state in a context. Storing the state multiple times can be used to selectively overwrite existing properties.- to delete a selective property, set it to
null(as string). list: stores a state in a list. Can be used to prepend/append new states to an existing list. List elements cannot be modified (only read/deleted).
state and list can be used in the same ServeEventListener (would count as two updates). Adding multiple recordState ServeEventListener is supported.
The following parameters have to be provided:
| Parameter | Type | Example | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| `context` | String | - `"context": "{{jsonPath response.body '$.id'}}"` - `"context": "{{request.pathSegments.[3]}}"` | |||||||||
| `state` | Object |
|