Mapping files

JSON schema

A JSON schema is bound to WireMock JSON mapping files (based on the schemas in the WireMock GitHub repository), which automatically provides validation and code completion. It works both for single- and multi-mapping files.

NOTE: the validation and auto-completion features are not implemented in this plugin, but in the IntelliJ platform itself. WireMocha simply provides the configuration for the IntelliJ platform, so that it knows what conditions must a file meet to assign a certain schema file to it.

Request-response information on Project View file nodes

To provide a basic overview of what data stub mapping files hold, this node decorator adds some basic information to stub mapping file nodes in the Project View.

It provides information on the following parts:

request method: the value of the request.method property
request url: the value of, any one of, the following properties first found: request.url, request.urlPath, request.urlPattern, request.urlPathPattern
response status: the value of the response.status property

Enable/disable node decoration

There is a toolbar action in the Project View to enable/disable the node decoration. By default, it is turned off. It saves the enabled/disable state per project.

Classification

Mapping files are classified as follows:

no mapping
single mapping
single mapping incomplete
multiple mappings
multiple mappings incomplete

The way and cases which category and what information is displayed also aims to uncover potentially erroneous mapping files and missing properties.

No mapping

A mapping file is considered empty, and the file node is decorated with the text no mapping, when:

the file is completely empty,
the root-level value is not an object, for instance the content is an array: ["some", "array"],
There is neither a request nor a response property in a single-stub mapping file. {} or { "id": "..." },
There is no stub mapping inside a mappings property: { "mappings": [ ] } or { "mappings": [ {} ] }

Single mapping

A mapping file is considered having a single mapping when:

There is one request-response mapping in the file with both a request and a response property present:

{
  "request": { ... },
  "response": { ... }
}

There is a mappings property, and there is only one stub mapping inside. That single mapping must have both a request and a response property:

{
  "mappings": [
    {
      "request": { ... },
      "response": { ... }
    }
  ]
}

In this case, the file is decorated with the following texts, based on the input values:

`request.method`	`request.url*`	`response.status`	Node decoration text
“”	“”	200	-> 200
“”	“/url”	“”	/url ->
“”	“/url”	200	/url -> 200
PUT	“”	“”	PUT ->
PUT	“”	200	PUT -> 200
PUT	“/url”	“”	PUT /url ->
PUT	“/url”	200	PUT /url -> 200
PUT	“/really-very-very-long-url”	200	PUT /really-very-very-lo… -> 200

The last example shows that url values are truncated at 20 characters to keep the node decoration concise.

In the following cases, the single mapping files is considered incomplete, but the decoration text will still be displayed according to the table above, extended with some error tags to notify about missing information:

There is one request-response mapping in the file but it lacks either the request or the response property.
There is a mappings property, and there is only one stub mapping inside. That single mapping lacks either the request or the response property.

Missing information tags

When there is information missing to properly display the node decoration, the mapping properties are substituted with the following information:

no request: <missing request>
no request.method: <no method>
no request.url: <no url>
no response: <missing response>
no response.status: <no status>

The resulting node decoration text can be like <no method> /some/url -> <missing response>.

Multiple mappings

A mapping file is considered having multiple mappings when there is a mappings property with more than one stub mapping, and all mappings contain a request and a response property inside:

{
  "mappings": [
    {
      "request": { ... },
      "response": { ... }
    },
    {
      "request": { ... },
      "response": { ... }
    }
  ]
}

In this case, the file node is decorated with the text multiple.

Where there is a mappings property with more than one stub mapping inside, but at least one of them lacks either the request or the response property, it is considered incomplete, and the file node is decorated with multiple (has incomplete).

Indexing

The displayed data is coming from a custom index implementation, so if you have the node decoration enabled when the IDE or a project launches, and you have some mapping folders open, the files inside won’t be visible until the IDE finishes indexing.

If you don’t use the node decoration feature, it is recommended to disable it to minimize any performance/resource impact it may have on the IDE.

Unwrap single stub mapping in multi-mapping definitions

This inspection can report mappings properties in JSON mapping files that contain only a single stub mapping. In that case, specifying the mappings property is not necessary, the stub mapping object itself can be the sole content of the mapping file.

It also provides a quick fix that unwraps the stub mapping, and essentially removes the wrapping around it.

Whether that child mapping has any content doesn’t matter, the property is reported regardless. However, nothing is reported when mappings has a meta sibling property specified, since that one doesn’t have a counterpart in the individual stub mapping schema.

Example:

{
  "mappings": [ //"mappings" property name is reported
    {
      "request": { ... },
      "response": { ... }
    }
  ]
}

