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

AbstractMatcher

Bases: ABC, Generic[_T_co]


              flowchart TD
              pact.match.matcher.AbstractMatcher[AbstractMatcher]

              

              click pact.match.matcher.AbstractMatcher href "" "pact.match.matcher.AbstractMatcher"

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

has_value() -> bool

Check if the matcher has a value.

If a value is present, it must be accessible via the value attribute.

RETURNS DESCRIPTION
bool

True if the matcher has a value, otherwise False.
Source code in src/pact/match/matcher.py 
74
75
76
77
78
79
80
81
82
83
84
def has_value(self) -> bool:
    """
    Check if the matcher has a value.

    If a value is present, it _must_ be accessible via the `value`
    attribute.

    Returns:
        True if the matcher has a value, otherwise False.
    """
    return not isinstance(getattr(self, "value", UNSET), Unset)
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 integration JSON docs.

RETURNS DESCRIPTION
dict[str, Any]

The matcher as an integration JSON object.
Source code in src/pact/match/matcher.py 
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 [integration JSON
    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, refer to the Pact specification and the matchers section

RETURNS DESCRIPTION
dict[str, Any]

The matcher as a matching rule.
Source code in src/pact/match/matcher.py 
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
@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, refer to the [Pact
    specification](https://github.com/pact-foundation/pact-specification/tree/version-4)
    and the [matchers
    section](https://github.com/pact-foundation/pact-specification/tree/version-2?tab=readme-ov-file#matchers)

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

AndMatcher(*matchers: AbstractMatcher[Any], value: _T_co | Unset = UNSET)

Bases: AbstractMatcher[_T_co]


              flowchart TD
              pact.match.matcher.AndMatcher[AndMatcher]
              pact.match.matcher.AbstractMatcher[AbstractMatcher]

                              pact.match.matcher.AbstractMatcher --> pact.match.matcher.AndMatcher
                


              click pact.match.matcher.AndMatcher href "" "pact.match.matcher.AndMatcher"
              click pact.match.matcher.AbstractMatcher href "" "pact.match.matcher.AbstractMatcher"

And matcher.

A matcher that combines multiple matchers using a logical AND.

It is best practice to provide a value. This may be set when creating the AndMatcher, or it may be inferred from one of the constituent matchers. In the latter case, the value from the first matcher that has a value will be used.

PARAMETER DESCRIPTION
matchers

List of matchers to combine.

TYPE: AbstractMatcher[Any] DEFAULT: ()

value

Example value to match against. If not provided, the value from the first matcher that has a value will be used.

TYPE: _T_co | Unset DEFAULT: UNSET

Source code in src/pact/match/matcher.py 
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
def __init__(
    self,
    *matchers: AbstractMatcher[Any],
    value: _T_co | Unset = UNSET,
) -> None:
    """
    Initialize the matcher.

    It is best practice to provide a value. This may be set when creating
    the `AndMatcher`, or it may be inferred from one of the constituent
    matchers. In the latter case, the value from the first matcher that has
    a value will be used.

    Args:
        matchers:
            List of matchers to combine.

        value:
            Example value to match against. If not provided, the value
            from the first matcher that has a value will be used.
    """
    self._matchers = matchers
    self._value: _T_co | Unset = value

    if isinstance(self._value, Unset):
        for matcher in matchers:
            if matcher.has_value():
                # If `has_value` is true, `value` must be present
                self._value = matcher.value  # type: ignore[attr-defined]
                break

Functions

has_value() -> bool

Check if the matcher has a value.

If a value is present, it must be accessible via the value attribute.

RETURNS DESCRIPTION
bool

True if the matcher has a value, otherwise False.
Source code in src/pact/match/matcher.py 
74
75
76
77
78
79
80
81
82
83
84
def has_value(self) -> bool:
    """
    Check if the matcher has a value.

    If a value is present, it _must_ be accessible via the `value`
    attribute.

    Returns:
        True if the matcher has a value, otherwise False.
    """
    return not isinstance(getattr(self, "value", UNSET), Unset)
to_integration_json() -> dict[str, Any]

Convert the matcher to an integration JSON object.

See [AbstractMatcher.to_integration_json][pact.pact.match.matcher.AbstractMatcher.to_integration_json] for more information.

Source code in src/pact/match/matcher.py 
385
386
387
388
389
390
391
392
393
def to_integration_json(self) -> dict[str, Any]:
    """
    Convert the matcher to an integration JSON object.

    See
    [`AbstractMatcher.to_integration_json`][pact.match.matcher.AbstractMatcher.to_integration_json]
    for more information.
    """
    return {"pact:matcher:type": [m.to_integration_json() for m in self._matchers]}
to_matching_rule() -> dict[str, Any]

Convert the matcher to a matching rule.

See [AbstractMatcher.to_matching_rule][pact.pact.match.matcher.AbstractMatcher.to_matching_rule] for more information.

Source code in src/pact/match/matcher.py 
395
396
397
398
399
400
401
402
403
404
405
406
def to_matching_rule(self) -> dict[str, Any]:
    """
    Convert the matcher to a matching rule.

    See
    [`AbstractMatcher.to_matching_rule`][pact.match.matcher.AbstractMatcher.to_matching_rule]
    for more information.
    """
    return {
        "combine": "AND",
        "matchers": [m.to_matching_rule() for m in self._matchers],
    }

ArrayContainsMatcher(variants: Sequence[_T_co | AbstractMatcher[_T_co]])

Bases: AbstractMatcher[Sequence[_T_co]]


              flowchart TD
              pact.match.matcher.ArrayContainsMatcher[ArrayContainsMatcher]
              pact.match.matcher.AbstractMatcher[AbstractMatcher]

                              pact.match.matcher.AbstractMatcher --> pact.match.matcher.ArrayContainsMatcher
                


              click pact.match.matcher.ArrayContainsMatcher href "" "pact.match.matcher.ArrayContainsMatcher"
              click pact.match.matcher.AbstractMatcher href "" "pact.match.matcher.AbstractMatcher"

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_co | AbstractMatcher[_T_co]]

Source code in src/pact/match/matcher.py 
215
216
217
218
219
220
221
222
223
224
225
226
def __init__(self, variants: Sequence[_T_co | AbstractMatcher[_T_co]]) -> None:
    """
    Initialize the matcher.

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

Functions

has_value() -> bool

Check if the matcher has a value.

If a value is present, it must be accessible via the value attribute.

RETURNS DESCRIPTION
bool

True if the matcher has a value, otherwise False.
Source code in src/pact/match/matcher.py 
74
75
76
77
78
79
80
81
82
83
84
def has_value(self) -> bool:
    """
    Check if the matcher has a value.

    If a value is present, it _must_ be accessible via the `value`
    attribute.

    Returns:
        True if the matcher has a value, otherwise False.
    """
    return not isinstance(getattr(self, "value", UNSET), Unset)
to_integration_json() -> dict[str, Any]

Convert the matcher to an integration JSON object.

See [AbstractMatcher.to_integration_json][pact.pact.match.matcher.AbstractMatcher.to_integration_json] for more information.

Source code in src/pact/match/matcher.py 
228
229
230
231
232
233
234
235
236
def to_integration_json(self) -> dict[str, Any]:
    """
    Convert the matcher to an integration JSON object.

    See
    [`AbstractMatcher.to_integration_json`][pact.match.matcher.AbstractMatcher.to_integration_json]
    for more information.
    """
    return self._matcher.to_integration_json()
to_matching_rule() -> dict[str, Any]

Convert the matcher to a matching rule.

See [AbstractMatcher.to_matching_rule][pact.pact.match.matcher.AbstractMatcher.to_matching_rule] for more information.

Source code in src/pact/match/matcher.py 
238
239
240
241
242
243
244
245
246
def to_matching_rule(self) -> dict[str, Any]:
    """
    Convert the matcher to a matching rule.

    See
    [`AbstractMatcher.to_matching_rule`][pact.match.matcher.AbstractMatcher.to_matching_rule]
    for more information.
    """
    return self._matcher.to_matching_rule()

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

Bases: AbstractMatcher[Mapping[_T, Matchable]]


              flowchart TD
              pact.match.matcher.EachKeyMatcher[EachKeyMatcher]
              pact.match.matcher.AbstractMatcher[AbstractMatcher]

                              pact.match.matcher.AbstractMatcher --> pact.match.matcher.EachKeyMatcher
                


              click pact.match.matcher.EachKeyMatcher href "" "pact.match.matcher.EachKeyMatcher"
              click pact.match.matcher.AbstractMatcher href "" "pact.match.matcher.AbstractMatcher"

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[AbstractMatcher[_T]] | None DEFAULT: None

Source code in src/pact/match/matcher.py 
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
def __init__(
    self,
    value: Mapping[_T, Matchable],
    rules: list[AbstractMatcher[_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: AbstractMatcher[Mapping[_T, Matchable]] = GenericMatcher(
        "eachKey",
        value=value,
        extra_fields={"rules": rules},
    )

Functions

has_value() -> bool

Check if the matcher has a value.

If a value is present, it must be accessible via the value attribute.

RETURNS DESCRIPTION
bool

True if the matcher has a value, otherwise False.
Source code in src/pact/match/matcher.py 
74
75
76
77
78
79
80
81
82
83
84
def has_value(self) -> bool:
    """
    Check if the matcher has a value.

    If a value is present, it _must_ be accessible via the `value`
    attribute.

    Returns:
        True if the matcher has a value, otherwise False.
    """
    return not isinstance(getattr(self, "value", UNSET), Unset)
to_integration_json() -> dict[str, Any]

Convert the matcher to an integration JSON object.

See [AbstractMatcher.to_integration_json][pact.pact.match.matcher.AbstractMatcher.to_integration_json] for more information.

Source code in src/pact/match/matcher.py 
277
278
279
280
281
282
283
284
285
def to_integration_json(self) -> dict[str, Any]:
    """
    Convert the matcher to an integration JSON object.

    See
    [`AbstractMatcher.to_integration_json`][pact.match.matcher.AbstractMatcher.to_integration_json]
    for more information.
    """
    return self._matcher.to_integration_json()
to_matching_rule() -> dict[str, Any]

Convert the matcher to a matching rule.

See [AbstractMatcher.to_matching_rule][pact.pact.match.matcher.AbstractMatcher.to_matching_rule] for more information.

Source code in src/pact/match/matcher.py 
287
288
289
290
291
292
293
294
295
def to_matching_rule(self) -> dict[str, Any]:
    """
    Convert the matcher to a matching rule.

    See
    [`AbstractMatcher.to_matching_rule`][pact.match.matcher.AbstractMatcher.to_matching_rule]
    for more information.
    """
    return self._matcher.to_matching_rule()

EachValueMatcher(value: Mapping[Matchable, _T_co], rules: list[AbstractMatcher[_T_co]] | None = None)

Bases: AbstractMatcher[Mapping[Matchable, _T_co]]


              flowchart TD
              pact.match.matcher.EachValueMatcher[EachValueMatcher]
              pact.match.matcher.AbstractMatcher[AbstractMatcher]

                              pact.match.matcher.AbstractMatcher --> pact.match.matcher.EachValueMatcher
                


              click pact.match.matcher.EachValueMatcher href "" "pact.match.matcher.EachValueMatcher"
              click pact.match.matcher.AbstractMatcher href "" "pact.match.matcher.AbstractMatcher"

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_co]

rules

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

TYPE: list[AbstractMatcher[_T_co]] | None DEFAULT: None

Source code in src/pact/match/matcher.py 
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
def __init__(
    self,
    value: Mapping[Matchable, _T_co],
    rules: list[AbstractMatcher[_T_co]] | 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: AbstractMatcher[Mapping[Matchable, _T_co]] = GenericMatcher(
        "eachValue",
        value=value,
        extra_fields={"rules": rules},
    )

Functions

has_value() -> bool

Check if the matcher has a value.

If a value is present, it must be accessible via the value attribute.

RETURNS DESCRIPTION
bool

True if the matcher has a value, otherwise False.
Source code in src/pact/match/matcher.py 
74
75
76
77
78
79
80
81
82
83
84
def has_value(self) -> bool:
    """
    Check if the matcher has a value.

    If a value is present, it _must_ be accessible via the `value`
    attribute.

    Returns:
        True if the matcher has a value, otherwise False.
    """
    return not isinstance(getattr(self, "value", UNSET), Unset)
to_integration_json() -> dict[str, Any]

Convert the matcher to an integration JSON object.

See [AbstractMatcher.to_integration_json][pact.pact.match.matcher.AbstractMatcher.to_integration_json] for more information.

Source code in src/pact/match/matcher.py 
326
327
328
329
330
331
332
333
334
def to_integration_json(self) -> dict[str, Any]:
    """
    Convert the matcher to an integration JSON object.

    See
    [`AbstractMatcher.to_integration_json`][pact.match.matcher.AbstractMatcher.to_integration_json]
    for more information.
    """
    return self._matcher.to_integration_json()
to_matching_rule() -> dict[str, Any]

Convert the matcher to a matching rule.

See [AbstractMatcher.to_matching_rule][pact.pact.match.matcher.AbstractMatcher.to_matching_rule] for more information.

Source code in src/pact/match/matcher.py 
336
337
338
339
340
341
342
343
344
def to_matching_rule(self) -> dict[str, Any]:
    """
    Convert the matcher to a matching rule.

    See
    [`AbstractMatcher.to_matching_rule`][pact.match.matcher.AbstractMatcher.to_matching_rule]
    for more information.
    """
    return self._matcher.to_matching_rule()

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

Bases: AbstractMatcher[_T_co]


              flowchart TD
              pact.match.matcher.GenericMatcher[GenericMatcher]
              pact.match.matcher.AbstractMatcher[AbstractMatcher]

                              pact.match.matcher.AbstractMatcher --> pact.match.matcher.GenericMatcher
                


              click pact.match.matcher.GenericMatcher href "" "pact.match.matcher.GenericMatcher"
              click pact.match.matcher.AbstractMatcher href "" "pact.match.matcher.AbstractMatcher"

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_co | 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: AbstractGenerator | 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/match/matcher.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
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
171
172
def __init__(
    self,
    type: MatcherType,  # noqa: A002
    /,
    value: _T_co | Unset = UNSET,
    generator: AbstractGenerator | 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_co | 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_co | Unset = value instance-attribute

Default value used by Pact when executing tests.

Functions

has_value() -> bool

Check if the matcher has a value.

If a value is present, it must be accessible via the value attribute.

RETURNS DESCRIPTION
bool

True if the matcher has a value, otherwise False.
Source code in src/pact/match/matcher.py 
74
75
76
77
78
79
80
81
82
83
84
def has_value(self) -> bool:
    """
    Check if the matcher has a value.

    If a value is present, it _must_ be accessible via the `value`
    attribute.

    Returns:
        True if the matcher has a value, otherwise False.
    """
    return not isinstance(getattr(self, "value", UNSET), Unset)
to_integration_json() -> dict[str, Any]

Convert the matcher to an integration JSON object.

See [AbstractMatcher.to_integration_json][pact.pact.match.matcher.AbstractMatcher.to_integration_json] for more information.

Source code in src/pact/match/matcher.py 
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
def to_integration_json(self) -> dict[str, Any]:
    """
    Convert the matcher to an integration JSON object.

    See
    [`AbstractMatcher.to_integration_json`][pact.match.matcher.AbstractMatcher.to_integration_json]
    for more information.
    """
    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.

See [AbstractMatcher.to_matching_rule][pact.pact.match.matcher.AbstractMatcher.to_matching_rule] for more information.

Source code in src/pact/match/matcher.py 
193
194
195
196
197
198
199
200
201
202
203
204
205
def to_matching_rule(self) -> dict[str, Any]:
    """
    Convert the matcher to a matching rule.

    See
    [`AbstractMatcher.to_matching_rule`][pact.match.matcher.AbstractMatcher.to_matching_rule]
    for more information.
    """
    return {
        "match": self.type,
        **({"value": self.value} if not isinstance(self.value, Unset) else {}),
        **self._extra_fields,
    }

IntegrationJSONEncoder

Bases: JSONEncoder


              flowchart TD
              pact.match.matcher.IntegrationJSONEncoder[IntegrationJSONEncoder]

              

              click pact.match.matcher.IntegrationJSONEncoder href "" "pact.match.matcher.IntegrationJSONEncoder"

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.

PARAMETER DESCRIPTION
o

The object to encode.

TYPE: Any

RETURNS DESCRIPTION
Any

The encoded object.
Source code in src/pact/match/matcher.py 
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
def default(self, o: Any) -> Any:  # noqa: ANN401
    """
    Encode the object to JSON.

    Args:
        o:
            The object to encode.

    Returns:
        The encoded object.
    """
    if isinstance(o, AbstractMatcher):
        return o.to_integration_json()
    if isinstance(o, AbstractGenerator):
        return o.to_integration_json()
    return super().default(o)

MatchingRuleJSONEncoder

Bases: JSONEncoder


              flowchart TD
              pact.match.matcher.MatchingRuleJSONEncoder[MatchingRuleJSONEncoder]

              

              click pact.match.matcher.MatchingRuleJSONEncoder href "" "pact.match.matcher.MatchingRuleJSONEncoder"

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.

PARAMETER DESCRIPTION
o

The object to encode.

TYPE: Any

RETURNS DESCRIPTION
Any

The encoded object.
Source code in src/pact/match/matcher.py 
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
def default(self, o: Any) -> Any:  # noqa: ANN401
    """
    Encode the object to JSON.

    Args:
        o:
            The object to encode.

    Returns:
        The encoded object.
    """
    if isinstance(o, AndMatcher):
        return o.to_matching_rule()
    if isinstance(o, AbstractMatcher):
        # We need to convert all matchers in AndMatchers (even if there is
        # only one).
        return AndMatcher(o).to_matching_rule()
    return super().default(o)