Exploring WireMocks Admin API
WireMock is a Java-based web service mocking tool that allows developers to simulate a web service’s behavior for testing purposes. WireMock provides an Admin API, which manages the mock server and its interactions. I will explore the stub mappings and scenarios that you can manipulate with the admin API.
Stub Mappings
In WireMock, a stub mapping defines a response to an HTTP request. A stub mapping consists of three primary elements:
- Request: This element defines the HTTP request that the stub mapping will match against. It includes information such as the HTTP method, URL, headers, query parameters, and request body.
- Response: This element defines the HTTP response that the stub mapping will return if the request matches. It includes information such as the HTTP status code, headers, and response body.
- Optional metadata: This element can include additional information about the stub mapping, such as a unique identifier, a description, or a priority.
WireMock provides several ways to create and manage stub mappings through its admin API. Let’s look at some examples.
Create a stub mapping
To create a new stub mapping, you can send a POST request to the /__admin/mappings
endpoint with the following JSON body:
{
"request": {
"method": "GET",
"url": "/api/users",
"headers": {
"Content-Type": {
"equalTo": "application/json"
}
}
},
"response": {
"status": 200,
"body": "[{\"id\":\"1\",\"name\":\"John\"},
{\"id\":\"2\",\"name\":\"Jane\"}]",
"headers": {
"Content-Type": "application/json"
}
}
}
This will create a new stub mapping that will match any GET request to /api/users
with a Content-Type
header of application/json
. It will return a 200 status code with the JSON array of two users.
Update a stub mapping
To update an existing stub mapping, you can send a PUT request to the /__admin/mappings/:id
endpoint with the ID of the stub mapping and the updated JSON body.
{
"request": {
"method": "GET",
"url": "/api/users",
"headers": {
"Content-Type": {
"equalTo": "application/json"
}
}
},
"response": {
"status": 200,
"body": "[{\"id\":\"1\",\"name\":\"John\"},
{\"id\":\"2\",\"name\":\"Jane\"},
{\"id\":\"3\",\"name\":\"Bob\"}]",
"headers": {
"Content-Type": "application/json"
}
}
}
This will update the previous stub mapping to return three users instead of two.
Delete a stub mapping
To delete an existing stub mapping, you can send a DELETE request to the /__admin/mappings/:id
endpoint with the ID of the stub mapping.
{
"id": "12345678-abcd-1234-abcd-1234567890ab"
}
This will delete the stub mapping with the given ID.
Scenarios
Scenarios enables you to simulate complex sequences of interactions. A scenario consists of multiple steps, each of which represents a single HTTP request/response pair. Each step can be conditional, meaning that it will only be executed if the previous step matches a particular condition.
WireMock provides a simple Domain-Specific Language (DSL) for creating scenarios through its admin API.
Create a scenario
To create a new scenario, you can send a POST request to the /__admin/scenarios
endpoint with the following JSON body.
{
"scenarioName": "example_scenario",
"requiredScenarioState": "Started",
"newScenarioState": "Finished",
"steps": [
{
"request": {
"method": "POST",
"url": "/api/login",
"bodyPatterns": [
{
"equalToJson": "{\"username\": \"testuser\",
\"password\": \"testpassword\"}"
}
]
},
"response": {
"status": 200
}
},
{
"request": {
"method": "GET",
"url": "/api/user",
}
},
"response": {
"status": 200,
"body": "{\"id\": \"123\", \"name\": \"Test User\"}"
}
}
]
}
This will create a new scenario called example_scenario
that has two steps. The first step is a POST request to /api/login
with a JSON body matching the username
and password
fields. The second step is a GET request to /api/user
. The second step will only be executed if the first step has been successfully completed and the scenario is in the Started
state.
It is also possible to have multiple GET’s that give a different reply after each other:
{
"scenarioName": "example_scenario",
"requiredScenarioState": "Started",
"newScenarioState": "Finished",
"steps": [
{
"request": {
"method": "GET",
"url": "/api/user",
}
},
"response": {
"status": 200,
"body": "{\"id\": \"123\", \"name\": \"Test User\"}"
}
},
{
"request": {
"method": "GET",
"url": "/api/user",
}
},
"response": {
"status": 200,
"body": "{\"id\": \"456\", \"name\": \"Other User\"}"
}
}
]
}
This will create a scenario that has two steps. The first step is a GET and the second is the same GET. You get each time you do a get to “/api/user” a different response.
Update a scenario
To update an existing scenario, you can send a PUT request to the /__admin/scenarios/:scenarioName
endpoint with the name of the scenario and the updated JSON body.
{
"scenarioName": "example_scenario",
"requiredScenarioState": "Finished",
"newScenarioState": "Started",
"steps": [
{
"request": {
"method": "POST",
"url": "/api/login",
"bodyPatterns": [
{
"equalToJson": "{\"username\": \"testuser\",
\"password\": \"testpassword\"}"
}
]
},
"response": {
"status": 200
}
},
{
"request": {
"method": "POST",
"url": "/api/logout"
},
"response": {
"status": 200
}
}
]
}
This will update the example_scenario
scenario to include a new step that logs out the user by sending a POST request to /api/logout
. The scenario will now only be executed if it is in the Finished
state.
Delete a scenario
To delete an existing scenario, you can send a DELETE request to the /__admin/scenarios/:scenarioName
endpoint with the name of the scenario.
{
"scenarioName": "example_scenario"
}
This will delete the example_scenario
scenario.
Conclusion
Testers can easily simulate HTTP-based services and test their applications in a controlled environment by using Wiremock. WireMock’s admin API provides a flexible interface for creating and managing mock servers.
References
- Photo by Brett Sayles
- API Documentation of Wiremock.