Crates.io | pact_matching |
lib.rs | pact_matching |
version | 1.2.4 |
source | src |
created_at | 2016-06-01 06:58:55.592609 |
updated_at | 2024-06-14 00:07:27.656617 |
description | Pact-Rust support library that implements request and response matching logic |
homepage | https://www.pact.io |
repository | https://github.com/pact-foundation/pact-reference/blob/master/rust/pact_matching |
max_upload_size | |
id | 5255 |
size | 3,043,510 |
This library implements the core matching logic required for matching HTTP requests and responses. It is based on the V3 pact specification.
To use it, add it to your dependencies in your cargo manifest:
[dependencies]
pact_matching = "1.1"
This crate provides three functions: match_request
, match_response
and match_message
. These functions take an
expected and actual request, response or message model from the pact_models
crate, and return a vector of mismatches.
To compare any incoming request, it first needs to be converted to a pact_models::Request
and then can be compared. Same for
any response.
All features are enabled by default
datetime
: Enables support of date and time expressions and generators. This will add the chronos
crate as a dependency.xml
: Enables support for parsing XML documents. This feature will add the sxd-document
crate as a dependency.plugins
: Enables support for using plugins. This feature will add the pact-plugin-driver
crate as a dependency.multipart
: Enables support for MIME multipart bodies. This feature will add the multer
crate as a dependency.The Pact
struct in the pact_models
crate has methods to read and write pact JSON files. It supports all the specification
versions up to V4, but will convert a V1, V1.1 and V2 spec file to the V3 format.
V3 specification matching is supported for both JSON and XML bodies, headers, query strings and request paths.
To understand the basic rules of matching, see Gotchas. For example test cases for matching, see the Pact Specification Project, version 3.
By default, Pact 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 a pseudo JSON-Path syntax.
For the most part, matching involves matching request and response bodies in JSON or XML format. Other formats will either have their own matching rules, or will follow the JSON one.
Bodies consist of Objects (Maps of Key-Value pairs), Arrays (Lists) and values (Strings, Numbers, true, false, null).
Body matching rules are prefixed with $.
.
The following method is used to determine if two bodies match:
Postel's law governs if we allow unexpected keys or not.
Bodies consist of a root element, Elements (Lists with children), Attributes (Maps) and values (Strings).
Body matching rules are prefixed with $.
.
The following method is used to determine if two bodies match:
Start by comparing the root element.
Then, if there are no mismatches:
Attributes are treated as a map of key-value pairs.
Then, for each expected key and value pair:
Postel's law governs if we allow unexpected keys or not. Note for matching paths, attribute names are prefixed with an @
.
Then, for each expected and actual element pair, compare them using the rules for comparing elements.
Text nodes are combined into a single string and then compared as values.
If there is a matcher defined that matches the path to the text node (text node paths end with #text
), default to that
matcher
Otherwise compare the text using equality.
Paths are matched by the following:
path
, default to that matcher.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.
For matching header values:
header.<HEADER_KEY>
, default to that matcherRequest headers are matched by excluding the cookie header.
If the list of expected cookies contains all the actual cookies, the cookies match.
Status codes are compared as integer values.
The actual and expected methods are compared as case-insensitive strings.
Pact supports extending the matching rules on each type of object (Request or Response) with a matchingRules
element in the pact file.
This is a map of JSON path strings to a matcher. When an item is being compared, if there is an entry in the matching
rules that corresponds to the path to the item, the comparison will be delegated to the defined matcher. Note that the
matching rules cascade, so a rule can be specified on a value and will apply to all children of that value.
Pact does not support the full JSON path expressions, only ones that match the following rules:
$
), representing the root..
), except array indices which use square brackets ([]
).*
) can be used to match all keys of a map or all items of an array (one level only).So the expression $.item1.level[2].id
will match the highlighted item in the following body:
{
"item1": {
"level": [
{
"id": 100
},
{
"id": 101
},
{
"id": 102 // <---- $.item1.level[2].id
},
{
"id": 103
}
]
}
}
while $.*.level[*].id
will match all the ids of all the levels for all items.
Due to the star notation, there can be multiple matcher paths defined that correspond to an item. The first, most specific expression is selected by assigning weightings to each path element and taking the product of the weightings. The matcher with the path with the largest weighting is used.
$
) is assigned the value 2.*
) that matches a property or array index is assigned the value 1.So for the body with highlighted item:
{
"item1": {
"level": [
{
"id": 100
},
{
"id": 101
},
{
"id": 102 // <--- Item under consideration
},
{
"id": 103
}
]
}
}
The expressions will have the following weightings:
expression | weighting calculation | weighting |
---|---|---|
$ | $(2) | 2 |
$.item1 | $(2).item1(2) | 4 |
$.item2 | $(2).item2(0) | 0 |
$.item1.level | $(2).item1(2).level(2) | 8 |
$.item1.level[1] | $(2).item1(2).level(2)[1(2)] | 16 |
$.item1.level[1].id | $(2).item1(2).level(2)[1(2)].id(2) | 32 |
$.item1.level[1].name | $(2).item1(2).level(2)[1(2)].name(0) | 0 |
$.item1.level[2] | $(2).item1(2).level(2)[2(0)] | 0 |
$.item1.level[2].id | $(2).item1(2).level(2)[2(0)].id(2) | 0 |
$.item1.level[*].id | $(2).item1(2).level(2)[*(1)].id(2) | 16 |
$.*.level[*].id | $(2).(1).level(2)[(1)].id(2) | 8 |
So for the item with id 102, the matcher with path $.item1.level[1].id
and weighting 32 will be selected.
The following matchers are supported:
matcher | Spec Version | example configuration | description |
---|---|---|---|
Equality | V1 | { "match": "equality" } |
This is the default matcher, and relies on the equals operator |
Regex | V2 | { "match": "regex", "regex": "\\d+" } |
This executes a regular expression match against the string representation of a values. |
Type | V2 | { "match": "type" } |
This executes a type based match against the values, that is, they are equal if they are the same type. |
MinType | V2 | { "match": "type", "min": 2 } |
This executes a type based match against the values, that is, they are equal if they are the same type. In addition, if the values represent a collection, the length of the actual value is compared against the minimum. |
MaxType | V2 | { "match": "type", "max": 10 } |
This executes a type based match against the values, that is, they are equal if they are the same type. In addition, if the values represent a collection, the length of the actual value is compared against the maximum. |
MinMaxType | V2 | { "match": "type", "max": 10, "min": 2 } |
This executes a type based match against the values, that is, they are equal if they are the same type. In addition, if the values represent a collection, the length of the actual value is compared against the minimum and maximum. |
Include | V3 | { "match": "include", "value": "substr" } |
This checks if the string representation of a value contains the substring. |
Integer | V3 | { "match": "integer" } |
This checks if the type of the value is an integer. |
Decimal | V3 | { "match": "decimal" } |
This checks if the type of the value is a number with decimal places. |
Number | V3 | { "match": "number" } |
This checks if the type of the value is a number. |
Timestamp | V3 | { "match": "datetime", "format": "yyyy-MM-dd HH:ss:mm" } |
Matches the string representation of a value against the datetime format |
Time | V3 | { "match": "time", "format": "HH:ss:mm" } |
Matches the string representation of a value against the time format |
Date | V3 | { "match": "date", "format": "yyyy-MM-dd" } |
Matches the string representation of a value against the date format |
Null | V3 | { "match": "null" } |
Match if the value is a null value (this is content specific, for JSON will match a JSON null) |
Boolean | V3 | { "match": "boolean" } |
Match if the value is a boolean value (booleans and the string values true and false ) |
ContentType | V3 | { "match": "contentType", "value": "image/jpeg" } |
Match binary data by its content type (magic file check) |
Values | V3 | { "match": "values" } |
Match the values in a map, ignoring the keys |
ArrayContains | V4 | { "match": "arrayContains", "variants": [...] } |
Checks if all the variants are present in an array. |
StatusCode | V4 | { "match": "statusCode", "status": "success" } |
Matches the response status code. |
NotEmpty | V4 | { "match": "notEmpty" } |
Value must be present and not empty (not null or the empty string) |
Semver | V4 | { "match": "semver" } |
Value must be valid based on the semver specification |
Semver | V4 | { "match": "semver" } |
Value must be valid based on the semver specification |
EachKey | V4 | { "match": "eachKey", "rules": [{"match": "regex", "regex": "\\$(\\.\\w+)+"}], "value": "$.test.one" } |
Allows defining matching rules to apply to the keys in a map |
EachValue | V4 | { "match": "eachValue", "rules": [{"match": "regex", "regex": "\\$(\\.\\w+)+"}], "value": "$.test.one" } |
Allows defining matching rules to apply to the values in a collection. For maps, delgates to the Values matcher. |
The matching rule definition language is a text format to specify the matching rules to be applied to data formats from plugins. It allows the matching rules to be applied without having to specify the specifics of the data format.
For example, they can equally be applied to very different data formats like Protobuf and CSV.
CSV:
"column:Date", "matching(datetime, 'yyyy-MM-dd','2000-01-01')"
Protobuf:
"contents": {
"contentType": "notEmpty('application/json')",
"content": "matching(contentType, 'application/json', '{}')",
"contentTypeHint": "matching(equalTo, 'TEXT')"
}
Each matching rule definition is a comma-separated list of functions with a number of arguments within brackets. Most of the time only a single definition is required for a value, but in they case were more than one is required, they just need to be separated by a comma.
The main function is the matching
function. This creates a matching rule based on a type and a number of values. The
values required are dependent on the type of the matching rule.
For example, matching with a regular expression: matching(regex, '\\$(\\.\\w+)+', '$.test.one')
Specifies that the attribute/field must be equal to the example value.
Parameters:
Example:
matching(equalTo, 'TEXT')
Specifies that the attribute/field must have the same type as the example value.
Parameters:
Example:
matching(type, 100)
Specifies that the attribute/field must be a number type. number
will match any numeric value, integer
will match
numeric values with no decimals (no significant figures after the decimal point) and decimal
will match numeric values
that have decimals (at least one significant figure after the decimal point).
Parameters:
Example:
matching(integer, 100)
matching(decimal, 100.1234)
Specifies that the string representation of the attribute/field must match the format specifier. These are based on the Java DateTimeFormatter.
Parameters:
Example:
matching(datetime, 'yyyy-MM-dd HH:mm:ss', '2021-10-07 13:00:13')
matching(date, 'yyyy-MM-dd', '2021-10-07')
matching(time, 'HH:mm:ss', '13:00:13')
Specifies that the string representation of the attribute/field must match the provided regular expression.
Parameters:
Example:
matching(regex, '\w+ \w+', 'Hello World')
Specifies that the string representation of the attribute/field must include the given string.
Parameters:
Example:
matching(include, 'Hello World')
Specifies that the attribute/field must be a boolean value or its string representation must be the strings true
or
false
.
Parameters:
Example:
matching(boolean, false)
Specifies that the string representation of the attribute/field must be a valid semantic version as per the semver specification.
Parameters:
Example:
matching(semver, '1.0.0')
Specifies that the byte string representation of the attribute/field must match the given content type using a magic file number check. This compares the first few bytes with a database of rules to determine the type of the contents.
Parameters:
Example:
matching(contentType, 'application/json', '{}')
pact_matching
currently performs the following for matching Binary content-types
expected
Content-Type
header requested by user in testinfer
library, and guess Content-Type
based on magic bytestree_magic_mini
library, and guess Content-Type
based on shared-mime-info DB
apk add shared-mime-info
brew install shared-mime-info
arm64
MacOS requires tree_magic_mini
forkapt-get install -y shared-mime-info
text/plain
, then manually read bytes using detect_content_type_from_bytes
function in pact_models
2
, 3
, or 4
fails, then throw error, otherwise return Ok
Rust libraries used:
Type matching can also be specified by a reference to an example. References are defined by a dollar ($
) followed by
a string value. The string value must be the attribute/field name that contains the example type.
Parameters:
Example:
matching($'items') // where items is the name of the example to match the types against
Specifies that the attribute field must be present and contain a value (not null or an empty string).
Parameters:
Example:
notEmpty('DateTime')
Allows a matching rule definition to be applied to the keys in a map.
Parameters:
Example:
eachKey(matching(regex, '\\$(\\.\\w+)+', '$.test.one'))
Allows a matching rule definition to be applied to the values in a collection (list/array or map form).
Parameters:
Example:
eachValue(matching($'items'))
The grammar for the Matching Rule Definition Language (ANTLR 4 format)
grammar MatcherDefinition;
matchingDefinition :
matchingDefinitionExp ( COMMA matchingDefinitionExp )* EOF
;
matchingDefinitionExp :
(
'matching' LEFT_BRACKET matchingRule RIGHT_BRACKET
| 'notEmpty' LEFT_BRACKET primitiveValue RIGHT_BRACKET
| 'eachKey' LEFT_BRACKET matchingDefinitionExp RIGHT_BRACKET
| 'eachValue' LEFT_BRACKET matchingDefinitionExp RIGHT_BRACKET
)
;
matchingRule :
(
( 'equalTo' | 'type' ) COMMA primitiveValue )
| 'number' COMMA ( DECIMAL_LITERAL | INTEGER_LITERAL )
| 'integer' COMMA INTEGER_LITERAL
| 'decimal' COMMA DECIMAL_LITERAL
| ( 'datetime' | 'date' | 'time' ) COMMA string COMMA string
| 'regex' COMMA string COMMA string
| 'include' COMMA string
| 'boolean' COMMA BOOLEAN_LITERAL
| 'semver' COMMA string
| 'contentType' COMMA string COMMA string
| DOLLAR string
;
primitiveValue :
string
| DECIMAL_LITERAL
| INTEGER_LITERAL
| BOOLEAN_LITERAL
;
string :
STRING_LITERAL
| 'null'
;
INTEGER_LITERAL : '-'? DIGIT+ ;
DECIMAL_LITERAL : '-'? DIGIT+ '.' DIGIT+ ;
fragment DIGIT : [0-9] ;
LEFT_BRACKET : '(' ;
RIGHT_BRACKET : ')' ;
STRING_LITERAL : '\'' (~['])* '\'' ;
BOOLEAN_LITERAL : 'true' | 'false' ;
COMMA : ',' ;
DOLLAR : '$';
WS : [ \t\n\r] + -> skip ;