pact-python

The example is divided into four main functional areas:

• Consumer: An async HTTP client implemented using aiohttp.
• Provider: A web server implemented using Flask.
• Consumer Tests: Contains the logic for contract definition and consumer-side testing.
• Provider Tests: Contains the logic for provider verification against the defined contracts.

This structure demonstrates a contract-driven development workflow where the consumer defines expectations and the provider verifies it can meet them.

This example is structured into four main components to demonstrate a complete contract-driven development workflow:

• Consumer: A synchronous HTTP client implemented using the requests library.
• Provider: A web server implemented using FastAPI.
• Consumer Tests: Where the contract is defined and the consumer is tested against a Pact mock server.
• Provider Tests: Where the provider is verified against the consumer-generated contracts.

This setup demonstrates how to handle different HTTP response scenarios (success, not found, etc.), manage provider state for different test scenarios, and maintain type safety using Python type hints.

Pact Python is an API contract testing tool designed to replace brittle end-to-end integration tests with fast, reliable unit tests. It supports:

• HTTP/REST and event-driven systems.
• Configurable mock servers.
• Powerful matching rules to prevent brittle tests.
• CI/CD integration via Pact Broker or PactFlow.

It is used to prevent breaking changes, document APIs, and reduce the cost and complexity of API integration testing.

The examples/http/ directory provides several implementation patterns for HTTP-based contract testing using Pact Python. You can use these examples to understand how to integrate Pact with different Python web frameworks and HTTP clients:

• Async patterns: Use aiohttp_and_flask/ to see an asynchronous aiohttp consumer interacting with a Flask provider.
• Synchronous patterns: Use requests_and_fastapi/ to see a requests client interacting with a FastAPI provider.
• Dual-role services: Use service_consumer_provider/ to see how a single service can be configured to act as both a consumer and a provider.
• XML payloads: Use xml_example/ to see how to perform contract testing when using requests and FastAPI with XML bodies instead of JSON.

The examples/ directory contains self-contained scenarios. Each example uses its own pyproject.toml for dependency management, allowing you to run them independently.

Available Example Categories

• Patterns Catalog: Focused code snippets demonstrating specific Pact patterns (examples/catalog/).
• HTTP Examples:
  • aiohttp client and Flask server (examples/http/aiohttp_and_flask/).
  • requests client and FastAPI server (examples/http/requests_and_fastapi/).
  • A single service acting as both Consumer and Provider (examples/http/service_consumer_provider/).
• Message Examples: (Work in progress) examples/message/.
• Plugin Examples: (Work in progress) examples/plugins/.

Pact is a consumer-driven contract testing tool that ensures services (consumers and providers) can communicate correctly.

The Workflow

1. Consumer Side: The consumer defines expected interactions (Given a state, Upon receiving a request, Will respond with a response). Consumer tests run against a Pact mock server that simulates the provider. Once tests pass, the generated contract is published to a Pact Broker.
2. Provider Side: The provider retrieves contracts from the Pact Broker. Provider tests run against the actual provider implementation. Pact uses a mock client to replay the requests defined in the contract and verifies that the provider's responses match the expectations.
3. Pact Broker: Acts as the central repository for storing contracts, verification results, and managing the compatibility matrix between consumers and providers.

Starting with Pact Python version 3, the library integrates with a Rust-based core library. This Rust core handles fundamental Pact operations including:

• Parsing and serializing Pact files.
• Matching requests with responses.
• Generating new Pact contracts.
• Providing mocking capabilities to simulate a provider during consumer verification.
• Replaying consumer requests against a provider during provider verification.

This integration uses a Python C Foreign Function Interface (CFFI) to bridge the gap between the Python interpreter and the high-performance Rust binary, allowing the Rust core to be imported and used as a standard Python module.

The versioning of pact-python-cli is aligned with the Pact CLI versioning. The version number follows the pattern [Pact CLI version].[release index].

For example, version 2.4.26.2 corresponds to Pact CLI version 2.4.26, where the .2 indicates that this is the third release of that specific Pact CLI version within the Python package (the first release being .0).

For the most robust contracts, use matchers to validate incoming request data and generators to produce dynamic response data. This ensures you validate the correct structure while simulating varied, real-world API behavior.

# Request validation with matchers
request_body = {
    "email": match.regex("user@example.com", regex=r".+@.+\..+"),
    "age": match.int(25, min=18, max=100),
    "preferences": match.array_containing([match.str("notifications")]),
}

# Response generation with dynamic data
response_body = {
    "id": generate.int(min=100000, max=999999),
    "email": match.str("user@example.com"),  # Echo back the input
    "verification_token": generate.uuid(),  # Fresh token each time
    "created_at": generate.datetime("%Y-%m-%dT%H:%M:%S%z"),
    "profile_url": generate.mock_server_url(
        example="/profiles/12345", regex=r"/profiles/\d+"
    ),
}