Skip to content

Test 00 Consumer

HTTP consumer test using Pact Python v3.

This module demonstrates how to write a consumer test using Pact Python's upcoming version 3. Pact, being a consumer-driven testing tool, requires that the consumer define the expected interactions with the provider.

In this example, the consumer defined in src/consumer.py is tested against a mock provider. The mock provider is set up by Pact and is used to ensure that the consumer is making the expected requests to the provider. Once these interactions are validated, the contracts can be published to a Pact Broker where they can be re-run against the provider to ensure that the provider is compliant with the contract.

A good source for understanding the consumer tests is the Pact Consumer Test section of the Pact documentation.

Functions

pact() -> Generator[Pact, None, None]

Set up the Pact fixture.

This fixture configures the Pact instance for the consumer test. It defines where the pact file will be written and the consumer and provider names. This fixture also sets the Pact specification to V4 (the latest version).

The use of yield allows this function to return the Pact instance to be used in the test cases, and then for this function to continue running after the test cases have completed. This is useful for writing the pact file after the test cases have run.

YIELDS DESCRIPTION
Pact

The Pact instance for the consumer tests.
Source code in examples/tests/v3/test_00_consumer.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
@pytest.fixture
def pact() -> Generator[Pact, None, None]:
    """
    Set up the Pact fixture.

    This fixture configures the Pact instance for the consumer test. It defines
    where the pact file will be written and the consumer and provider names.
    This fixture also sets the Pact specification to `V4` (the latest version).

    The use of `yield` allows this function to return the Pact instance to be
    used in the test cases, and then for this function to continue running after
    the test cases have completed. This is useful for writing the pact file
    after the test cases have run.

    Yields:
        The Pact instance for the consumer tests.
    """
    pact_dir = Path(Path(__file__).parent.parent.parent / "pacts")
    pact = Pact("v3_http_consumer", "v3_http_provider")
    yield pact.with_specification("V4")
    pact.write_file(pact_dir, overwrite=True)

test_get_existing_user(pact: Pact) -> None

Retrieve an existing user's details.

This test defines the expected interaction for a GET request to retrieve user information. It sets up the expected request and response from the provider and verifies that the response status code is 200.

When setting up the expected response, the consumer should only define what it needs from the provider (as opposed to the full schema). Should the provider later decide to add or remove fields, Pact's consumer-driven approach will ensure that interaction is still valid.

The use of the given method allows the consumer to define the state of the provider before the interaction. In this case, the provider is in a state where the user exists and can be retrieved. By contrast, the same HTTP request with a different given state is expected to return a 404 status code as shown in test_get_non_existent_user.

Source code in examples/tests/v3/test_00_consumer.py 
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def test_get_existing_user(pact: Pact) -> None:
    """
    Retrieve an existing user's details.

    This test defines the expected interaction for a GET request to retrieve
    user information. It sets up the expected request and response from the
    provider and verifies that the response status code is 200.

    When setting up the expected response, the consumer should only define what
    it needs from the provider (as opposed to the full schema). Should the
    provider later decide to add or remove fields, Pact's consumer-driven
    approach will ensure that interaction is still valid.

    The use of the `given` method allows the consumer to define the state of the
    provider before the interaction. In this case, the provider is in a state
    where the user exists and can be retrieved. By contrast, the same HTTP
    request with a different `given` state is expected to return a 404 status
    code as shown in
    [`test_get_non_existent_user`](#test_get_non_existent_user).
    """
    expected_response_code = 200
    expected: Dict[str, Any] = {
        "id": 123,
        "name": "Verna Hampton",
        "created_on": {
            # This structure is using the Integration JSON format as described
            # in the link below. The preview of V3 currently does not have
            # built-in support for matchers and generators, though this is on
            # the roadmap and will be available before the final release.
            #
            # <https://docs.pact.io/implementation_guides/rust/pact_ffi/integrationjson>
            "pact:matcher:type": "regex",
            "regex": r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}(Z|(\+|-)\d{2}:\d{2})",
            "value": datetime.now(tz=timezone.utc).isoformat(),
        },
    }
    (
        pact.upon_receiving("a request for user information")
        .given("user exists")
        .with_request(method="GET", path="/users/123")
        .will_respond_with(200)
        .with_body(json.dumps(expected))
    )

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

        assert response.status_code == expected_response_code
        assert expected["name"] == "Verna Hampton"
        datetime.fromisoformat(expected["created_on"]["value"])

test_get_non_existent_user(pact: Pact) -> None

Test the GET request for retrieving user information.

This test defines the expected interaction for a GET request to retrieve user information when that user does not exist in the provider's database. It is the counterpart to the test_get_existing_user and showcases how the same request can have different responses based on the provider's state.

It is up to the specific use case to determine whether negative scenarios should be tested, and to what extent. Certain common negative scenarios include testing for non-existent resources, unauthorized access attempts may be useful to ensure that the consumer handles these cases correctly; but it is generally infeasible to test all possible negative scenarios.

Source code in examples/tests/v3/test_00_consumer.py 
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
def test_get_non_existent_user(pact: Pact) -> None:
    """
    Test the GET request for retrieving user information.

    This test defines the expected interaction for a GET request to retrieve
    user information when that user does not exist in the provider's database.
    It is the counterpart to the
    [`test_get_existing_user`](#test_get_existing_user) and showcases how the
    same request can have different responses based on the provider's state.

    It is up to the specific use case to determine whether negative scenarios
    should be tested, and to what extent. Certain common negative scenarios
    include testing for non-existent resources, unauthorized access attempts may
    be useful to ensure that the consumer handles these cases correctly; but it
    is generally infeasible to test all possible negative scenarios.
    """
    expected_response_code = 404
    (
        pact.upon_receiving("a request for user information")
        .given("user doesn't exists")
        .with_request(method="GET", path="/users/2")
        .will_respond_with(404)
    )

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

        assert response.status_code == expected_response_code