Request Matching

JsonUnit placeholders

Syntax highlighting for JsonUnit placeholders

Since, in WireMock

JSON equality matching is based on JsonUnit and therefore supports placeholders.

(see also the Request matching document), simple highlighting (not actual language support) is added for these placeholders in JSON stub mapping files and Java String literals.

Code completion of JsonUnit placeholders is also available in JSON and Java String literal when invoked at a caret position where the preceding text is either ${json-unit. or #{json-unit..

XmlUnit placeholders

Syntax highlighting and code completion

Since, in WireMock

The underlying engine for determining XML equality is XMLUnit.
(see also the Request matching document), simple highlighting (not actual language support) is added
for these placeholders in JSON and Java String literals.

Code completion of XmlUnit placeholders is also available in JSON and Java String literal, as well as XML tags and attribute values, when invoked at a caret position where the preceding text is ${xmlunit..

Before-after matcher folding

WireMock provides quite a handful of methods for request matching, among which there are date-time related ones. The following ones are in scope of this code folding:

• before(...)
• beforeNow()
• after(...)
• afterNow()

Chained together with and() , these code snippets can be quite long, thus this code folding aims to lessen the cognitive load on having to read through the whole matcher expression.

In case they are used inside a matchingJsonPath, matchingXPath or matchesXPathWithSubMatcher matcher, the path is included in the folded placeholder text, otherwise the subject is substituted with it.

For now, the placeholder creation always takes the text of the after and before expressions, be it string literal, constant, or method call, and not the value they potentially evaluate to.

Inside matchingJsonPath():

unfolded:  stubFor(post("/").withRequestBody(matchingJsonPath("$.date", before("BEFORE").and(after("AFTER")))));
folded:    stubFor(post("/").withRequestBody(matching: "AFTER" < "$.date" < "BEFORE"));

unfolded:  stubFor(post("/").withRequestBody(matchingJsonPath("$.date", before("BEFORE").and(afterNow()))));
folded:    stubFor(post("/").withRequestBody(matching: [now] < "$.date" < "BEFORE"));

unfolded:  stubFor(post("/").withRequestBody(matchingJsonPath("$.date", beforeNow().and(after("AFTER")))));
folded:    stubFor(post("/").withRequestBody(matching: "AFTER" < "$.date" < [now]));

unfolded:  stubFor(post("/").withRequestBody(matchingJsonPath("$.date", and(before("2022-02-02T00:00:00"), after("2020-01-01T00:00:00")))));
folded:    stubFor(post("/").withRequestBody(matching: "2020-01-01T00:00:00" < "$.date" < "2022-02-02T00:00:00"));

Referencing constants:

private static final String AFTER_DATE = "after_date_value";
private static final String BEFORE_DATE = "before_date_value";

unfolded:  stubFor(post("/").withRequestBody(matchingJsonPath("$.date", before(BEFORE_DATE).and(after(AFTER_DATE)))));
folded:    stubFor(post("/").withRequestBody(matching: AFTER_DATE < "$.date" < BEFORE_DATE));

Standalone calls

unfolded:  LogicalAnd and = WireMock.and(before("BEFORE"), afterNow());
folded:    LogicalAnd and = [now] < it < "BEFORE";

unfolded:  LogicalAnd and = before("BEFORE").and(after("AFTER));
folded:    LogicalAnd and = "AFTER" < it < "BEFORE";

unfolded:  LogicalAnd and = after("AFTER").and(before("BEFORE"));
folded:    LogicalAnd and = "AFTER" < it < "BEFORE";

Individual before(...) and after(...) calls are not folded because the save on reading length is not that significant.

Between date-time “matcher” live template

Since no ‘between’ date-time matcher exists in WireMock, this live template helps to create and insert the before().and(after()) code snippet.

Nonsense matcher combinations

There are certain matcher combinations that either don’t make sense or contradict each other, so this inspection reports those cases.

For now, date-time specific matchers linked together with and() are supported. For example:

isNow().and(beforeNow())

The full list of combinations that are reported (the operands are applicable in the reverse order as well):

Method calls with too few arguments

There are methods that require a minimum number of arguments to be passed in. This inspection reports calls to them with a fewer number of arguments required.

Converting boolean and() and or() between WireMock and StringValuePattern variants

StringValuePattern type matchers can be combined into complex boolean matchers using and() and or(), and since they have static WireMock.and()/or() and instance StringValuePattern.and()/or()variants, it is possible to switch between the two forms.

From the fluent x.and(y)/x.or(y) forms the conversion is possible only when all operands are combined with and() or or(), respectively.

The intention is generally available if there are at least two operands specified. Bold text below means a selected code snippet.

From WireMock-based

From fluent

Note: if you want to flip the operands of a fluent call, there is already an intention coming from IntelliJ called Flip commutative method call that can do that.

Mixed

Replacing date-time “now” calls with convenience method calls

Since date-time matchers (after(), before(), equalToDateTime()) can accept WireMock’s now offset expression format, the aforementioned methods can be called with the String value "now" for which there are non-parametrized convenience methods.

Method calls chained to the original ones (e.g. after("now").and(before("SOME DATE"))) are kept after applying the quick fix, e.g. WireMock.afterNow().and(before("SOME DATE")).

request.pathParameters has no corresponding request.urlPathTemplate property

This inspection reports request.pathParameters properties when there are no request.urlPathTemplate
properties specified in their corresponding stub mappings.

request.urlPathTemplate / WireMock.urlPathTemplate() has no or empty path variable defined

This inspection reports the value of the request.urlPathTemplate property when it has either no path variable defined, or at least one empty (i.e. {}) variable.

JSON

Java

request.urlPathTemplate doesn’t have matching variable name

This inspection reports parameters in request.pathParameters/withPathParam() calls when request.urlPathTemplate/WireMock.urlPathTemplate() doesn’t contain
path variable(s) with those names.

JSON

Java

Generate path parameters from URL path template

This intention action generates

• the request.pathParameters property, or missing path parameters inside it, based on the path variables in the request.urlPathTemplate property.
• withPathParam() calls for each path variable that doesn’t have such call, based on the path variables in WireMock.urlPathTemplate()

It presumes that path variables are defined with arbitrary names enclosed by { and } curly braces.

See WireMock 3 path templates documentation.

JSON

Generate pathParameters

If request.pathParameters doesn’t exist for a given stub mapping, it is generated along with the parameters, right after request.urlPathTemplate.

From:

{
  "request": {
    "method": "GET",
    "urlPathTemplate": "/v1/{some}/path/{parameter}"
  },
  ...
}

to:

{
  "request": {
    "method": "GET",
    "urlPathTemplate": "/v1/{some}/path/{parameter}",
    "pathParameters": {
      "some": {
      },
      "parameter": {
      }
    }
  },
  ...
}

Generate all or missing parameters

If request.pathParameters do exist, only the parameters that are not yet defined in it, are generated. They are generated at the beginning of pathParameters, and in the same order as the parameters occur in urlPathTemplate, and only one instance of each of them.

From:

{
  "request": {
    "method": "GET",
    "urlPathTemplate": "/v1/{some}/path/{parameter}",
    "pathParameters": {
      "parameter": {
        "equalTo": "value"
      }
    }
  },
  ...
}

to:

{
  "request": {
    "method": "GET",
    "urlPathTemplate": "/v1/{some}/path/{parameter}",
    "pathParameters": {
      "some": {
      },
      "parameter": {
        "equalTo": "value"
      }
    }
  },
  ...
}

Java

The idea is the same as for the JSON part of this feature. The calls are generated right after urlPathTemplate(), and in the same order as the parameters occur in it, and only one instance of each of them.

From:

stubFor(get(urlPathTemplate("/v1/{some}/path/{parameter}"))
    .willReturn(ok()));

to:

stubFor(get(urlPathTemplate("/v1/{some}/path/{parameter}"))
    .withPathParam("some", WireMock.equalTo(""))
    .withPathParam("parameter", WireMock.equalTo(""))
    .willReturn(ok()));

Suspicious use of regex symbols in request URL and URL path matching

During request matching multiple approaches can be used to match URLs and URL paths.
Users may run into the case when the specified URL or path can’t be used with the specified used matching approach, and during test execution the request doesn’t match one or more requests.

To prevent such issues, URLs and URL paths that are specified as potential regular expressions are reported, so that the matching approach can be fixed if necessary.

The followings are reported:

• In JSON
  • request.url property values containing any of []{}.*+^$\|
  • request.urlPath property values containing any of ()[]{}.*?+^$\|
    • This check is disabled for all mapping files when the wiremock-grpc-extension is available in the project. The fully qualified name of the grpc service requires the dot symbol to be used.
• In Java
  • WireMock.urlEqualTo() call arguments containing any of []{}.*+^$\|
  • WireMock.urlPathEqualTo() call arguments containing any of ()[]{}.*?+^$\|

To prevent false positives:

• Exact url and url path matching excludes the . (dot) symbol because the value may point to an actual file with its extension.
• Exact url matching excludes the check for (, ) and ? symbols, because they can be used as part of the query parameters.

Issues with the EqualToXmlPattern configuration

This inspection validates the configuration and content of the equalToXml pattern in the request.bodyPatterns.equalToXml
and request.multipartPatterns.bodyPatterns.equalToXml JSON properties, as well as in the arguments of WireMock.equalToXml() calls.

JSON

The following issues with their corresponding quick fixes are reported and available:

• the pattern contains an XmlUnit placeholder but placeholders are not enabled (enablePlaceholders is either missing or is set to false). The quick fix will Enable placeholders like this:

{ "equalToXml": "<message>${xmlunit.isDateTime}</message>" }

{ "equalToXml": "<message>${xmlunit.isDateTime}</message>", "enablePlaceholders": true }

• the pattern doesn’t contain XmlUnit placeholder but placeholders are enabled. In that case it doesn’t really make sense to use XmlUnit’s placeholder specific difference evaluator. The quick fix will Disable placeholders like this:

{ "equalToXml": "<message>message with no placeholder</message>", "enablePlaceholders": true }

{ "equalToXml": "<message>message with no placeholder</message>" }

Java

The following issues with their corresponding quick fixes are reported and available:

• the pattern contains an XmlUnit placeholder but placeholders are not enabled (enablePlaceholders is either missing or is set to false). The quick fix will Enable placeholders like this:

WireMock.equalToXml("<message>${xmlunit.isDateTime}</message>")
WireMock.equalToXml("<message>${xmlunit.isDateTime}</message>", false)

WireMock.equalToXml("<message>${xmlunit.isDateTime}</message>", true)

• the pattern doesn’t contain XmlUnit placeholder but placeholders are enabled. In that case it doesn’t really make sense to use XmlUnit’s placeholder specific difference evaluator. The quick fix will Disable placeholders like this:

WireMock.equalToXml("<message>message with no placeholder</message>", true)

WireMock.equalToXml("<message>message with no placeholder</message>")

Custom request matcher validation

state-matcher from wiremock-state-extension

The wiremock-state-extension provides a custom matcher called state-matcher for which the following validations are in place:

Criteria	Screenshot
Either only one of hasContext or hasNotContext must be specified, but not both.

GRPC service call reference validation

This inspection includes the following validations regarding request url specifications for GRPC service calls:

• When the value of a request.url* (except urlPath) matches the GRPC service call pattern specified by the wiremock-grpc-extension, and the corresponding request method is POST.

• When the value of a request.urlPath property matches the GRPC service call pattern, but the corresponding request method is not set to POST.

Navigation to GRPC service implementation

For users of the wiremock-grpc-extension, a line marker is available on the request.urlPath property of JSON mapping files to navigate to the service implementation Java class or the service declaration in a .proto file.
The line marker is available when the request method is POST, and either the implementation or the declaration is found. Upon clicking on the gutter icon, the list of resolved elements are shown with on or more items:

• the service Java class (the FQN of the service + the string Grpc) when it can be resolved,
• zero or more .proto service declarations depending on how many match the FQN of the service.

Completion of GRPC service methods

Code completion items are provided for GRPC service methods in the request.urlPath property in JSON mapping files
at /[service FQN]/<caret>.

They are available when the wiremock-grpc-extension is configured in the project, and the corresponding request method is POST.