Skip to content

Matcher

Matching functionality for Pact.

Matchers are used in Pact to allow for more flexible matching of data. While the consumer defines the expected request and response, there are circumstances where the provider may return dynamically generated data. In these cases, the consumer should use a matcher to define the expected data.

Attributes

Classes

ArrayContainsMatcher(variants: Sequence[_T | Matcher[_T]])

Bases: Matcher[Sequence[_T]]

Array contains matcher.

A matcher that checks if an array contains a value.

PARAMETER DESCRIPTION
variants

List of possible values to match against.

TYPE: Sequence[_T | Matcher[_T]]

Source code in src/pact/v3/match/matcher.py 
205
206
207
208
209
210
211
212
213
214
215
216
def __init__(self, variants: Sequence[_T | Matcher[_T]]) -> None:
    """
    Initialize the matcher.

    Args:
        variants:
            List of possible values to match against.
    """
    self._matcher: Matcher[Sequence[_T]] = GenericMatcher(
        "arrayContains",
        extra_fields={"variants": variants},
    )

Functions

to_integration_json() -> dict[str, Any]
Source code in src/pact/v3/match/matcher.py 
218
219
def to_integration_json(self) -> dict[str, Any]:  # noqa: D102
    return self._matcher.to_integration_json()
to_matching_rule() -> dict[str, Any]
Source code in src/pact/v3/match/matcher.py 
221
222
def to_matching_rule(self) -> dict[str, Any]:  # noqa: D102
    return self._matcher.to_matching_rule()

EachKeyMatcher(value: Mapping[_T, Matchable], rules: list[Matcher[_T]] | None = None)

Bases: Matcher[Mapping[_T, Matchable]]

Each key matcher.

A matcher that applies a matcher to each key in a mapping.

PARAMETER DESCRIPTION
value

Example value to match against.

TYPE: Mapping[_T, Matchable]

rules

List of matchers to apply to each key in the mapping.

TYPE: list[Matcher[_T]] | None DEFAULT: None

Source code in src/pact/v3/match/matcher.py 
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
def __init__(
    self,
    value: Mapping[_T, Matchable],
    rules: list[Matcher[_T]] | None = None,
) -> None:
    """
    Initialize the matcher.

    Args:
        value:
            Example value to match against.

        rules:
            List of matchers to apply to each key in the mapping.
    """
    self._matcher: Matcher[Mapping[_T, Matchable]] = GenericMatcher(
        "eachKey",
        value=value,
        extra_fields={"rules": rules},
    )

Functions

to_integration_json() -> dict[str, Any]
Source code in src/pact/v3/match/matcher.py 
253
254
def to_integration_json(self) -> dict[str, Any]:  # noqa: D102
    return self._matcher.to_integration_json()
to_matching_rule() -> dict[str, Any]
Source code in src/pact/v3/match/matcher.py 
256
257
def to_matching_rule(self) -> dict[str, Any]:  # noqa: D102
    return self._matcher.to_matching_rule()

EachValueMatcher(value: Mapping[Matchable, _T], rules: list[Matcher[_T]] | None = None)

Bases: Matcher[Mapping[Matchable, _T]]

Each value matcher.

A matcher that applies a matcher to each value in a mapping.

PARAMETER DESCRIPTION
value

Example value to match against.

TYPE: Mapping[Matchable, _T]

rules

List of matchers to apply to each value in the mapping.

TYPE: list[Matcher[_T]] | None DEFAULT: None

Source code in src/pact/v3/match/matcher.py 
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
def __init__(
    self,
    value: Mapping[Matchable, _T],
    rules: list[Matcher[_T]] | None = None,
) -> None:
    """
    Initialize the matcher.

    Args:
        value:
            Example value to match against.

        rules:
            List of matchers to apply to each value in the mapping.
    """
    self._matcher: Matcher[Mapping[Matchable, _T]] = GenericMatcher(
        "eachValue",
        value=value,
        extra_fields={"rules": rules},
    )

Functions

to_integration_json() -> dict[str, Any]
Source code in src/pact/v3/match/matcher.py 
288
289
def to_integration_json(self) -> dict[str, Any]:  # noqa: D102
    return self._matcher.to_integration_json()
to_matching_rule() -> dict[str, Any]
Source code in src/pact/v3/match/matcher.py 
291
292
def to_matching_rule(self) -> dict[str, Any]:  # noqa: D102
    return self._matcher.to_matching_rule()

