Exploring WireMocks Admin API

· 5 min read

Exploring WireMock’s 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