Request matching¶
A stub answers a request when every condition in its request object holds. Conditions that are not set do not
restrict anything: {"request": {}} matches every request. This page lists every condition, the string and body
matchers they use, how FastMock picks one stub when several match, and the limits that keep matching cheap.
- A complete example
- Method and URL
- Query parameters, headers and cookies
- Host, port, scheme and basic authentication
- Form parameters
- Multipart parts
- String matchers
- Body matchers
- GraphQL
- Which stub wins
- Near misses
- Limits
A complete example¶
{
"name": "create invoice",
"priority": 3,
"request": {
"method": "POST",
"urlPathTemplate": "/api/{version}/invoices",
"pathParams": {"version": {"matches": "v[12]"}},
"query": {"tenant": {"equalTo": "acme"}, "debug": {"absent": true}},
"headers": {"content-type": {"contains": "json"}, "x-trace-id": {}},
"cookies": {"session": {"matches": "s-[0-9]+"}},
"host": {"equalTo": "billing.example.com"},
"scheme": "https",
"body": [
{"jsonPath": "$.amount", "value": {"matches": "[0-9]+(\\.[0-9]{2})?"}},
{"equalToJson": {"currency": "EUR", "lines": "${json-unit.ignore}"}, "ignoreExtraElements": true}
]
},
"response": {"status": 201, "jsonBody": {"id": "{{uuid}}"}}
}
curl -X POST http://localhost:9090/__admin/stubs \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'content-type: application/json' \
-d @invoice-stub.json
Method and URL¶
| Field | Matches |
|---|---|
method |
The HTTP method, case-insensitive. ANY or no method matches every method. |
url |
Path and query string exactly, as sent: /search?q=a%20b&page=2. Parameter order matters. |
urlPattern |
An anchored regular expression over path and query string: /search\\?q=.*. |
urlPath |
The path exactly; the query string is ignored. |
urlPathPattern |
An anchored regular expression over the path. |
urlPathTemplate |
A path template: /users/{id}, /report.{format}, /v1/{name}:cancel, /files/{rest...}. |
pathParams |
String matchers for the template parameters; needs urlPathTemplate. |
Use at most one of url, urlPattern, urlPath, urlPathPattern and urlPathTemplate. Paths are
percent-decoded before matching, except %2F, which stays encoded so it cannot create a new path segment. For url
and urlPattern the query string is used exactly as the client sent it (not decoded, not reordered).
Regular expressions are anchored: "urlPathPattern": "/a/\\d+" matches /a/12 and not /x/a/12. They use the
Rust regex syntax (no look-around, no back-references), which guarantees linear-time matching.
Query parameters, headers and cookies¶
query, headers and cookies map a name to a string matcher.
{
"request": {
"query": {"id": {"hasExactly": [{"equalTo": "1"}, {"equalTo": "2"}]}, "sort": {"equalTo": "asc"}},
"headers": {"accept": {"contains": "json"}, "authorization": {"absent": true}},
"cookies": {"session": {"matches": "s-[0-9]+"}, "theme": {"or": [{"absent": true}, {"equalTo": "dark"}]}}
}
}
- Header names are case-insensitive; query parameter and cookie names are case-sensitive.
- A name can appear several times (
?id=1&id=2, twoacceptlines, two cookies with the same name). A single-value matcher passes when any value passes;absentpasses when there is no value at all; the multi-value matchershasExactlyandincludessee all values (see Multi-value matchers). - Cookies are read from every
Cookieheader (a=1; b=2); surrounding quotes of a value are removed. - An empty matcher
{}means "present with any value".
Host, port, scheme and basic authentication¶
{
"request": {
"host": {"equalTo": "api.example.com"},
"port": 8443,
"scheme": "https",
"basicAuth": {"username": "partner", "password": "s3cret"}
}
}
| Field | Matches |
|---|---|
host |
A string matcher on the host name from the Host header (HTTP/1.1) or :authority (HTTP/2), without the port, compared case-insensitively. |
port |
The port from Host/:authority; when the client sent none, the data port FastMock listens on (FASTMOCK_LISTEN), else 80 or 443 by scheme. |
scheme |
http or https. The data port is https when FASTMOCK_TLS_CERT_FILE and FASTMOCK_TLS_KEY_FILE are set. |
basicAuth |
Authorization: Basic ... with exactly this user name and password. |
basicAuth stores the password in the stub. Viewers see stubs too, so use a test-only credential.
Form parameters¶
formParameters matches fields of an application/x-www-form-urlencoded body. Bodies with any other content type
have no form parameters, so every non-absent matcher fails.
{
"request": {
"method": "POST",
"urlPath": "/oauth/token",
"formParameters": {
"grant_type": {"equalTo": "client_credentials"},
"scope": {"includes": [{"equalTo": "read"}, {"equalTo": "write"}]}
}
},
"response": {"jsonBody": {"access_token": "{{randomValue length=32}}", "token_type": "Bearer"}}
}
Names and values are URL-decoded (+ is a space). At most 10,000 fields are read from one body.
Multipart parts¶
multipart matches the parts of a multipart/* body (usually multipart/form-data).
{
"request": {
"method": "POST",
"urlPath": "/documents",
"multipartMatchingType": "ANY",
"multipart": [
{"name": "meta", "body": [{"jsonPath": "$.kind", "value": {"equalTo": "invoice"}}]},
{"filename": {"matches": ".*\\.pdf"}, "headers": {"content-type": {"equalTo": "application/pdf"}}, "body": [{"contains": "%PDF"}]}
]
},
"response": {"status": 201}
}
| Field | Meaning |
|---|---|
name |
The name of the part's Content-Disposition, exactly. |
filename |
String matcher on the filename of Content-Disposition. |
headers |
String matchers on the part's own headers (names case-insensitive). |
body |
Body matchers applied to the part's content. |
multipartMatchingType decides how patterns and parts combine:
ANY(default): every pattern must match at least one part.ALL: every part must match every pattern (and the body must have at least one part).
A request that is not multipart, has no boundary, is malformed or has more than 64 parts matches no multipart pattern. A stub may have at most 16 multipart patterns.
curl -X POST localhost:8080/documents \
-F 'meta={"kind":"invoice"};type=application/json' -F 'file=@invoice.pdf;type=application/pdf'
String matchers¶
A string matcher is an object; every field that is set must hold.
| Field | Meaning |
|---|---|
equalTo |
The value equals the text. |
contains |
The value contains the text. |
matches |
The value matches the anchored regular expression. |
doesNotMatch |
The value does not match the anchored regular expression. |
caseInsensitive |
true makes equalTo, contains, matches and doesNotMatch ignore case. |
absent |
true: the value must be missing. false: it must be present. |
and |
A list of string matchers that must all hold. |
or |
A list of string matchers of which at least one must hold. |
not |
A string matcher that must not hold. |
before, after, equalToDateTime |
Date-time comparisons, see below. |
actualFormat, truncateExpected, truncateActual |
Options of the date-time comparisons. |
hasExactly, includes, allValues |
Multi-value matchers, see below. |
{} means "present". A missing value only satisfies absent: true, or a matcher made only of and/or/not
whose logic accepts a missing value: {"or": [{"absent": true}, {"equalTo": "1"}]} means "missing or 1", and
{"not": {"equalTo": "x"}} also accepts a missing value.
Combining matchers¶
{
"headers": {
"x-client": {
"or": [
{"equalTo": "mobile"},
{"and": [{"matches": "web-.*"}, {"not": {"contains": "beta"}}]}
]
}
}
}
Nesting is limited to 8 levels, and a stub may contain at most 256 matcher nodes in total (every string matcher, nested matcher, body matcher and multipart pattern counts as one node).
Date-time matchers¶
before, after and equalToDateTime compare the value as a point in time with an expected time. The expected
time is either an ISO-8601 date-time, now, or one of them followed by an offset:
| Expected | Meaning |
|---|---|
2026-06-01T00:00:00Z |
A fixed instant (a time without zone is UTC; a date alone is midnight UTC). |
now |
The time the request is matched. |
now +3 days, now -1 hours, now +30 minutes |
Offset from now. Units: seconds, minutes, hours, days, weeks, months, years (singular too; also ms, s, h, d). |
2026-06-01T00:00:00Z +2 hours |
Offset from a fixed instant. |
{
"query": {"from": {"after": "now -30 days", "before": "now"}},
"headers": {"if-modified-since": {"before": "2026-01-01T00:00:00Z"}},
"body": [{"jsonPath": "$.expires", "value": {"after": "now +1 days", "truncateActual": "first day of month"}}]
}
Without actualFormat the value may be RFC 3339 / ISO-8601 (with or without zone, with T or a space), an HTTP
date (Tue, 15 Nov 1994 08:12:31 GMT) or a plain date. actualFormat parses a different format:
actualFormat |
Value |
|---|---|
unix or epoch |
Seconds since 1970-01-01 UTC. |
epochMillis |
Milliseconds since 1970-01-01 UTC. |
A Java pattern: dd/MM/yyyy, yyyy-MM-dd'T'HH:mm:ssXXX |
Letters y M d D H h k m s S E a Z X x z w e c; text in '...'. |
A strftime pattern (contains %): %d.%m.%Y %H:%M |
As in chrono. |
truncateExpected and truncateActual round the expected or the actual time down before comparing: first second
of minute, first minute of hour, first hour of day, first day of month, first day of next month, last day of
month, first day of year, first day of next year, last day of year (the result is midnight UTC of that day;
the FIRST_DAY_OF_MONTH spelling is accepted too). Example: "issued this month" is
{"equalToDateTime": "now", "truncateExpected": "first day of month", "truncateActual": "first day of month"}.
A value that cannot be parsed never matches. actualFormat/truncate* without a date-time comparison, an unknown
unit and an unparsable expected time are rejected when the stub is saved.
Multi-value matchers¶
hasExactly, includes and allValues see every value of a repeated query parameter, header, cookie or form
field (and every result of a jsonPath or xpath body matcher):
includes: [m1, m2]: each matcher matches at least one value; other values are allowed.hasExactly: [m1, m2]: there are exactly as many values as matchers and each value is matched by a different matcher (any order).allValues: [m1, m2]: there is at least one value and every value is matched by at least one of the matchers (MockServerkeyMatchStyle: MATCHING_KEY):{"allValues": [{"matches": "[0-9]"}]}accepts?id=1&id=2and rejects?id=1&id=x.
{"query": {"tag": {"includes": [{"equalTo": "red"}]}, "id": {"hasExactly": [{"equalTo": "1"}, {"matches": "[0-9]+"}]}}}
?tag=blue&tag=red&id=7&id=1 matches; ?tag=red&id=1&id=2&id=3 does not (three ids). A multi-value matcher cannot be
combined with other fields in the same object, and its list must not be empty.
Body matchers¶
body is a list; every entry must match. Each entry sets exactly one of the fields below, plus the options that
belong to it and negate (true inverts the result).
| Field | Matches |
|---|---|
equalTo |
The body text equals the string. |
contains |
The body text contains the string. |
matches |
The body text matches the anchored regular expression (use (?s) to let . cross lines). |
equalToJson |
The JSON body equals this JSON value; options ignoreExtraElements, ignoreExtraArrayItems, ignoreArrayOrder, enablePlaceholders. |
jsonPath |
The JSONPath selects something; with value, a string matcher must accept one of the results; with valueBody, a body matcher must accept one of them. Option jsonPathDialect. |
jsonSchema |
The JSON body is valid against this JSON Schema (formats are checked). |
xpath |
The XPath selects something; with value a string matcher (or with valueBody a body matcher) must accept one of the results; option xpathNamespaces. |
equalToXml |
The XML body is semantically equal; options exemptedComparisons, enablePlaceholders. |
binaryEqualTo |
The raw body bytes equal this base64 value. |
absent |
true: the body is empty. |
equalToJson¶
Numbers compare by value (6 equals 6.0; big integers compare exactly). By default objects must have the same
keys and arrays the same elements in the same order.
ignoreExtraElements: true: the request may have more object keys than expected (arrays keep their length).ignoreExtraArrayItems: true: an array of the request may have more elements than expected. In order, the expected elements must be a prefix of the actual ones; withignoreArrayOrder, every expected element needs its own matching actual element. The WireMock importer sets it together withignoreExtraElements, as WireMock does; MockServer's defaultONLY_MATCHING_FIELDSsets both andignoreArrayOrder.ignoreArrayOrder: true: array elements may come in any order (lengths must match unlessignoreExtraArrayItemsis set).- Placeholders (on unless
enablePlaceholders: false) stand for values in the expected JSON:
| Placeholder | Accepts |
|---|---|
${json-unit.any-string} |
any string |
${json-unit.any-number} |
any number |
${json-unit.any-boolean} |
true or false |
${json-unit.ignore} |
any value, but the key must be present |
${json-unit.ignore-element} |
any value, and the key may be missing |
${json-unit.regex}[A-Z]{2}\\d+ |
a string (or number/boolean as text) matching the anchored regex |
{
"body": [{
"equalToJson": {"id": "${json-unit.any-number}", "code": "${json-unit.regex}[A-Z]{3}", "tags": ["b", "a"], "meta": "${json-unit.ignore}"},
"ignoreArrayOrder": true
}]
}
equalToJson and jsonSchema need a JSON body of at most 200,000 JSON nodes; larger or invalid bodies do not match.
jsonPath¶
The expression follows RFC 9535 ($.items[?@.qty > 1].sku, length(@.tags) == 2, match(@.name, 'Req.*')). With
value, a string matcher must accept one of the selected values (objects and arrays as JSON text); with value
{"absent": true}, the path must select nothing. With valueBody, a body matcher (equalToJson, jsonSchema,
equalToXml, ...) must accept one of the selected values; with several results, the array of all of them is tried
too:
{"body": [{"jsonPath": "$.items[0]", "valueBody": {"equalToJson": {"sku": "A"}, "ignoreExtraElements": true}}]}
jsonPathDialect: "jayway" evaluates the expression the way WireMock and MockServer (Jayway JsonPath) do; their
importers set it. It accepts [?(@.name =~ /Req.*/i)], [?(@.status in ['A','B'])], nin, size,
empty true|false, @.items.length() and .size() inside filters, the trailing functions length(), size(),
min(), max(), avg(), sum(), stddev(), keys(), first(), last() ($.items.length() with
value: {"equalTo": "2"}), member names with -, and a filter applied to an object tests the object itself
($.order[?(@.qty > 1)] matches {"order": {"qty": 2}}). contains, subsetof, anyof and noneof are not
supported: the stub is rejected, and an import skips that mapping with a warning that names it.
xpath¶
XPath 1.0 location paths: /a/b, //b, *, @attr, text(), predicates [n], [@a='v'], [child='v'],
[@a]. Without xpathNamespaces names are compared by local name, so prefixes in the expression and the document
do not matter. With xpathNamespaces a prefixed step only matches elements in that namespace:
{
"body": [{
"xpath": "//b:msisdn",
"xpathNamespaces": {"b": "urn:balance"},
"value": {"matches": "380[0-9]{9}"}
}]
}
An unknown prefix is rejected when the stub is saved. Documents with a DTD are refused.
equalToXml¶
The request body is compared with the expected document by structure, not by text:
- whitespace around text and between elements, comments, processing instructions and the XML declaration are ignored;
- attribute order and namespace prefixes do not matter (namespace URIs do);
- child elements are compared in order.
{
"body": [{
"equalToXml": "<o:order xmlns:o=\"urn:orders\" id=\"${xmlunit.ignore}\"><o:item>${xmlunit.matchesRegex([A-Z]{3}-[0-9]+)}</o:item></o:order>",
"exemptedComparisons": ["CHILD_NODELIST_SEQUENCE"]
}]
}
Placeholders (on unless enablePlaceholders: false) can be a whole attribute value or a whole text node:
${xmlunit.ignore}, ${xmlunit.isNumber}, ${xmlunit.isDateTime}, ${xmlunit.matchesRegex(<regex>)}.
exemptedComparisons switches comparisons off:
| Value | Effect |
|---|---|
CHILD_NODELIST_SEQUENCE |
Child elements may come in any order. |
CHILD_NODELIST_LENGTH, CHILD_LOOKUP |
The request may have extra child nodes. |
ELEMENT_TAG_NAME |
Element names are not compared. |
NAMESPACE_URI |
Namespace URIs of elements and attributes are not compared. |
ATTR_VALUE |
Attribute values are not compared. |
ATTR_NAME_LOOKUP, ELEMENT_NUM_ATTRIBUTES |
The request may have extra or missing attributes. |
TEXT_VALUE |
Text content is not compared. |
SCHEMA_LOCATION, NO_NAMESPACE_SCHEMA_LOCATION |
xsi:schemaLocation / xsi:noNamespaceSchemaLocation are ignored. |
NAMESPACE_PREFIX, XML_VERSION, XML_STANDALONE, XML_ENCODING, HAS_DOCTYPE_DECLARATION, DOCTYPE_NAME, DOCTYPE_PUBLIC_ID, DOCTYPE_SYSTEM_ID, COMMENT_VALUE, PROCESSING_INSTRUCTION_TARGET, PROCESSING_INSTRUCTION_DATA, NODE_TYPE |
Accepted; these are never compared anyway. |
Unknown names, invalid expected XML and more than 64 regex placeholders are rejected when the stub is saved. Both
documents are limited to 100,000 nodes and 256 levels; deeper or bigger request bodies do not match. Unordered
comparison (CHILD_NODELIST_SEQUENCE) is used for up to 10,000 element pairs per level and falls back to ordered
comparison beyond that; one comparison visits at most 500,000 elements, a bigger comparison does not match.
binaryEqualTo and absent¶
GraphQL¶
graphql matches GraphQL-over-HTTP requests with a JSON body {"query": ..., "operationName": ...}:
| Field | Matches |
|---|---|
operationName |
String matcher on operationName. |
query |
String matcher on the query text. |
rootField |
String matcher on the root fields of the selected operation (any root field may match; includes/hasExactly see all of them). |
Which stub wins¶
- Stubs that are disabled, expired (
expiresAt,ttlSeconds) or used up (times) are skipped; see Stub lifecycle. - Lower
priorityfirst (default 5). - At equal priority, stubs with an
ordercome first, lowerorderfirst, and their URL condition is not compared. The WireMock and MockServer importers setorderto reproduce those tools (Stub lifecycle); you can set it on any stub. - For stubs without
order, the more specific URL condition first:urlPathandurl; thenurlPathTemplatewith fewer parameters; then templates with{rest...}; thenurlPathPatternandurlPattern; then no URL condition. - Then the most recently changed stub.
Scenario state (requiredState) is checked after the request matched; a stub in the wrong state lets the next stub
try. The full order is evaluated for every request.
Near misses¶
Unmatched requests get 404 {"error": "no stub matched", ...}; with FASTMOCK_UNMATCHED_DETAILS=true the body
includes the three closest stubs. The admin API explains any request on demand:
curl -X POST http://localhost:9090/__admin/requests/near-misses \
-H "Authorization: Bearer $FASTMOCK_TOKEN" -H 'content-type: application/json' \
-d '{"method": "POST", "path": "/login", "headers": {"cookie": "session=x"}, "body": "user=ann"}'
{
"nearMisses": [{
"stubId": "0193f3a4-6a43-7c1b-9d0e-9c4f6b1d2e11",
"name": "login",
"score": 0.6,
"mismatches": ["cookie `session` does not match", "form parameter `user` does not match"]
}]
}
The score is the share of conditions that hold: method counts 1, the URL 2, and every scheme, port, host, basic authentication, path parameter, query parameter, header, cookie, form parameter, multipart block, body matcher and GraphQL root field 1.
Limits¶
| Limit | Value | When exceeded |
|---|---|---|
| Matchers per stub (query, headers, cookies, path params, form fields, body matchers, multipart pattern contents, host, basic auth, GraphQL root field) | 64 | stub rejected |
Matcher nodes per stub, including nested and/or/not/hasExactly/includes |
256 | stub rejected |
| Nesting depth of string matchers | 8 | stub rejected |
| Multipart patterns per stub | 16 | stub rejected |
| Compiled size of one regular expression | 256 KiB | stub rejected |
Regex placeholders per equalToJson / equalToXml |
64 | stub rejected |
xpathNamespaces entries |
32 | stub rejected |
| JSON nodes parsed from a request body | 200,000 | JSON matchers do not match |
| XML nodes / depth | 100,000 / 256 | XML matchers do not match |
| Text collected by one XPath expression | 2 MiB over all results | the rest of the text is not collected |
Element comparisons in one equalToJson with ignoreArrayOrder |
2,000,000 | the body does not match |
Element comparisons in one equalToXml |
500,000 | the body does not match |
| Parts read from a multipart body | 64 | multipart patterns do not match |
| Cookies read from a request | 256 | the rest is ignored |
| Form fields read from a body | 10,000 | the rest is ignored |
Stubs that break a rule are rejected by POST /__admin/stubs, PUT /__admin/stubs/{id} and
POST /__admin/stubs/validate with 400 {"error": "..."} naming the problem.