GenericMatcher(type: MatcherType, /, value: _T | Unset = UNSET, generator: Generator | None = None, extra_fields: Mapping[str, Any] | None = None, **kwargs: Matchable)

Bases: Matcher[_T]

Generic matcher.

A generic matcher, with the ability to define arbitrary additional fields for inclusion in the integration JSON object and matching rule.

PARAMETER DESCRIPTION
type

The type of the matcher.

TYPE: MatcherType

value

The value to match. If not provided, the Pact library will generate a value based on the matcher type (or use the generator if provided). To ensure reproducibility, it is highly recommended to provide a value when creating a matcher.

TYPE: _T | Unset DEFAULT: UNSET

generator

The generator to use when generating the value. The generator will generally only be used if value is not provided.

TYPE: Generator | None DEFAULT: None

extra_fields

Additional configuration elements to pass to the matcher. These fields will be used when converting the matcher to both an integration JSON object and a matching rule.

TYPE: Mapping[str, Any] | None DEFAULT: None

**kwargs

Alternative way to define extra fields. See the extra_fields argument for more information.

TYPE: Matchable DEFAULT: {}

Source code in src/pact/v3/match/matcher.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
def __init__(
    self,
    type: MatcherType,  # noqa: A002
    /,
    value: _T | Unset = UNSET,
    generator: Generator | None = None,
    extra_fields: Mapping[str, Any] | None = None,
    **kwargs: Matchable,
) -> None:
    """
    Initialize the matcher.

    Args:
        type:
            The type of the matcher.

        value:
            The value to match. If not provided, the Pact library will
            generate a value based on the matcher type (or use the generator
            if provided). To ensure reproducibility, it is _highly_
            recommended to provide a value when creating a matcher.

        generator:
            The generator to use when generating the value. The generator
            will generally only be used if value is not provided.

        extra_fields:
            Additional configuration elements to pass to the matcher. These
            fields will be used when converting the matcher to both an
            integration JSON object and a matching rule.

        **kwargs:
            Alternative way to define extra fields. See the `extra_fields`
            argument for more information.
    """
    self.type = type
    """
    The type of the matcher.
    """

    self.value: _T | Unset = value
    """
    Default value used by Pact when executing tests.
    """

    self.generator = generator
    """
    Generator used to generate a value when the value is not provided.
    """

    self._extra_fields: Mapping[str, Any] = dict(
        chain((extra_fields or {}).items(), kwargs.items())
    )

Attributes

generator = generator instance-attribute

Generator used to generate a value when the value is not provided.

type = type instance-attribute

The type of the matcher.

value: _T | Unset = value instance-attribute

Default value used by Pact when executing tests.

Functions

has_value() -> bool

Check if the matcher has a value.

Source code in src/pact/v3/match/matcher.py 
140
141
142
143
144
def has_value(self) -> bool:
    """
    Check if the matcher has a value.
    """
    return not isinstance(self.value, Unset)
to_integration_json() -> dict[str, Any]

Convert the matcher to an integration JSON object.

This method is used internally to convert the matcher to a JSON object which can be embedded directly in a number of places in the Pact FFI.

For more information about this format, see the docs:

https://docs.pact.io/implementation_guides/rust/pact_ffi/integrationjson

RETURNS DESCRIPTION
dict[str, Any]

dict[str, Any]: The matcher as an integration JSON object.
Source code in src/pact/v3/match/matcher.py 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def to_integration_json(self) -> dict[str, Any]:
    """
    Convert the matcher to an integration JSON object.

    This method is used internally to convert the matcher to a JSON object
    which can be embedded directly in a number of places in the Pact FFI.

    For more information about this format, see the docs:

    > https://docs.pact.io/implementation_guides/rust/pact_ffi/integrationjson

    Returns:
        dict[str, Any]:
            The matcher as an integration JSON object.
    """
    return {
        "pact:matcher:type": self.type,
        **({"value": self.value} if not isinstance(self.value, Unset) else {}),
        **(
            self.generator.to_integration_json()
            if self.generator is not None
            else {}
        ),
        **self._extra_fields,
    }
to_matching_rule() -> dict[str, Any]

Convert the matcher to a matching rule.

This method is used internally to convert the matcher to a matching rule which can be embedded directly in a Pact file.

For more information about this format, see the docs:

https://github.com/pact-foundation/pact-specification/tree/version-4

and

