pytest-pook

A pytest plugin for pook.

Installation

pip install pytest-pook

Pytest automatically finds and configures the plugin.

The project is only tested on the latest versions of pook and pytest.

Issue tracker

pytest-pook uses Sourcehut for issue tracking. You can also submit issues and participate in their discussions via email if you don't have a Sourcehut account: ~sara/pytest-pook@todo.sr.ht. Read documentation for Sourcehut's issue tracker here.

Usage

@pytest.mark.pook

Tests that rely on pook can be marked with @pytest.mark.pook. The mark wraps the test in pook.use() in a way compatible with pytest, that does not interfere with other marks. It also asserts that any declared pook mocks were actually matched. This prevents the easy mistake of declareing a mock intenteded to be matched, but that never matches. Normally this requires manually asserting pook.isdone() at the end of a test, but this is too easy to forget and is tedious anyhow.

Within the body of the test, use the global pook import to interact with pook for things like creating new mocks.

Use the mark's default behaviour as follows:

import pytest
import requests
import pook


@pytest.mark.pook
def test_network_call():
    pook.get("https://example.com").reply(200).body("Hello from pook")

    res = requests.get("https://example.com")

    assert res.text == "Hello from pook"

Delay pook activation

If your test requires real network calls to happen before pook is enabled, pass start_active=False to the mark to delay pook activation until pook.on is called:

import pytest
import requests
import pook


@pytest.mark.pook(start_active=False)
def test_network_call():
    fixture = requests.get("localhost:8080/my-fixture").json()

    (pook.post("https://example.com")
        .json(fixture)
        .reply(200)
        .body("Hello from pook"))

    pook.on()
    res = requests.get("https://example.com", data=fixture)

    assert res.text == "Hello from pook"

With this approach, you still get the benefits of automatic cleanup and checks, but can still make outbound network calls before pook starts capturing them later in your test.

Dangling or unused pending mocks

By default the plugin raises an exception if it detects if pending mocks exist after the test is finished. This helps catch the easy-to-miss edge case where a pook was intended to match a request but didn't match any. This is commonly caused either by the tested code not using a compatible HTTP library or by misconfigured mocks.

To disable this check, pass allow_pending_mocks=True to the mark. In this case, it is recommended to manually confirm the mocks are in the expected state at the end of the test.

Contributing

This project uses hatch to manage testing and development environments.

Linting

Configure linting before you start development with hatch run installprecommit.

Run the linter at any time with hatch run lint.

Tests

Tests run with pytest in the hatch test environment. Tests are configured to run with all supported Python versions. Run tests for all versions:

hatch run test:test

To run tests only for a specific environment:

hatch run test.py3.12:test

Changelog

1.0.0

Initial stable release of the plugin.