WireMock Tool Window

The WireMock tool window can be found at bottom left of the IDE frame, and consists of the tabs Admin API and Generate Scenario. You can find more details about them in the sections below.

Admin API Client

This tool is designed to provide an GUI where users can interact with a standalone WireMock server (launched locally or remotely) in an easy way.

In summary, to send requests to a server, one needs to do the following:

• specify the Admin root URL,
• select an endpoint you want to send the request to,
• configure the query and path parameters for the endpoint, if there is any,
• configure the request body for the endpoint, if there is any,
• click Send.

The left hand side of the tool window provides the options to configure the endpoints with the necessary data.

Admin root and endpoint selection

In order to have a target to where the requests will be sent, one has to specify the Admin root URL and select the endpoint.

The Admin root is a local or remote URL of a WireMock server, and must end with /__admin. To simplify the process of filling in the field, clicking the Use Default Root button populates the field with the default configuration.

There are a couple of validations on the Admin root field (e.g. must not be empty, and must end with /__admin), and the request cannot be sent (the Send button is disabled) until it is set to a valid value. In addition to this, the Send button is also disabled when any of the parameter or request body fields contain invalid values.

The dropdown next to the Admin root field contains the available endpoints. The item names of the ones that are available in the Admin API’s OpenAPI specification are the same as in the aforementioned specification.

Upon selecting an endpoint, the area below is updated to provide relevant query parameter, path parameter and request body configuration. When there is at least one parameter field, the first such field is focused automatically for a smoother typing experience.

When selecting certain endpoints, you may notice that the Send button is disabled right off the bat. This is because there is at least one parameter or request body that needs to be specified in order to have a valid configuration for the endpoint.

Endpoints contributed by WireMock extensions

Since the set of Admin API endpoints can be extended by implementing com.github.tomakehurst.wiremock.extension.AdminApiExtension, it opens up the possibility to add those custom endpoints to the Admin API tool window as well.

One such endpoint is provided by the wiremock-grpc-extension. It reloads gRPC descriptor files, and is available under the /__admin/ext/grpc/reset relative URL.

This endpoint is added to the end of the Admin API endpoints lists in the tool window, and it is marked accordingly that is is provided by the wiremock-grpc-extension.

Proxy and Authenticator

There is additional configuration available for establishing a connection to a WireMock server:

• Client authenticator
• Value set in the Host header for authentication
• Proxy host and port

Available authenticators are the ones implementing the com.github.tomakehurst.wiremock.security.ClientAuthenticator interface:

• No authenticator: NoClientAuthenticator
• Basic: ClientBasicAuthenticator
• Token: ClientTokenAuthenticator
• Single header: SingleHeaderClientAuthenticator

Passwords and tokens are displayed as password fields with hidden symbols. Passwords and tokens are not stored physically anywhere (neither on the file system nor in a password safe), they only live in the underlying com.github.tomakehurst.wiremock.client.WireMock object instances that are responsible for handling the communication with the WireMock servers.

Parameters

The endpoints in the Admin API use query parameters and path parameters (not necessarily both, or even any one of them) to customize the input data sent to the endpoint. Some are mandatory, some are optional, and the validation of them is handled accordingly.

Query parameters are displayed as e.g. limit:

while path parameters are displayed as e.g. {{stubMappingId}} to signal that they are path parameters and not query parameters:

These fields incorporate validation logic too with relevant error messages, and the Send button gets disabled automatically when invalid values are specified in them.

Each field has a context help icon next to them that contain explanation about the corresponding field.

Some fields also have comments underneath to provide example values, like the {{stubMappingId}} field a bit above.

Request body

The request body section (for endpoints that require such data) consists of the following main parts:

• the request body editor,
• an error icon if the editor content is invalid,
• the schema type that the JSON content must adhere to,
• example code snippet(s)

The request body editor provides advanced coding support for specifying the JSON body. It provides:

• JSON schema based code completion and validation,
• language injections, including Handlebars,
• inspections and intention actions (in case of StubMapping request bodies)

It doesn’t provide reference resolution and line markers at the moment.

Below the editor, there is one or more schema types (actual WireMock classes) that the JSON content specified in the editor must adhere to. Next to this type there is a help icon that contains code examples.

If the editor contents do not match the defined schema type, and error icon appears next to the section label, and the Send button gets automatically disabled, so that requests cannot be sent with an invalid request body.

Request sending

Requests can be sent by clicking on the Send (green play) button.

Requests are processed on a background thread in order to avoid GUI freezing and allow users to meanwhile interact with different parts of the IDE. This is indicated by a progress bar on the IDE’s status bar.

The Send button is disabled while a request is being processed, so that processing of only one request is allowed at a time.