https://github.com/pact-foundation/pact-specification/tree/version-2?tab=readme-ov-file#matchers

RETURNS DESCRIPTION
dict[str, Any]

dict[str, Any]: The matcher as a matching rule.
Source code in src/pact/v3/match/matcher.py 
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
def to_matching_rule(self) -> dict[str, Any]:
    """
    Convert the matcher to a matching rule.

    This method is used internally to convert the matcher to a matching rule
    which can be embedded directly in a Pact file.

    For more information about this format, see the docs:

    > https://github.com/pact-foundation/pact-specification/tree/version-4

    and

    > https://github.com/pact-foundation/pact-specification/tree/version-2?tab=readme-ov-file#matchers

    Returns:
        dict[str, Any]:
            The matcher as a matching rule.
    """
    return {
        "match": self.type,
        **({"value": self.value} if not isinstance(self.value, Unset) else {}),
        **self._extra_fields,
    }

IntegrationJSONEncoder

Bases: JSONEncoder

JSON encoder class for integration JSON objects.

This class is used to encode integration JSON objects to JSON.

Functions

default(o: Any) -> Any

Encode the object to JSON.

Source code in src/pact/v3/match/matcher.py 
318
319
320
321
322
323
324
325
326
def default(self, o: Any) -> Any:  # noqa: ANN401
    """
    Encode the object to JSON.
    """
    if isinstance(o, Matcher):
        return o.to_integration_json()
    if isinstance(o, Generator):
        return o.to_integration_json()
    return super().default(o)

Matcher

Bases: ABC, Generic[_T]

Abstract matcher.

In Pact, a matcher is used to define how a value should be compared. This allows for more flexible matching of data, especially when the provider returns dynamically generated data.

This class is abstract and should not be used directly. Instead, use one of the concrete matcher classes. Alternatively, you can create your own matcher by subclassing this class.

The matcher provides methods to convert into an integration JSON object and a matching rule. These methods are used internally by the Pact library when communicating with the FFI and generating the Pact file.

Functions

to_integration_json() -> dict[str, Any] abstractmethod

Convert the matcher to an integration JSON object.

This method is used internally to convert the matcher to a JSON object which can be embedded directly in a number of places in the Pact FFI.

For more information about this format, see the docs:

https://docs.pact.io/implementation_guides/rust/pact_ffi/integrationjson

RETURNS DESCRIPTION
dict[str, Any]

The matcher as an integration JSON object.
Source code in src/pact/v3/match/matcher.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
@abstractmethod
def to_integration_json(self) -> dict[str, Any]:
    """
    Convert the matcher to an integration JSON object.

    This method is used internally to convert the matcher to a JSON object
    which can be embedded directly in a number of places in the Pact FFI.

    For more information about this format, see the docs:

    > https://docs.pact.io/implementation_guides/rust/pact_ffi/integrationjson

    Returns:
        The matcher as an integration JSON object.
    """
to_matching_rule() -> dict[str, Any] abstractmethod

Convert the matcher to a matching rule.

This method is used internally to convert the matcher to a matching rule which can be embedded directly in a Pact file.

For more information about this format, see the docs:

https://github.com/pact-foundation/pact-specification/tree/version-4

and

https://github.com/pact-foundation/pact-specification/tree/version-2?tab=readme-ov-file#matchers

RETURNS DESCRIPTION
dict[str, Any]

The matcher as a matching rule.
Source code in src/pact/v3/match/matcher.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
@abstractmethod
def to_matching_rule(self) -> dict[str, Any]:
    """
    Convert the matcher to a matching rule.

    This method is used internally to convert the matcher to a matching rule
    which can be embedded directly in a Pact file.

    For more information about this format, see the docs:

    > https://github.com/pact-foundation/pact-specification/tree/version-4

    and

    > https://github.com/pact-foundation/pact-specification/tree/version-2?tab=readme-ov-file#matchers

    Returns:
        The matcher as a matching rule.
    """

MatchingRuleJSONEncoder

Bases: JSONEncoder

JSON encoder class for matching rules.

This class is used to encode matching rules to JSON.

Functions

default(o: Any) -> Any

Encode the object to JSON.

Source code in src/pact/v3/match/matcher.py 
302
303
304
305
306
307
308
def default(self, o: Any) -> Any:  # noqa: ANN401
    """
    Encode the object to JSON.
    """
    if isinstance(o, Matcher):
        return o.to_matching_rule()
    return super().default(o)