pook - HTTP traffic mocking

Common errors

• pook.errors.NoMatches: No matching mock for request: GET https://example.com/data

  cause The outgoing HTTP request did not match any of the currently active mocks. This can be due to discrepancies in URL, method, headers, query parameters, or request body.
  fix Carefully review your mock definition (`pook.get('url', ...)`) and the actual outgoing request to ensure all criteria (URL, method, headers, query, body) exactly match. Ensure `pook` is activated for the scope of the request.

• TypeError: Response.body() got an unexpected keyword argument 'binary'

  cause You are using `pook` version 2.0.0 or higher, which removed the `binary` parameter from the `Response.body()` method.
  fix Remove the `binary=True/False` argument from your `pook.response().body()` call. `pook` now handles byte encoding automatically.

• RuntimeError: There is an activated pook mock that has not been called: GET https://example.com/uncalled

  cause A mock expectation was set and `pook` was activated, but the corresponding HTTP request that would satisfy this mock was never made within the active scope.
  fix Ensure all mocks you define are actually hit by an outgoing HTTP request. If a mock is optional or should not trigger an error if uncalled, use `times(0)` or `persist()` as appropriate.

• ModuleNotFoundError: No module named 'pook'

  cause The `pook` library is not installed in the Python environment you are currently using.
  fix Install `pook` using pip: `pip install pook`. If using a virtual environment, ensure it is activated.

Warnings

• breaking The `Response::body`'s `binary` parameter was removed, and `chunked` is now an enforced keyword-only argument. Responses are now always byte-encoded.
  Fix: Remove the `binary` parameter from `pook.response().body()`. Ensure `chunked` is passed as a keyword argument (e.g., `body('content', chunked=True)`).
• breaking Support for Python 3.9 and PyPy 3.10 was dropped in version 2.1.5. Support for Python 3.8 was dropped in version 2.1.0.
  Fix: Upgrade your Python environment to 3.10 or newer. For projects requiring older Python versions, pin `pook<2.1.0` (for Python 3.8) or `pook<2.1.5` (for Python 3.9/PyPy 3.10).
• gotcha Mocks might leak between test cases when `pook.activate()` was used as a wrapper, potentially leading to confusing test failures or unexpected behavior.
  Fix: Upgrade to `pook` version 2.1.1 or newer. This version includes a fix to automatically flush mocks when `pook.activate` is used as a decorator or context manager. Always ensure `pook.flush()` is called after each test or test suite runs.

Install

• pip install pook Install pook

Imports

• pook

  import pook

• on

  import pook
  
  @pook.on

  Decorator to activate pook for a test function
• use

  import pook
  
  with pook.use():

  Context manager to activate pook within a block

Quickstart

This quickstart demonstrates how to mock an HTTP GET request using `pook` with the `requests` library. It sets up an expectation for a specific URL, activates the mock, makes the request, and then asserts the mocked response. Remember to deactivate and flush mocks to prevent state leakage between tests.

import pook
import requests
import os

# Configure a mock for a GET request
pook.get('https://api.example.com/data', reply=200, response_json={'status': 'ok', 'data': [1, 2, 3]})

# Activate pook (can also use @pook.on decorator or with pook.use():)
pook.activate()

try:
    # Make a request using requests, which pook will intercept
    response = requests.get('https://api.example.com/data')

    print(f"Status Code: {response.status_code}")
    print(f"Response JSON: {response.json()}")

    assert response.status_code == 200
    assert response.json() == {'status': 'ok', 'data': [1, 2, 3]}

finally:
    # Always deactivate pook and clear mocks to avoid leakage
    pook.off()
    pook.flush()