Skip to main content

Primitive values

Matching Rule Definition Expressions

Test expectations (requests, responses or messages) setup via plugins use matching rule expressions to configure the rules and values required for the test. Each definition can contain a number of expressions, separated by a comma. Whitespace is ignored.

Primitive (or scalar) values can be strings (quoted with single quotes), numbers, booleans or null.


The main types of expressions are one of the following:

matching(TYPE [, CONFIG], EXAMPLE) or matching($'NAME')

Expression that defines a matching rule. Each matching rule requires the type of matching rule, and can contain an optional configuration value. The final value is the example value to use.

Supported matching rules:

RuleDescriptionConfig ValueExample
equalToValue must be equal to the examplematching(equalTo, 'Example value')
typeValue must be the same type as the examplematching(type, 'Example value')
numberValue must be a numeric valuematching(number, 100.09)
integerValue must be an integer value (no decimals)matching(integer, 100)
decimalValue must be a decimal number (must have at least one significant figure after the decimal point)matching(decimal, 100.01)
datetimeValue must match a date-time format stringFormat Stringmatching(datetime, 'yyyy-MM-dd HH:mm:ssZZZZZ', '2020-05-21 16:44:32+10:00')
dateValue must match a date format stringFormat Stringmatching(date, 'yyyy-MM-dd', '2020-05-21')
timeValue must match a time format stringFormat Stringmatching(time, 'HH:mm', '22:04')
regexValue must match a regular expressionRegular expressionmatching(regex, '\\w{3}\\d+', 'abc123')
includeValue must include the example value as a substringmatching(include, 'testing')
booleanValue must be a booleanmatching(boolean, true)
semverValue must match the semver specificationmatching(semver, '1.0.0')
contentTypeValue must be of the provided content type. This will preform a magic test on the bytes of the value.Content typematching(contentType, 'application/xml', '<?xml?><test/>')

The final form is a reference to another key. This is used to setup type matching using an example value, and is normally used for collections. The name of the key must be a string value in single quotes.

For example, to configure a type matcher where each value in a list must match the definition of a person:

"pact:match": "eachValue(matching($'person'))",
"person": {
"name": "Fred",
"age": 100


Expression that defines the value the same type as the example, must be present and not empty. This is used to defined required fields.

Example: notEmpty('test')


Configures a matching rule to be applied to each key in a map.

For example: eachKey(matching(regex, '\$(\.\w+)+', '$'))


Configures a matching rule to be applied to each value in a map or list.

For example: eachValue(matching(type, 100))


Configures a type matching rule to be applied to a map or list (if another rule is not applied), and asserts the length is at least the given size.

For example: atLeast(2)


Configures a type matching rule to be applied to a map or list (if another rule is not applied), and asserts the length is at most the given size. If an expression is provided, that will be used instead of the type matching rule.

For example: atMost(2)

Composing expressions

Expressions can be composed by separating them with a comma. For example atLeast(2), atMost(10), eachValue(matching(regex, '\d+', '1234')). This will configure an array to have at least 2 items, at most 10, and each item in the array must match the given regex.


There is a grammar for the definitions in ANTLR4 format.