Verifications

The MockServer Proxy allows the verification of requests by specifying:

an amount of a single type of request
a sequence of requests that is verified in order

Verifying Repeating Requests

To verify that a request has been sent use the verify method of the ProxyClient as follows:

new ProxyClient("localhost", 1090).verify(
        request()
                .withMethod("POST")
                .withPath("/login")
                .withBody(exact("{username: 'foo', password: 'bar'}"))
                .withCookies(
                        new Cookie("sessionId", ".*")
                ),
        VerificationTimes.exactly(1)
);

The org.mockserver.verify.VerificationTimes class is used to specify how many times you want MockServer to match a request:

To create an instance of VerificationTimes use one of the static factory methods:

VerificationTimes.once();
VerificationTimes.exactly(int count);
VerificationTimes.atLeast(int count);

Verifying Request Sequences

To verify that the system under test has sent a sequence of requests to MockServer use the verify method of the MockServerClient as follows:

new ProxyClient("localhost", 1090).verify(
        request()
                .withMethod("POST")
                .withPath("/login")
                .withBody(exact("{username: 'foo', password: 'bar'}"))
                .withCookies(
                        new Cookie("sessionId", ".*")
                ),
        request()
                .withMethod("POST")
                .withPath("/deposit")
                .withBody(exact("{acccount: '123456789', card: '1234 5678 9012 3456', amount: '10.00'}"))
                .withCookies(
                        new Cookie("sessionId", ".*")
                ),
        request()
                .withMethod("POST")
                .withPath("/logout")
                .withCookies(
                        new Cookie("sessionId", ".*")
                )
);

The each request in the sequence will be verified to have been received at least once, in the exact order specified.

The mockserver-example project contains an example test called BookPageIntegrationTest that demonstrates a fully working example.

Request Matchers

For each verification a request matcher is used to specify how and what should be verified.

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"
            ]
        }"
    }
}