Requests can be matched on:

  • method - plain text or regular expression
  • path - plain text or regular expression
  • query string - plain text or regular expression
  • headers - plain text or regular expression
  • cookies - plain text or regular expression
  • body
    • XPath
    • XML
    • XML Schema
    • JSON - supports two match types STRICT and ONLY_MATCHING_FIELDS. STRICT match type matches all fields and the order of arrays. In STRICT match type extra fields will cause the matcher to fail. ONLY_MATCHING_FIELDS match type only matches fields provided in the request matcher.
    • JSON Schema
    • regular expression
    • plain text (i.e. exact match)
    • form fields (i.e. body parameters)
  • secure - true if the request was made using HTTPS
NOT

All matchers for the fields above can also be negated, even the entire request matcher can be negated. When a matched is negated anything except what is specified in the matcher is matched.

For example if a path matcher for "/some/path" is negated by adding a "!" at the start (as follows "!/some/path") then any path except "/some/path" is matched.

Java Request Matcher API

To specify a request matcher in Java use the org.mockserver.model.HttpRequest class which specifies the details of each HTTP response with a fluent API.

For example:

HttpRequest httpRequest =
        request()
                .withMethod("POST")
                .withPath("/login")
                .withBody("{username: 'foo', password: 'bar'}")
                .withQueryStringParameters(
                        new Parameter("returnUrl", "/account")
                )
                .withCookies(
                        new Cookie("sessionId", "2By8LOhBmaW5nZXJwcmludCIlMDAzMW")
                );

JavaScript Request Matcher API

To specify a request matcher in JavaScript use JSON to specify the details with the following format: 

"httpRequest": {
    "method": "",
    "path": "",
    "queryStringParameters": []
    "body": {
       "type": <"STRING" or "REGEX" or "JSON" or "JSON_SCHEMA" or "XPATH" or "PARAMETERS">,
       "value": "" ( or "parameters" as shown in more detail below )
    },
    "cookies": [],
    "headers": [],
}

Note: Only values which are matched on need to be specified, if a value is missing then it will not be matched on. For example, below both the parameters and headers fields are not specified.

Cookies, Headers, Parameters

Each cookie, header or parameter array entry has the following syntax:

{
    "name": "someName",
    "values": ["someValueOne", "someValueTwo", ...]
}

The same example, as in Java above, in JavaScript would be :

"httpRequest": {
    "method": "POST",
    "path": "/login",
    "queryStringParameters": [
        {
            "name": "returnUrl",
            "values": ["/account"]
        }
    ],
    "cookies": [
        {
            "name": "sessionId",
            "values": ["2By8LOhBmaW5nZXJwcmludCIlMDAzMW"]
        }
    ],
    "body": {
        "type": "STRING",
        "value": "{username: 'foo', password: 'bar'}"
    }
}

Bodies

The "type" value in "body" can be:

"STRING"
"REGEX"
"JSON"
"JSON_SCHEMA"
"XPATH"
"PARAMETERS"

When the "type" field has a value of "STRING", "REGEX", "JSON", "JSON_SCHEMA" or "XPATH" the other field of "body"" should be "value" and it should provide a string to perform the match against, as shown in the example above.

Parameter Bodies

When the "type" field has a value of "PARAMETERS" the other field of "body" should be "parameters" and it should provide a list of body parameters using the following syntax:

{
    "name": "someName",
    "values": ["someValueOne", "someValueTwo", ...]
}

For example:

"httpRequest": {
    "method": "POST",
    "path": "/login",
    "queryStringParameters": [
        {
            "name": "returnUrl",
            "values": ["/account"]
        }
    ],
    "cookies": [
        {
            "name": "sessionId",
            "values": ["2By8LOhBmaW5nZXJwcmludCIlMDAzMW"]
        }
    ],
    "body": {
        "type": "PARAMETERS",
        "parameters": [
            {
                "name": "username",
                "values": ["foo"]
            },
            {
                "name": "password",
                "values": ["bar"]
            }
        ]
    }
}

String Body Matcher

When the "type" field has a value of "STRING" a short hand can be used where the "body" is only specified as a string literal for example:

"httpRequest": {
    "method": "POST",
    "path": "/login",
    "queryStringParameters": [
        {
            "name": "returnUrl",
            "values": ["/account"]
        }
    ],
    "cookies": [
        {
            "name": "sessionId",
            "values": ["2By8LOhBmaW5nZXJwcmludCIlMDAzMW"]
        }
    ],
    "body": "a string body showing the short-hand way to specify a simple string body"
}

JSON Object Body Matchers

When the "type" field has a value of "JSON" an additional field can be provided to specify the match type called "matchType".

The JSON expression supports two match types "STRICT" and "ONLY_MATCHING_FIELDS". "STRICT" match type matches all fields and the order of arrays. In "STRICT" match type extra fields will cause the matcher to fail. "ONLY_MATCHING_FIELDS" match type only matches fields provided in the body for the request matcher. "ONLY_MATCHING_FIELDS" match type will match correctly against a request that contains additional fields or a request that contains any array fields those elements are in a different order.

"httpRequest": {
    "method": "POST",
    "path": "/login",
    "body": {
        "type": "JSON",
        "value": "{username: 'foo', password: 'bar'}",
        "matchType": "STRICT"
    }
}

JSON Schema Body Matcher

MockServer supports matching request bodies using JSON Schema, which is useful for matching or validating the format of a JSON object. The detailed syntax of JSON Schema is documented at http://json-schema.org.

To use JSON Schema to match a request body the "type" field should have a value of "JSON_SCHEMA" and the "value" field should contain the JSON Schema as a string value, as follows:

"httpRequest": {
    "method": "POST",
    "path": "/login",
    "body": {
        "type": "JSON_SCHEMA",
        "value": "{
            "type": "object",
            "properties": {
                "username": {
                    "type": "string",
                    "pattern": "^[a-z0-9_-]{3,15}$"
                },
                "password": {
                    "type": "string",
                    "minLength": 8
                }
            },
            "required": [
                "username",
                "password"
            ]
        }"
    }
}