pact-python

3.2.1 · active · verified Tue Apr 14

pact-python is an active library (current version 3.2.1) providing consumer-driven contract testing capabilities for Python applications. It builds on the Pact Rust FFI library, offering full support for Pact features and ensuring compatibility with other Pact implementations. It sees regular updates, often aligning with major Pact specification changes and core library enhancements.

Warnings

breaking Version 3.x introduces significant breaking changes due to a re-architecture leveraging the Pact Rust FFI library, replacing the older Ruby-based executables and API. The primary `pact` module now exposes the v3 API.
Fix: Migrate code from the old `pact` module (pre-v3) to the new v3 API. If maintaining old code, it needs to be updated to use the deprecated `pact.v2` namespace (e.g., `from pact.v2 import Pact` instead of `from pact import Pact`). A detailed migration guide is available in the official documentation.
breaking The default Pact specification version for new `Pact` instances changed from v3 to v4. While largely backward-compatible, explicitly setting the specification might be necessary if your project relies on specific v3 behaviors.
Fix: If your project requires Pact Specification v3, explicitly set it during `Pact` instantiation: `Pact(...).with_specification('V3')`.
breaking The signature of the `Interaction.given()` method has been simplified, which may require updates to consumer test definitions.
Fix: Refer to the latest documentation for the updated `given()` method signature and adjust your consumer test code accordingly.
deprecated The `pact.v3.ffi` module has been removed as of v3.0.0 and is replaced by the standalone `pact_ffi` package.
Fix: Any direct imports or usage of `pact.v3.ffi` should be replaced with `pact_ffi`.
gotcha When defining provider states using `given()`, it's recommended to parameterize the state (e.g., `given("user exists", id=123)`) rather than embedding values directly in the state description (e.g., `given("user 123 exists")`). This makes provider state handlers more reusable and robust.
Fix: Refactor provider state definitions to use keyword arguments for dynamic data, allowing the provider to set up the necessary state more flexibly.

Install

pip install pact-python Latest stable version

Imports

Pact
```
from pact import Pact
```
The `pact.v3` namespace was a temporary module during the transition to v3; the main `pact` module now exposes the v3 API directly.
Consumer, Provider
```
from pact import Consumer, Provider
```
While `Consumer` and `Provider` classes exist, `Pact(consumer='...', provider='...')` is the recommended v3 approach. The old v2 API moved to `pact.v2` (which is deprecated).
Verifier
```
from pact.verifier import Verifier
```
Used for verifying pacts against a provider service.

Quickstart

This quickstart demonstrates a basic consumer-side contract test using `pact-python`. It sets up a mock service, defines an expected interaction, and then verifies that a simple Python client correctly interacts with the mock service based on the defined contract. The mock service URL and consumer/provider names are configurable via environment variables for CI/CD compatibility.

import atexit
import unittest
import requests
import os
from pact import Pact

# Define the client that will interact with the provider
class UserClient:
    def __init__(self, base_url):
        self.base_url = base_url

    def get_user(self, username):
        response = requests.get(f"{self.base_url}/users/{username}")
        response.raise_for_status()
        return response.json()

# Set up Pact for consumer testing
# Use environment variables for consumer/provider names in CI/CD, or hardcode for local dev
PACT_MOCK_HOST = os.environ.get('PACT_MOCK_HOST', 'localhost')
PACT_MOCK_PORT = int(os.environ.get('PACT_MOCK_PORT', '1234'))

# Instantiate Pact with consumer and provider names
pact = Pact(
    consumer=os.environ.get('PACT_CONSUMER', 'MyConsumer'),
    provider=os.environ.get('PACT_PROVIDER', 'UserService')
)

# Start the mock service and register its shutdown
pact.start_service(host_name=PACT_MOCK_HOST, port=PACT_MOCK_PORT)
atexit.register(pact.stop_service)

class GetUserInfoContract(unittest.TestCase):
    def test_get_ash_user(self):
        expected_body = {
            'username': 'Ash',
            'id': 123,
            'groups': ['Admin']
        }

        # Define the interaction
        (pact
         .given('User Ash exists and is an administrator')
         .upon_receiving('a request for Ash')
         .with_request('GET', '/users/Ash')
         .will_respond_with(200, headers={'Content-Type': 'application/json'}, body=expected_body))

        # Run the consumer code against the mock service
        with pact:
            client = UserClient(pact.uri)
            result = client.get_user('Ash')
            self.assertEqual(result, expected_body)

if __name__ == '__main__':
    unittest.main()

view raw JSON →