V3¶
Pact Python V3.
This module provides a preview of the next major version of Pact Python. It is subject to breaking changes and may have bugs; however, it is available for testing and feedback. If you encounter any issues, please report them on GitHub, and if you have any feedback, please let us know on either the GitHub discussions or on Slack.
The next major release will use the Pact Rust library to provide full support for all Pact features, and bring feature parity between the Python library and the other Pact libraries.
Migration Plan¶
This change will introduce some breaking changes where needed, but it will be done in a staged manner to give everyone the opportunity to migrate.
Stage 1 (from v2.2)¶
- The main Pact Python library remains the same. Bugs and minor features will continue to be added to the existing library, but no new major features will be added as the focus will be on the new library.
- The new library is exposed within
pact.v3
and can be used alongside the existing library. During this stage, no guarantees are made about the stability of thepact.v3
module. - Users are not recommended to use the new library in any production critical code at this stage, but are encouraged to try it out and provide feedback.
- The existing library will raise
PendingDeprecationWarning
warnings when it is used (if these warnings are enabled).
Stage 2 (from v2.3, tbc)¶
- The library within
pact.v3
is considered generally stable and users are encouraged to start migrating to it. - A detailed migration guide will be provided.
- The existing library will raise
DeprecationWarning
warnings when it is used to help raise awareness of the upcoming change. - This stage will likely last a few months to give everyone the opportunity to migrate.
Stage 3 (from v3)¶
-
The
pact.v3
module is renamed topact
- People who have previously migrated to
pact.v3
should be able to do as/pact.v3/pact/
and have everything work. - If the previous stage identifies any breaking changes as necessary, they will be made at this point and a detailed migration guide will be provided.
- People who have previously migrated to
-
The existing library is moved to the
pact.v2
scope.- This will be a very major and breaking change. Previous code
running against
v2
of Pact Python will not work againstv3
of Pact Python. - Users still wanting to use the
v2
library will need to update their code to use the newpact.v2
module. As/pact/pact.v2/
should be sufficient. - The
pact.v2
module will be considered deprecated, and will eventually be removed in a future release. No new features and only critical bug fixes will be made to this part of the library.
- This will be a very major and breaking change. Previous code
running against
Classes¶
Pact(consumer: str, provider: str)
¶
A Pact between a consumer and a provider.
This class defines a Pact between a consumer and a provider. It is the central class in Pact's framework, and is responsible for defining the interactions between the two parties.
One Pact
instance should be created for each provider that a consumer
interacts with. The methods on this class are used to define the broader
attributes of the Pact, such as the consumer and provider names, the Pact
specification, any plugins that are used, and any metadata that is attached
to the Pact.
Each interaction between the consumer and the provider is defined through
the upon_receiving
method, which
returns a sub-class of Interaction
.
PARAMETER | DESCRIPTION |
---|---|
consumer
|
Name of the consumer.
TYPE:
|
provider
|
Name of the provider.
TYPE:
|
Source code in src/pact/v3/pact.py
Attributes¶
consumer: str
property
¶
Consumer name.
provider: str
property
¶
Provider name.
specification: pact.v3.ffi.PactSpecification
property
¶
Pact specification version.
Functions¶
interactions(kind: Literal['HTTP', 'Sync', 'Async'] = 'HTTP') -> Generator[pact.v3.ffi.SynchronousHttp, None, None] | Generator[pact.v3.ffi.SynchronousMessage, None, None] | Generator[pact.v3.ffi.AsynchronousMessage, None, None]
¶
Return an iterator over the Pact's interactions.
The kind is used to specify the type of interactions that will be iterated over.
Source code in src/pact/v3/pact.py
serve(addr: str = 'localhost', port: int = 0, transport: str = 'http', transport_config: str | None = None, *, raises: bool = True, verbose: bool = True) -> PactServer
¶
Return a mock server for the Pact.
This function configures a mock server for the Pact. The mock server
is then started when the Pact is entered into a with
block:
PARAMETER | DESCRIPTION |
---|---|
addr
|
Address to bind the mock server to. Defaults to
TYPE:
|
port
|
Port to bind the mock server to. Defaults to
TYPE:
|
transport
|
Transport to use for the mock server. Defaults to
TYPE:
|
transport_config
|
Configuration for the transport. This is specific to the transport being used and should be a JSON string.
TYPE:
|
raises
|
Whether to raise an exception if there are mismatches between
the Pact and the server. If set to
TYPE:
|
verbose
|
Whether or not to print the mismatches to the logger. This works
independently of
TYPE:
|
RETURNS | DESCRIPTION |
---|---|
PactServer
|
A |
Source code in src/pact/v3/pact.py
upon_receiving(description: str, interaction: Literal['HTTP', 'Sync', 'Async'] = 'HTTP') -> HttpInteraction | AsyncMessageInteraction | SyncMessageInteraction
¶
Create a new Interaction.
PARAMETER | DESCRIPTION |
---|---|
description
|
Description of the interaction. This must be unique within the Pact.
TYPE:
|
interaction
|
Type of interaction. Defaults to
TYPE:
|
Source code in src/pact/v3/pact.py
using_plugin(name: str, version: str | None = None) -> Self
¶
Add a plugin to be used by the test.
Plugins extend the functionality of Pact.
PARAMETER | DESCRIPTION |
---|---|
name
|
Name of the plugin.
TYPE:
|
version
|
Version of the plugin. This is optional and can be
TYPE:
|
Source code in src/pact/v3/pact.py
verify(handler: Callable[[str | bytes | None, dict[str, str]], None], kind: Literal['Async', 'Sync'], *, raises: bool = True) -> list[InteractionVerificationError] | None
¶
Verify message interactions.
This function is used to ensure that the consumer is able to handle the
messages that are defined in the Pact. The handler
function is called
for each message in the Pact.
The end-user is responsible for defining the handler
function and
verifying that the messages are handled correctly. For example, if the
handler is meant to call an API, then the API call should be mocked out
and once the verification is complete, the mock should be verified. Any
exceptions raised by the handler will be caught and reported as
mismatches.
PARAMETER | DESCRIPTION |
---|---|
handler
|
The function that will be called for each message in the Pact. The first argument to the function is the message body, either as a string or byte array. The second argument is the metadata for the message. If there is no metadata, then this will be an empty dictionary. |
kind
|
The type of message interaction. This must be one of
TYPE:
|
raises
|
Whether or not to raise an exception if the handler fails to
process a message. If set to
TYPE:
|
Source code in src/pact/v3/pact.py
with_metadata(namespace: str, metadata: dict[str, str]) -> Self
¶
Set additional metadata for the Pact.
A common use for this function is to add information about the client library (name, version, hash, etc.) to the Pact.
PARAMETER | DESCRIPTION |
---|---|
namespace
|
Namespace for the metadata. This is used to group the metadata together.
TYPE:
|
metadata
|
Key-value pairs of metadata to add to the Pact. |
Source code in src/pact/v3/pact.py
with_specification(version: str | pact.v3.ffi.PactSpecification) -> Self
¶
Set the Pact specification version.
The Pact specification version indicates the features which are supported by the Pact, and certain default behaviours.
PARAMETER | DESCRIPTION |
---|---|
version
|
Pact specification version. The can be either a string or a
The version string is case insensitive and has an optional
TYPE:
|
Source code in src/pact/v3/pact.py
write_file(directory: Path | str | None = None, *, overwrite: bool = False) -> None
¶
Write out the pact to a file.
This function should be called once all of the consumer tests have been run. It writes the Pact to a file, which can then be used to validate the provider.
PARAMETER | DESCRIPTION |
---|---|
directory
|
The directory to write the pact to. If the directory does not exist, it will be created. The filename will be automatically generated from the underlying Pact. |
overwrite
|
If set to True, the file will be overwritten if it already exists. Otherwise, the contents of the file will be merged with the existing file.
TYPE:
|
Source code in src/pact/v3/pact.py
Verifier(name: str, host: str | None = None)
¶
A Verifier between a consumer and a provider.
This class encapsulates the logic for verifying that a provider meets the expectations of a consumer. This is done by replaying interactions from the consumer against the provider, and ensuring that the provider's responses match the expectations set by the consumer.
PARAMETER | DESCRIPTION |
---|---|
name
|
The name of the provider to verify. This is used to identify which interactions the provider is involved in, and then Pact will replay these interactions against the provider.
TYPE:
|
host
|
The host on which the Pact verifier is running. This is used to
communicate with the provider. If not specified, the default
value is
TYPE:
|
Source code in src/pact/v3/verifier.py
Attributes¶
logs: str
property
¶
Get the logs.
results: dict[str, Any]
property
¶
Get the results.
Functions¶
add_custom_header(name: str, value: str) -> Self
¶
Add a customer header to the request.
These headers are added to every request made to the provider.
PARAMETER | DESCRIPTION |
---|---|
name
|
The key of the header.
TYPE:
|
value
|
The value of the header.
TYPE:
|
Source code in src/pact/v3/verifier.py
add_custom_headers(headers: dict[str, str] | Iterable[tuple[str, str]]) -> Self
¶
Add multiple customer headers to the request.
These headers are added to every request made to the provider.
PARAMETER | DESCRIPTION |
---|---|
headers
|
The headers to add. This can be a dictionary or an iterable of key-value pairs. The iterable is preferred as it ensures that repeated headers are not lost. |
Source code in src/pact/v3/verifier.py
add_source(source: str | Path | URL, *, username: str | None = None, password: str | None = None, token: str | None = None) -> Self
¶
Adds a source to the verifier.
This will use one or more Pact files as the source of interactions to verify.
PARAMETER | DESCRIPTION |
---|---|
source
|
The source of the interactions. This may be either of the following:
If using a URL, the |
username
|
The username to use for basic HTTP authentication. This is only used when the source is a URL.
TYPE:
|
password
|
The password to use for basic HTTP authentication. This is only used when the source is a URL.
TYPE:
|
token
|
The token to use for bearer token authentication. This is only
used when the source is a URL. Note that this is mutually
exclusive with
TYPE:
|
Source code in src/pact/v3/verifier.py
add_transport(*, url: str | URL | None = None, protocol: str | None = None, port: int | None = None, path: str | None = None, scheme: str | None = None) -> Self
¶
Add a provider transport method.
If the provider supports multiple transport methods, or non-HTTP(S) methods, this method allows these additional transport methods to be added. It can be called multiple times to add multiple transport methods.
As some transport methods may not use ports, paths or schemes, these
parameters are optional. Note that while optional, these may still be
used during testing as Pact uses HTTP(S) to communicate with the
provider. For example, if you are implementing your own message
verification, it needs to be exposed over HTTP and the port
and path
arguments are used for this testing communication.
PARAMETER | DESCRIPTION |
---|---|
url
|
A convenient way to set the provider transport. This option is mutually exclusive with the other options.
TYPE:
|
protocol
|
The protocol to use. This will typically be one of:
Any other protocol will be treated as a custom protocol and will be handled by a plugin. If
TYPE:
|
port
|
The provider port. If the protocol does not use ports, this parameter should be
TYPE:
|
path
|
The provider context path. For protocols which do not use paths, this parameter should be
For protocols which do use paths, this parameter should be specified to avoid any ambiguity, though if left unspecified, the root path will be used. If a non-root path is used, the path given here will be
prepended to the path in the interaction. For example, if the
path is
TYPE:
|
scheme
|
The provider scheme, if applicable to the protocol. This is typically only used for the
TYPE:
|
Source code in src/pact/v3/verifier.py
199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 |
|
broker_source(url: str | URL, *, username: str | None = None, password: str | None = None, token: str | None = None, selector: bool = False) -> BrokerSelectorBuilder | Self
¶
broker_source(
url: str | URL,
*,
username: str | None = None,
password: str | None = None,
selector: Literal[False] = False,
) -> Self
broker_source(
url: str | URL,
*,
token: str | None = None,
selector: Literal[False] = False,
) -> Self
Adds a broker source to the verifier.
PARAMETER | DESCRIPTION |
---|---|
url
|
The broker URL. TThe URL may contain a username and password for basic HTTP authentication.
TYPE:
|
username
|
The username to use for basic HTTP authentication. If the source
is a URL containing a username, this parameter must be
TYPE:
|
password
|
The password to use for basic HTTP authentication. If the source
is a URL containing a password, this parameter must be
TYPE:
|
token
|
The token to use for bearer token authentication. This is
mutually exclusive with
TYPE:
|
selector
|
Whether to return a BrokerSelectorBuilder instance.
TYPE:
|
Source code in src/pact/v3/verifier.py
1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 |
|
disable_ssl_verification() -> Self
¶
Disable SSL verification.
Source code in src/pact/v3/verifier.py
filter(description: str | None = None, *, state: str | None = None, no_state: bool = False) -> Self
¶
Set the filter for the interactions.
This method can be used to filter interactions based on their description and state. Repeated calls to this method will replace the previous filter.
PARAMETER | DESCRIPTION |
---|---|
description
|
The interaction description. This should be a regular expression. If unspecified, no filtering will be done based on the description.
TYPE:
|
state
|
The interaction state. This should be a regular expression. If unspecified, no filtering will be done based on the state.
TYPE:
|
no_state
|
Whether to include interactions with no state.
TYPE:
|
Source code in src/pact/v3/verifier.py
filter_consumers(*filters: str) -> Self
¶
Filter the consumers.
PARAMETER | DESCRIPTION |
---|---|
filters
|
Filters to apply to the consumers.
TYPE:
|
logs_for_provider(provider: str) -> str
classmethod
¶
message_handler(handler: MessageProducerFull | dict[str, MessageProducerNoName | Message]) -> Self
¶
Set the message handler.
This method sets a custom message handler for the verifier. The handler can be called to produce a specific message to send to the provider.
This can be provided in one of two ways:
-
A fully fledged function that will be called for all messages. The function must take two arguments: the name of the message (as a string), and optional parameters (as a dictionary). This then returns the message as bytes.
This is the most powerful option as it allows for full control over the message generation.
-
A dictionary mapping message names to producer functions, or bytes. In this case, the producer function must take optional parameters (as a dictionary) and return the message as bytes.
If the message to be produced is static, the bytes can be provided directly.
Implementation¶
There are a large number of ways to send messages, and the specifics of the transport methods are not specifically relevant to Pact. As such, Pact abstracts the transport layer away and uses a lightweight HTTP server to handle messages.
Pact Python is capable of setting up this server and handling the
messages internally using user-provided handlers. It is possible to use
your own HTTP server to handle messages by using the add_transport
method. It is not possible to use both this method and add_transport
to handle messages.
PARAMETER | DESCRIPTION |
---|---|
handler
|
The message handler. This should be a callable that takes no arguments: the
TYPE:
|
Source code in src/pact/v3/verifier.py
328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 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 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 |
|
output(*, strip_ansi: bool = False) -> str
¶
set_coloured_output(*, enabled: bool = True) -> Self
¶
set_error_on_empty_pact(*, enabled: bool = True) -> Self
¶
Toggle error on empty pact.
If enabled, a Pact file with no interactions will cause the verifier to return an error. If disabled, a Pact file with no interactions will be ignored.
Source code in src/pact/v3/verifier.py
set_publish_options(version: str, url: str | None = None, branch: str | None = None, tags: list[str] | None = None) -> Self
¶
Set options used when publishing results to the Broker.
PARAMETER | DESCRIPTION |
---|---|
version
|
The provider version.
TYPE:
|
url
|
URL to the build which ran the verification.
TYPE:
|
tags
|
Collection of tags for the provider. |
branch
|
Name of the branch used for verification.
TYPE:
|
Source code in src/pact/v3/verifier.py
set_request_timeout(timeout: int) -> Self
¶
Set the request timeout.
PARAMETER | DESCRIPTION |
---|---|
timeout
|
The request timeout in milliseconds.
TYPE:
|
Source code in src/pact/v3/verifier.py
state_handler(handler: StateHandlerFull | StateHandlerNoAction | dict[str, StateHandlerNoState] | dict[str, StateHandlerNoActionNoState] | StateHandlerUrl, *, teardown: bool = False, body: bool | None = None) -> Self
¶
state_handler(
handler: StateHandlerNoAction,
*,
teardown: Literal[False] = False,
body: None = None,
) -> Self
state_handler(
handler: dict[str, StateHandlerNoState],
*,
teardown: Literal[True],
body: None = None,
) -> Self
Set the state handler.
In many interactions, the consumer will assume that the provider is in a
certain state. For example, a consumer requesting information about a
user with ID 123
will have specified given("user with ID 123
exists")
.
The state handler is responsible for changing the provider's internal state to match the expected state before the interaction is replayed.
This can be done in one of three ways:
- By providing a single function that will be called for all state changes.
- By providing a mapping of state names to functions.
- By providing the URL endpoint to which the request should be made.
The first two options are most straightforward to use.
When providing a function, the arguments should be:
- The state name, as a string.
- The action (either
setup
orteardown
), as a string. - A dictionary of parameters, or
None
if no parameters are provided.
Note that these arguments will change in the following ways:
- If a dictionary mapping is used, the state name is not provided to the function.
- If
teardown
isFalse
thereby indicating that the function is only called for setup, theaction
argument is not provided.
This means that in the case of a dictionary mapping of function with
teardown=False
, the function should take only one argument: the
dictionary of parameters (which itself may be None
, albeit still an
argument).
PARAMETER | DESCRIPTION |
---|---|
handler
|
The handler for the state changes. This can be one of the following:
See above for more information on the function signature.
TYPE:
|
teardown
|
Whether to teardown the provider state after an interaction is validated.
TYPE:
|
body
|
Whether to include the state change request in the body (
TYPE:
|
Source code in src/pact/v3/verifier.py
506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 |
|
verify() -> Self
¶
Verify the interactions.
RETURNS | DESCRIPTION |
---|---|
Self
|
Whether the interactions were verified successfully. |