Matching

Matching requests and responses with Pact-JVM

To understand the basic rules of matching, see Matching Gotchas. For example test cases for matching, see the Pact Specification Project, version 2.

By default, Pact-JVM will use string equality matching following Postel's Law. This means that for an actual value to match an expected one, they both must consist of the same sequence of characters. For collections (basically Maps and Lists), they must have the same elements that match in the same sequence, with cases where the additional elements in an actual Map are ignored.

Matching rules can be defined for both request and response elements based on JSON-Path syntax.

Matching Bodies

For the most part, matching involves matching request and response bodies in JSON format. Other formats will either have their own matching rules, or will follow the JSON one.

JSON body matching rules

Bodies consist of Objects (Maps of Key-Value pairs), Arrays (Lists) and values (Strings, Numbers, true, false, null). The following method is used to determine if two bodies match:

1. If both the actual body and expected body are empty, the bodies match.
2. If the actual body is non-empty, and the expected body empty, the bodies match.
3. If the actual body is empty, and the expected body non-empty, the bodies don't match.
4. Otherwise do a comparison on the contents of the bodies.

For the body contents comparison:

1. If the actual and expected values are both Objects, compare as Maps.
2. If the actual and expected values are both Arrays, compare as Lists.
3. If the expected value is an Object, and the actual is not, they don't match.
4. If the expected value is an Array, and the actual is not, they don't match.
5. Otherwise, compare the values

For comparing Maps

1. If the actual map is non-empty while the expected is empty, they don't match.
2. If we allow unexpected keys, and the number of expected keys is greater than the actual keys, they don't match.
3. If we don't allow unexpected keys, and the expected and actual maps don't have the same number of keys, they don't match.
4. Otherwise, for each expected key and value pair:
   1. if the actual map contains the key, compare the values
   2. otherwise they don't match

For comparing lists

Postel's law govers if we allow unexpected keys or not.

Matching Paths

Paths are matched by the following:

1. If there is a matcher defined for $.path, default to that matcher.
2. Otherwise paths are compared as Strings

Matching Queries

1. If the actual and expected query strings are empty, they match.
2. If the actual is not empty while the expected is, they don't match.
3. If the actual is empty while the expected is not, they don't match.
4. Otherwise convert both into a Map of keys mapped to a list values, and compare those.

Matching Query Maps

Query strings are parsed into a Map of keys mapped to lists of values. Key value pairs can be in any order, but when the same key appears more than once the values are compared in the order they appear in the query string.

Matching Headers

Matching Status Codes

Status codes are compared as integer values.