WireMock\u2019s matching model is built around a small set of pattern types that you reuse everywhere: URLs, headers, query parameters, and bodies all use variations of the same abstractions. In this article we\u2019ll build an intuition for those abstractions and then see them in a Java example.<\/p>\n
At the heart of WireMock matching is the idea \u201cgiven some content, decide how well it matches this expectation.\u201d That idea is embodied in ContentPattern<\/strong> and its concrete subclasses.<\/p>\n You rarely construct Rationale:<\/strong> by funnelling everything through StringValuePattern, WireMock can reuse the same matching semantics across URLs, headers, query params, and body fragments, and can assign a distance score<\/em> that lets it pick the best matching stub.<\/p>\n Mini example (headers and query):<\/p>\n Both Headers and query parameters can have multiple values; sometimes you care about the set of values as a whole, not just any one of them. That\u2019s what MultiValuePattern<\/strong> is for.<\/p>\n Conceptually, MultiValuePattern answers: \u201cdoes this list of strings satisfy my condition?\u201d Typical usage for query parameters:<\/p>\n Here:<\/p>\n Rationale:<\/strong> this is important for APIs where order and multiplicity of query or header values matter (e.g. \u201call of these scopes must be present\u201d). Without a dedicated multi-value abstraction you would be forced to encode such logic in brittle string hacks.<\/p>\n WireMock lets you match URLs at several levels in the Java DSL: exact string, regex, or path-only vs path+query. UrlPathPattern<\/strong> corresponds to Key URL matchers in Java:<\/p>\n In modern WireMock 3 you\u2019ll also see templates<\/em> like Rationale:<\/strong> splitting \u201cpath\u201d from \u201cquery\u201d and using distinct matchers lets you:<\/p>\n When the request body is JSON and you care about conditions<\/em> inside it rather than full equality, WireMock uses MatchesJsonPathPattern<\/strong>. You access it via Two main flavours:<\/p>\n Example:<\/p>\n Important detail: all WireMock matchers operate on strings, so the JSONPath result is stringified before applying the StringValuePattern. This even allows selecting a sub-document<\/em> and then matching it with Rationale:<\/strong> JSONPath is ideal when you need to assert that some field exists or meets a condition (e.g. When you do<\/em> want structural equality for JSON, You embed placeholders directly into the expected JSON:<\/p>\n Common placeholders:<\/p>\n You can also change delimiters if Rationale:<\/strong> equalToJson is excellent for enforcing payload shape and fixed fields, but brittle when some fields are inherently variable (IDs, timestamps, correlation IDs). JsonUnit placeholders let you keep strictness where it matters and loosen it where variability is expected.<\/p>\n For more formal validation you can use JSON Schema<\/strong> with matchers like Typical body matcher:<\/p>\n You can also apply Rationale:<\/strong><\/p>\n JSON Schema is especially useful when your WireMock stub is acting as a consumer-driven contract test for another service.<\/p>\n When WireMock\u2019s built-in matchers are not enough, you can implement Custom Matchers<\/strong>. The main extension is The minimal shape:<\/p>\n You then reference it by name in your stub:<\/p>\n There is also a lower\u2011level Rationale:<\/strong> custom matchers are your \u201cescape hatch\u201d for domain\u2011specific logic which would otherwise be contorted into regexes or JSONPath. Examples include:<\/p>\n Below is a Java 17 style example which combines several of the discussed matcher types. You can drop this into a plain Maven\/Gradle project that has What this stub requires:<\/p>\n Using any HTTP client (curl, HTTPie, Postman, Java HTTP client), send:<\/p>\n You should receive a 200 OK with JSON body:<\/p>\n If you break one constraint at a time (e.g. price negative, missing WireMock\u2019s matching model is built around a small set of pattern types that you reuse everywhere: URLs, headers, query parameters, and bodies all use variations of the same abstractions. In this article we\u2019ll build an intuition for those abstractions and then see them in a Java example. The Core Abstractions: ContentPattern and StringValuePattern At the […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[76,96],"tags":[],"_links":{"self":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts\/2162"}],"collection":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=2162"}],"version-history":[{"count":1,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts\/2162\/revisions"}],"predecessor-version":[{"id":2163,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts\/2162\/revisions\/2163"}],"wp:attachment":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=2162"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=2162"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=2162"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}\n
MatchResult<\/code>.\u201d<\/li>\nStringValuePattern<\/code> directly; you use the DSL factory methods that create it for you. These include:<\/p>\n\n
equalTo("foo")<\/code> \u2013 exact match.<\/li>\ncontaining("foo")<\/code> \u2013 substring.<\/li>\nmatching("[A-Z]+")<\/code> \u2013 regular expression.<\/li>\nequalToJson("{...}")<\/code>, equalToXml("<root\/>")<\/code> \u2013 structural equality for JSON\/XML.<\/li>\n<\/ul>\nstubFor(get(urlPathEqualTo("\/search"))\n .withQueryParam("q", equalTo("WireMock"))\n .withHeader("Accept", containing("json"))\n .willReturn(okJson("""{ "result": "ok" }"""))\n);<\/code><\/pre>\nequalTo("WireMock")<\/code> and containing("json")<\/code> are StringValuePattern instances internally.<\/p>\n
\nMultiValuePattern: Matching Lists of Values<\/h2>\n
stubFor(get(urlPathEqualTo("\/items"))\n .withQueryParam("tag", havingExactly("featured", "sale"))\n .willReturn(ok())\n);<\/code><\/pre>\n\n
havingExactly("featured", "sale")<\/code> expresses that the parameter tag<\/code> must have exactly those two values and no others.<\/li>\n
\nUrlPathPattern and URL-Level Matching<\/h2>\n
urlPathMatching(...)<\/code> when you use the Java client.<\/p>\n\n
urlEqualTo("\/path?query=...")<\/code> \u2013 exact match on full path (with query).<\/li>\nurlMatching("regex")<\/code> \u2013 regex on full path (with query).<\/li>\nurlPathEqualTo("\/path")<\/code> \u2013 exact match on path only.<\/li>\nurlPathMatching("regex")<\/code> \u2013 regex on path only.<\/li>\n<\/ul>\nstubFor(get(urlPathMatching("\/users\/([A-Za-z0-9_-]+)\/repos"))\n .willReturn(aResponse()\n .withStatus(200)));<\/code><\/pre>\nurlPathTemplate("\/contacts\/{contactId}")<\/code>, which are easier to read and type-safe at the path level:<\/p>\nstubFor(get(urlPathTemplate("\/contacts\/{contactId}"))\n .willReturn(aResponse()\n .withStatus(200)));<\/code><\/pre>\n\n
urlEqualTo<\/code>, urlPathEqualTo<\/code>) when you want deterministic behaviour (faster, simpler).<\/li>\nurlMatching<\/code>, urlPathMatching<\/code>) when you truly need flexible matching, such as versioned paths or dynamic IDs.<\/li>\n<\/ul>\n
\nMatchesJsonPathPattern: Querying Inside JSON Bodies<\/h2>\n
matchingJsonPath(...)<\/code> in the DSL.<\/p>\n\n
matchingJsonPath("$.message")<\/code> \u2013 body must match the JSONPath (i.e. the expression finds at least one node).<\/li>\nmatchingJsonPath("$.message", equalTo("Hello"))<\/code> \u2013 evaluates JSONPath, converts the result to a string, then matches it with a StringValuePattern.<\/li>\n<\/ul>\nstubFor(post(urlEqualTo("\/api\/message"))\n .withRequestBody(matchingJsonPath("$.message", equalTo("Hello World!")))\n .willReturn(aResponse().withStatus(200))\n);<\/code><\/pre>\nequalToJson(...)<\/code>.<\/p>\nprice > 10<\/code>) without tightly coupling your tests to the entire JSON shape. It makes tests robust to benign changes in unrelated fields.<\/p>\n
\nJsonUnit Placeholders in equalToJson<\/h2>\n
equalToJson<\/code> is your tool, and it is powered by JsonUnit. JsonUnit supports placeholders<\/strong>, which WireMock exposes to let you relax parts of the JSON equality check.<\/p>\nstubFor(post(urlEqualTo("\/orders"))\n .withRequestBody(equalToJson("""\n {\n "id": "${json-unit.any-string}",\n "amount": 123.45,\n "status": "NEW",\n "metadata": "${json-unit.ignore}"\n }\n """))\n .willReturn(ok())\n);<\/code><\/pre>\n\n
${json-unit.ignore}<\/code> \u2013 ignore value and type, just require key presence.<\/li>\n${json-unit.any-string}<\/code> \u2013 value can be any string.<\/li>\n${json-unit.any-number}<\/code> \u2013 any number.<\/li>\n${json-unit.any-boolean}<\/code> \u2013 any boolean.<\/li>\n${json-unit.regex}[A-Z]+<\/code> \u2013 value must match this regex.<\/li>\n<\/ul>\n${<\/code> and }<\/code> clash with your payload conventions.<\/p>\n
\nJSON Schema Matching<\/h2>\n
matchingJsonSchema<\/code>. This checks that the JSON body (or a path variable) conforms to an explicit schema: types, required fields, min\/max, etc.<\/p>\nstubFor(post(urlEqualTo("\/things"))\n .withRequestBody(\n matchingJsonSchema("""\n {\n "$schema": "http:\/\/json-schema.org\/draft-07\/schema#",\n "type": "object",\n "required": ["id", "name"],\n "properties": {\n "id": { "type": "string", "minLength": 2 },\n "name": { "type": "string" },\n "price": { "type": "number", "minimum": 0 }\n },\n "additionalProperties": false\n }\n """)\n )\n .willReturn(created())\n);<\/code><\/pre>\nmatchingJsonSchema<\/code> to path parameters when you use path templates, e.g. constraining userId<\/code> to a specific shape.<\/p>\n\n
\nCustom Matcher: Escaping the Built-in Model<\/h2>\n
RequestMatcherExtension<\/code>, which gives you full control over how a request is matched.<\/p>\nimport com.github.tomakehurst.wiremock.extension.Parameters;\nimport com.github.tomakehurst.wiremock.extension.requestfilter.RequestMatcherExtension;\nimport com.github.tomakehurst.wiremock.http.MatchResult;\nimport com.github.tomakehurst.wiremock.http.Request;\n\npublic class BodyLengthMatcher extends RequestMatcherExtension {\n\n @Override\n public String getName() {\n return "body-too-long";\n }\n\n @Override\n public MatchResult match(Request request, Parameters parameters) {\n int maxLength = parameters.getInt("maxLength");\n boolean tooLong = request.getBody().length > maxLength;\n return MatchResult.of(tooLong);\n }\n}<\/code><\/pre>\nstubFor(requestMatching("body-too-long", Parameters.one("maxLength", 2048))\n .willReturn(aResponse().withStatus(422))\n);<\/code><\/pre>\nValueMatcher<T><\/code> interface that you can use in verification or in some advanced APIs to match arbitrary values, without registering a global extension.<\/p>\n\n
\nPutting It All Together<\/h2>\n
wiremock<\/code> dependencies;<\/p>\nExample: Product API Stub with Multiple Matchers<\/h2>\n
import com.github.tomakehurst.wiremock.WireMockServer;\n\nimport static com.github.tomakehurst.wiremock.client.WireMock.*;\nimport static com.github.tomakehurst.wiremock.core.WireMockConfiguration.wireMockConfig;\n\npublic class ProductApiStub {\n\n public static void main(String[] args) {\n WireMockServer server = new WireMockServer(\n wireMockConfig().port(8080)\n );\n server.start();\n\n configureFor("localhost", 8080);\n registerStubs(server);\n\n Runtime.getRuntime().addShutdownHook(new Thread(server::stop));\n System.out.println("WireMock running at http:\/\/localhost:8080");\n }\n\n private static void registerStubs(WireMockServer server) {\n server.stubFor(post(urlPathTemplate("\/shops\/{shopId}\/products"))\n \/\/ UrlPathTemplate + JSON Schema for path parameter\n .withPathParam("shopId", matchingJsonSchema("""\n {\n "type": "string",\n "minLength": 3,\n "maxLength": 10\n }\n """))\n\n \/\/ MultiValuePattern on query param\n .withQueryParam("tag", havingExactly("featured", "sale"))\n\n \/\/ StringValuePattern: header must match regex\n .withHeader("X-Request-Id", matching("req-[0-9a-f]{8}"))\n\n \/\/ JsonUnit placeholders in equalToJson\n .withRequestBody(equalToJson("""\n {\n "id": "${json-unit.any-string}",\n "name": "Socks",\n "price": 9.99,\n "metadata": "${json-unit.ignore}"\n }\n """))\n\n \/\/ MatchesJsonPathPattern + StringValuePattern\n .withRequestBody(matchingJsonPath("$[?(@.price > 0)]"))\n\n .willReturn(okJson("""\n {\n "status": "ACCEPTED",\n "message": "Product created"\n }\n """)));\n }\n}<\/code><\/pre>\n\n
\/shops\/{shopId}\/products<\/code> where shopId<\/code> is a string 3\u201310 chars long (validated via JSON Schema).<\/li>\n?tag=featured&tag=sale<\/code> and only those values (MultiValuePattern).<\/li>\nX-Request-Id<\/code> must match req-[0-9a-f]{8}<\/code> (regex StringValuePattern).<\/li>\nname<\/code> and price<\/code>, but any string for id<\/code> and anything for metadata<\/code>, thanks to JsonUnit placeholders.<\/li>\n$.price<\/code> is strictly greater than 0.<\/li>\n<\/ul>\nHow to Validate the Example<\/h2>\n
curl -i \\\n -X POST "http:\/\/localhost:8080\/shops\/abc\/products?tag=featured&tag=sale" \\\n -H "Content-Type: application\/json" \\\n -H "X-Request-Id: req-deadbeef" \\\n -d '{\n "id": "any-random-id",\n "name": "Socks",\n "price": 9.99,\n "metadata": { "color": "blue" }\n }'<\/code><\/pre>\n{\n "status": "ACCEPTED",\n "message": "Product created"\n}<\/code><\/pre>\ntag<\/code> value, bad X-Request-Id<\/code> format, too-short shopId<\/code>), the request will no longer match that stub, and you will either hit no stub or some other fallback stub, which is precisely how you verify each matcher behaves as expected.<\/p>\n","protected":false},"excerpt":{"rendered":"