Migration Guide¶

[!INFO]

This document is best viewed on the Pact Python docs site.

This document outlines the key changes and migration steps for users transitioning between major Pact Python versions. It focuses on breaking changes, new features, and best practices to ensure a smooth upgrade.

Migrating from `3.x` to `4.x`¶

Key Changes¶

The pact.v2 compatibility module and the compat-v2 extra have been removed, along with the pact-verifier console script. Code still importing from pact.v2 must move to the 3.x API described in Migrating from 2.x to 3.x.
Python 3.11 or newer is required.
The compat-v2 extra used to install pact-python-cli. Install it directly if you rely on the Pact CLI (for example, pact broker to publish contracts).

Projects that cannot migrate yet should pin pact-python<4, which still provides pact.v2 through pact-python[compat-v2].

Migrating `pact-python-cli` from `2.x` to `1!x`¶

pact-python-cli is now published from pact-foundation/pact-cli and ships its Rust pact binary. Its versions follow that project under PEP 440 epoch 1 (1!0.10.10, for example), so they sort above the 2.x releases.

Key Changes¶

The Ruby standalone tools are gone. Each command maps to a pact subcommand:

`2.x` command	`1!x` command
`pact-broker`	`pact broker`
`pactflow`	`pact pactflow`
`pact-mock-service`, `pact_mock_server_cli`	`pact mock`
`pact-provider-verifier`, `pact_verifier_cli`	`pact verifier`
`pact-stub-service`, `pact-stub-server`	`pact stub`
`pact-plugin-cli`	`pact plugin`
`pact-message`	No equivalent

The pact_cli Python module is gone, along with PACT_USE_SYSTEM_BINS and the *_PATH constants. Find the binary with shutil.which("pact").
Linux with glibc older than 2.34 has no 1!x wheel, so pip installs 2.6.4.0 there. Install pact with the Pact CLI installers instead.

Projects that still need the Ruby tools should pin pact-python-cli<1!0.

Migrating from `2.x` to `3.x`¶

Key Changes¶

Replaced the entire Pact CLI-based implementation with a brand new version leveraging the core Pact FFI written in Rust.
- This will help ensure feature parity between different language implementations and improve performance and reliability. This also brings compatibility with the latest Pact Specification (v4).
The bundled CLI is now a separate package: pact-python-cli.
The programmatic API has been completely overhauled to be more Pythonic and easier to use. Legacy process calls and return code checks have been removed in favour of proper exception handling.
The old programmatic interface was available in the pact.v2 module during the 3.x series. It was removed in 4.0.0; see Migrating from 3.x to 4.x.

Consumer Changes¶

The v3 API introduces significant changes to how consumer tests are structured and written. The main changes simplify the API, making it more Pythonic and flexible.

Defining a Pact¶

The Consumer and Provider classes have been removed. Instead, a single Pact class is used to define the consumer-provider relationship:

v2

from pact.v2 import Consumer, Provider

consumer = Consumer("my-web-front-end")
provider = Provider("my-backend-service")

pact = consumer.has_pact_with(provider, pact_dir="/path/to/pacts")

v3

from pact import Pact

pact = Pact("my-web-front-end", "my-backend-service")

Defining Interactions¶

The v3 interface favours method chaining and provides more granular control over request and response definitions.

v2

(
    pact
    .given("user exists")
    .upon_receiving("a request for user data")
    .with_request(
        "GET",
        "/users/123",
        headers={"Accept": "application/json"},
        query={"include": "profile"},
    )
    .will_respond_with(
        200,
        headers={"Content-Type": "application/json"},
        body={"id": 123, "name": "Alice"},
    )
)

v3

(
    pact
    .upon_receiving("a request for user data")
    .given("user exists", id=123, name="Alice")  # (1)
    .with_request("GET", "/users/123")
    .with_header("Accept", "application/json")
    .with_query_parameter("include", "profile")
    .will_respond_with(200)
    .with_header("Content-Type", "application/json")
    .with_body({"id": 123, "name": "Alice"}, content_type="application/json")
)

In v2, there was limited support for parameterizing provider states, and each state variation often required a separate definition. For example, given("user Alice exists with id 123") and given("user Bob exists with id 456") would be two distinct states, which would then need to be handled separately in the provider state setup.

The new interface can now define a common descriptor that can be reused with different parameters: .given("user exists", id=123, name='Alice') and .given("user exists", id=456, name='Bob'). This approach reduces redundancy and makes it easier to manage provider states.