If there is a connection related issue after sending the request, e.g. an unknown host or there is no server available on the given address, the Admin root field is highlighted and a relevant error message is displayed on it. If you need further details about the underlying exception that was thrown, see the IDE logs.

Response handling

The right hand side of the tool window displays the raw response from the endpoint and error messages if any happened during processing the request.

When a request is successful, the raw response (when the endpoint specification provides a response body) is displayed in the non-editable editor, and a success message is displayed underneath. This latter one is more useful in cases when the endpoint doesn’t return a response body.

If an issue occurred during the request processing, an error message is displayed, and no value is populated into the response field. The underlying exceptions are also logged in the IDE logs to provide further details.

The response field is cleared automatically when Sending a request, so to not confuse users with remaining responses.

Connecting to a stub server in WireMock Cloud

To interact with a server in WireMock Cloud, the following steps are needed:

• Configure the Admin root field with the address of the stub server like this: https://.wiremockapi.cloud/__admin,
• Open the Proxy and Auth Configuration section,
• Select the Token authenticator,
• Copy your WireMock Cloud API Token from the Security subpage of your WMC account, and paste it into the Token field in the tool window.

Interacting with WireMock Cloud’s Provisioning API

The tool window provides dedicated buttons to switch between the regular Admin API and WireMock Cloud’s Provisioning API.

Once the Provisioning API is selected

• the base URL field, Host header and proxy settings become disabled,
• the base URL field is filled with the fixed value https://api.wiremock.cloud,
• only the Basic authenticator is made available.

In terms of parameters and request body configuration, this API works the same as the Admin API endpoint configurations, except that there is no schema type associated with request bodies since they are WireMock Cloud’s internal classes.

To send a request, select an endpoint, set the required configurations, set your username/email and WireMock Cloud API token then click the Send button.

Generate HTTP Client request

The toolbar features a section called Generate where one button resides: it can generate from the current Admin API tool window configuration a request in the HTTP Client format, which is then copied to the clipboard.

It is disabled for the WireMock Cloud Provisioning API, but is available regardless of the presence of the JetBrains HTTP Client plugin.

It uses the following fields to generate the request:

• the admin root URL,
• the request method and URI from the selected endpoint,
• authenticator details,
• the Host header value,
• path parameters, if any
• the request body, if any

Thus, it can generate something like this:

http request POST http://localhost:8080/__admin/mappings/import Authorization: Token sometoken Host: host-header-value Content-Type: application/json { "request": { }, "response": { } }

Notes:

• If an endpoint URI incorporates path parameters, e.g. /__admin/mappings/{stubMappingId}
• if there is a value specified, it replaces the parameter with the corresponding value, e.g.: /__admin/mappings/730d3e32-d098-4169-a20c-554c3bedce58
• if there is no value specified, the parameter is left untouched: /__admin/mappings/{stubMappingId}
• In case of authenticator details, if there is no value specified in a field, it is replaced with a placeholder to signal that that data is missing, for example in case of a missing password: Authorization: Basic some@email.address <no password>

Tips for keyboard users

For users who prefer using the keyboard, you can hit Enter in the Admin root field and in any of the parameter fields, and if the Send button is enabled, the request will be sent.

Not supported features

• WireMock Cloud specific endpoints, and among /files endpoints, the Get file by ID and Update or create a file endpoints.
• Saving configuration and credentials for later use.

Other notes

• When the Protocol Buffers plugin is enabled and some content is copy-pasted into the request body field, a NullPointerException may be thrown. There is already a related ticket on the JetBrains YouTrack (GO-16796).

Scenario generation

The aim of this tool is to generate skeleton Java and JSON stub mappings that are tied to a specific scenario.
It may help users to concentrate on modeling the scenario states first, without having to deal with the coding aspect in that state
of the implementation.

Scenario definition

On the left side of the tool, you can specify a scenario name that is being modeled, and stub definitions with the following attributes/columns
Method, URL, Current State and New State. Response code is not customizable at the moment.

On the right side, the code is automatically generated and updated upon modifications on the left side.

Each row of the table reads like this: Sending a Method-type request to URL in Current State will return some response, and optionally move the scenario to New State.

There is no validation on any of the fields, but for convenience, if the Current State is a case-insensitive variant of Scenario.STARTED or STARTED,
then the following values are generated into the code:

• Java: Scenario.STARTED
• JSON: Started

Note: the Method dropdowns are editable when double-clicked.

Toolbar actions

In addition to the standard Add, Remove and Move Up/Down actions, the following extra action are available:

• Add Stub Definition with Started State: adds a new table row whose Current State is set to STARTED.
• Transition from Previous New State: adds a new table row whose Current State is the New State of the selected row.
• Duplicate Row(s): duplicates the selected rows. The new rows are added to the end of the table.

Example (based on the WireMock Stateful Behaviour documentation):