becomes

{
  "request": { ... },
  "response": { ... }
}

Create mapping file from template

The Create Mapping File action is available in the Project view context menu on directories called mappings and on subdirectories of them. It uses File Templates to pre-populate mapping files with predefined contents.

You can select from two templates (both editable in Settings > Editor > File and Code Templates > Files). The provided file name must include the .json extension too.

single request-response mapping

{
  "request": {
    "method": "GET",
    "url": "/"
  },
  "response": {
    "status": 200
  }
}

multiple request-response mappings

{
  "mappings": [
    {
      "request": {
        "method": "GET",
        "url": "/"
      },
      "response": {
        "status": 200
      }
    },
    {
      "request": {
        "method": "GET",
        "url": "/"
      },
      "response": {
        "status": 200
      }
    }
  ]
}

Split multi-mapping file into multiple single-mapping files

This action is available in the Project view context menu at WireMock > Split Mapping File. The action is visible regardless of the contents of the mapping files, but not all mapping files can be/make sense to be split.

Given the following mapping file, it splits this mapping file:

# filename: multi_mapping.json
{
  "mappings": [
    {
      "request": { 
        "method": "GET"
      }
      "response": { ... }
    },
    {
      "request": {
        "method": "POST"
      }
      "response": { ... }
    }
  ]
}

into the following ones:

# filename: multi_mapping_0.json
{
    "request": {
      "method": "GET"
    }
    "response": { ... }
}

# filename: multi_mapping_1.json
{
    "request": {
      "method": "POST"
    }
    "response": { ... }
}

The filenames are index-postfixes starting from 0. The original mapping file is removed after the new files are created.

Mapping files in certain cases cannot be split. If that is the case, a notification balloon is displayed in the Project View, on the mapping file node, to let you know why the split cannot happen:

no indexed data for the file (ideally this should not happen),
there is no mapping in the file
there is only a single mapping in the file
there are multiple mappings, but at least one of them doesn’t specify either the request or response property.

Merge stub mapping files in a selected folder

This action is available in the Project view context menu at WireMock > Merge Mapping Files in This Directory, when there is at least two JSON files (be it mapping or non-mapping ones) present in the selected directory.

It merges all JSON mapping files in that directory (files in subdirectories are not included) in three phases, and provides a progress bar as well, in case there is a large number of files to merge:

Phase 1: collects the stub mapping JSON objects. The mappings are collected in alphabetical order of their containing files’ names, and in the order of their presence in those files. Non-mapping files, and files that don’t contain a stub mapping, are excluded.
Phase 2: merges the collected mappings into a new JSON file, whose name must be specified by the user.
- NOTE: the .json extension must be included when specifying the file name.
Phase 3: deletes all mapping files from the selected directory.
- NOTE: mapping files that don’t contain any mapping, are deleted too. At the moment, there is no option to exclude them from the deletion.

Given the following two stub mapping files (responses are ommitted for brevity):

# filename: single_mapping.json
{
  "request": {
    "method": "PATCH",
    "url": "/single-mapping"
  },
  "response": { ... }
}

# filename: multi_mapping.json
{
  "mappings": [
    {
      "request": {
        "method": "GET",
        "url": "/multi-mapping"
      },
      "response": { ... }
    },
    {
      "request": {
        "method": "POST",
        "url": "/multi-mapping"
      },
      "response": { ... }
    }
  ]
}

The merged version will be – mappings from multi_mapping.json precede ones from single_mapping.json because of their filenames’ alphabetical order:

{
  "mappings": [
    {
      "request": {
        "method": "GET",
        "url": "/multi-mapping"
      },
      "response": { ... }
    },
    {
      "request": {
        "method": "POST",
        "url": "/multi-mapping"
      },
      "response": { ... }
    },
    {
      "request": {
        "method": "PATCH",
        "url": "/single-mapping"
      },
      "response": { ... }
    }
  ]
}

Handling errors during the merge process

There are popup balloons displayed when the whole merge process, or a part of it, couldn’t happen due to some precondition, or an error:

No mapping file to merge.: when there is no actual mapping file in the directory, even if there are other JSON files present.
A single mapping file won’t be merged.: when there is only a single mapping file in the directory.
Could not get the content of some mapping files. See IDE logs.: there is a problem reading the content of a file.
Could not delete some mapping files. See IDE logs.: speaks for itself
Could not merge files. See IDE logs.: a catch-all message if there was any other kind of issue during any of the phases that is not caught/handled by the merge logic.

When the balloon message includes See IDE logs, there is further stacktrace information and reasoning available in the IDE’s idea.log file.