Some methods are shared across request and response definitions, such as with_header() and with_body(). Pact Python automatically applies them to the correct part of the interaction based on whether they are called before or after will_respond_with(). Alternatively, these methods accept an optional part argument to explicitly specify whether they apply to the request or response.

Running Tests¶

Pact Python v2 had two different ways to run consumer tests, both of which spawned a separate mock service process. The new v3 API provides a single, consistent way to run tests using the serve() method.

v2 - with context manager

pact = Consumer("my-consumer").has_pact_with(
    Provider("my-provider"),
    host_name="localhost",
    port=1234,
)

# Context manager automatically calls setup() and verify()
with pact:
    response = requests.get(pact.uri + "/users/123")
# Pact file written automatically on exit

v2 - with manual service management

pact = Consumer("my-consumer").has_pact_with(
    Provider("my-provider"),
    host_name="localhost",
    port=1234,
)

# Manually start the mock service
pact.start_service()
pact.setup()  # Configure interactions

# Make requests
response = requests.get(pact.uri + "/users/123")
# Assertions...

# Verify and stop
pact.verify()  # Writes pact file
pact.stop_service()

The new API entirely replaces both of these approaches with a single, consistent method:

v3

pact = Pact("my-consumer", "my-provider")

with pact.serve() as srv:
    response = requests.get(f"{srv.url}/users/123")

The server host and port can be specified in serve() if needed, but by default, the server binds to localhost on a random available port. More details can be found in the API reference.

Writing Pact Files¶

Since the old v2 API executed a sub-process for the mock service, the Pact file was automatically written when the context manager exited or when pact.verify() was called. The new v3 API runs the mock service in-process, so the Pact file must be written explicitly using the write_file() method:

v2

with pact:
    # tests...
# Pact file written automatically

v3

pact = Pact("consumer", "provider")
# Define interactions and run tests...
pact.write_file("/path/to/pacts")

Matchers¶

Support for matchers has been greatly expanded and improved in the v3 API. The older v2 classes defined a limited set of matchers, while the new API provides a more comprehensive and flexible approach.

v2

from pact.v2.matchers import Like, EachLike, Regex, Term

# Usage:
Like({"id": 123})
EachLike({"item": "value"})
Regex("hello world", r"^hello")

v3

from pact import match

# Usage:
match.like({"id": 123})
match.each_like({"item": "value"})
match.regex("hello world", r"^hello")

For a full list of available matchers and their usage, refer to the API documentation.

Provider Changes¶

The provider verification API has been completely redesigned in v3 to provide a more intuitive and flexible interface. The old Provider and Verifier classes have been replaced by a single Verifier class with a fluent interface.

Creating a Verifier¶

v2

from pact.v2 import Provider, Verifier

# Create separate Provider and Verifier instances
provider = Provider("my-provider")
verifier = Verifier(provider, "http://localhost:8080")

v3

from pact import Verifier

# Single Verifier instance with provider name
verifier = Verifier("my-provider")

The protocol specification is now done through the add_transport method, which allows for more flexible configuration and supports multiple transports if needed.

v2

verifier = Verifier(provider, "http://localhost:8080")

v3

verifier = (
    Verifier("my-provider")
    .add_transport(url="http://localhost:8080")
    # Or more granular control:
    .add_transport(protocol="http", port=8080, path="/api/v1", scheme="https")
)

Adding Pact Sources¶

Support for both local files and Pact Brokers is retained in v3, with the verify_pacts and verify_with_broker methods replaced by a more flexible source configuration. This allows multiple sources to be combined, and selectors to be applied.

Local FilesPact Broker

v2

success, logs = verifier.verify_pacts(
    "./pacts/consumer1-provider.json", "./pacts/consumer2-provider.json"
)

v3

verifier = (
    Verifier("my-provider")
    # It can discover all Pact files in a directory
    .add_source("./pacts/")
    # Or read individual files
    .add_source("./pacts/specific-consumer.json")
)

v2

success, logs = verifier.verify_with_broker(
    broker_url="https://pact-broker.example.com",
    broker_username="username",
    broker_password="password",
)

v3

verifier = Verifier("my-provider").broker_source(
    "https://pact-broker.example.com", username="username", password="password"
)

# Or with selectors for more control
broker_builder = (
    verifier
    .broker_source("https://pact-broker.example.com", selector=True)
    .include_pending()
    .provider_branch("main")
    .consumer_version(branch="main")
    .consumer_version(branch="develop")
    .build()
)

The selector=True argument returns a BrokerSelectorBuilder instance, which provides methods to configure which pacts to fetch. The build() call finalizes the configuration and returns the Verifier instance which can then be further configured.

The consumer_version method provides fine-grained control over which consumer pacts are verified and can be called multiple times to add multiple selectors (combined with a logical OR). The older consumer_versions method is now deprecated in favor of consumer_version.

Provider State Handling¶

The old v2 API required the provider to expose an HTTP endpoint dedicated to handling provider states. This is still supported in v3, but there are now more flexible options, allowing Python functions (or mappings of state names to functions) to be used instead.

URL-based State HandlingFunctional State Handling

v2

success, logs = verifier.verify_pacts(
    "./pacts/consumer-provider.json",
    provider_states_setup_url="http://localhost:8080/_pact/provider_states",
)

v3

# Option 1: URL-based (similar to v2)
verifier = (
    Verifier("my-provider")
    .add_transport(url="http://localhost:8080")
    .state_handler(
        "http://localhost:8080/_pact/provider_states",
        body=True,  # (1)
    )
    .add_source("./pacts/")
)

The body argument specifies whether to use a POST request and pass information in the body, or to use a GET request and pass information through HTTP headers. For more details, see the state_handler API documentation.

v2

# Not supported

v3 - Function

def handler(name, params=None):
    if name == "user exists":
        # Set up user in database/mock
        create_user(params.get("id", 123))
    elif name == "no users exist":
        # Clear users
        clear_users()

    verifier = (
        Verifier("my-provider")
        .add_transport(url="http://localhost:8080")
        .state_handler(handler)
        .add_source("./pacts/")
    )

v3 - Mapping

state_handlers = {
    "user exists": lambda name, params: create_user(params.get("id", 123)),
    "no users exist": lambda name, params: clear_users(),
}

verifier = (
    Verifier("my-provider")
    .add_transport(url="http://localhost:8080")
    .state_handler(state_handlers)
    .add_source("./pacts/")
)

More information on the state handler function signature can be found in the state_handler API documentation. By default, the handlers only set up the provider state. If you need to also tear down the state after verification, you can use the teardown=True argument to enable this behaviour.

Warning

These functions run in the test process, so any side effects must be properly shared with the provider. If using mocking libraries, ensure the provider is started in a separate thread of the same process (using threading.Thread or similar), rather than a separate process (e.g., using multiprocessing.Process or subprocess.Popen).

Message Verification¶

Message verification is now much more straightforward in v3, with a a similar interface to HTTP verification and fixes a number of issues and deficiencies present in the v2 implementation (including the swapped behaviour of expects_to_receive and given, and the lack of support for matchers and generators).

v3 - Functional Handler

def message_handler(description, metadata):
    if description == "user created event":
        return {"id": 123, "name": "Alice", "event": "created"}
    elif description == "user deleted event":
        return {"id": 123, "event": "deleted"}


verifier = (
    Verifier("my-provider").message_handler(message_handler).add_source("./pacts/")
)

v3 - Dictionary Mapping

messages = {
    "user created event": {"id": 123, "name": "Alice", "event": "created"},
    "user deleted event": lambda desc, meta: {"id": 123, "event": "deleted"},
}

verifier = Verifier("my-provider").message_handler(messages).add_source("./pacts/")

Running Verification¶

Verification has been simplified and no longer requires checking return codes. Instead, the verify() method raises an exception on failure, or returns normally on success.

v2

success, logs = verifier.verify_pacts("./pacts/consumer-provider.json")
if not success:
    print(logs)
    raise AssertionError("Verification failed!")

v3

verifier.verify()

Migration Guide¶

Migrating from 3.x to 4.x¶

Key Changes¶

Migrating pact-python-cli from 2.x to 1!x¶

Key Changes¶

Migrating from 2.x to 3.x¶

Key Changes¶

Consumer Changes¶

Defining a Pact¶

Defining Interactions¶

Running Tests¶

Writing Pact Files¶

Matchers¶

Provider Changes¶

Creating a Verifier¶

Adding Pact Sources¶

Provider State Handling¶

Message Verification¶

Running Verification¶

Migrating from `3.x` to `4.x`¶

Migrating `pact-python-cli` from `2.x` to `1!x`¶

Migrating from `2.x` to `3.x`¶