pytest-httpbin

Common errors

• ModuleNotFoundError: No module named 'httpbin'

  cause You are attempting to explicitly import `httpbin` or other fixtures from `pytest-httpbin`.
  fix pytest fixtures are automatically discovered and injected. Do not `import httpbin`. Instead, declare `httpbin` as an argument in your test function signature, e.g., `def test_my_feature(httpbin): ...`

• requests.exceptions.SSLError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed

  cause You are making an HTTPS request to `httpbin_secure` without providing the necessary CA certificate for verification, or without disabling verification.
  fix Ensure your test function accepts the `httpbin_ca_bundle` fixture and pass its value to your HTTP client's `verify` parameter: `requests.get(httpbin_secure.url, verify=httpbin_ca_bundle)`.

• This version of pytest-httpbin requires Python 3.7 or higher, but you are running Python X.Y.

  cause You are trying to install or run `pytest-httpbin` version 2.0.0 or higher on an unsupported Python version.
  fix Upgrade your Python environment to 3.7 or newer, or downgrade `pytest-httpbin` by pinning it to a version less than 2.0.0 (e.g., `pip install 'pytest-httpbin<2.0.0'`).

• requests.exceptions.ConnectionError: ('Connection aborted.', BadStatusLine(''))

  cause This error can occur if the local httpbin server crashes or is prematurely shut down, potentially due to rapid consecutive requests in older versions or specific test setups.
  fix Ensure you are using a recent `pytest-httpbin` version (>=0.0.4 addressed some issues). If the problem persists, review your test logic for potential server overloading or race conditions, or ensure sufficient time between requests if making many calls in one session.

Warnings

• breaking Version 2.0.0 dropped support for older Python versions (2.6, 2.7, 3.4, 3.5, 3.6). It introduced support for Python 3.7+ (up to 3.12).
  Fix: Ensure your project uses Python 3.7 or newer before upgrading to `pytest-httpbin` 2.x. If you must use older Python, pin `pytest-httpbin` to `<2.0.0`.
• breaking Version 1.0.0 updated the self-signed certificate provided by `httpbin_secure` to include the IP address in the Subject Alternative Name (SAN). This could be a breaking change for tests that explicitly depended on the certificate *not* having the IP address in the SAN.
  Fix: Review tests that explicitly manipulate or inspect the SSL certificate provided by `httpbin_secure`. Most users verifying with `httpbin_ca_bundle` should be unaffected.
• gotcha When using the `httpbin_secure` fixture for HTTPS tests, client-side SSL verification will fail unless you explicitly pass the `httpbin_ca_bundle` fixture's path to your HTTP client's `verify` parameter.
  Fix: Always use `verify=httpbin_ca_bundle` (e.g., `requests.get(httpbin_secure.url, verify=httpbin_ca_bundle)`) when making requests to `httpbin_secure` in your tests.
• gotcha The httpbin server can be configured to run on a fixed port by setting `HTTPBIN_HTTP_PORT` or `HTTPBIN_HTTPS_PORT` environment variables before running pytest. If not set, a random available port is chosen.
  Fix: To specify a port, define the environment variable before running pytest, e.g., `HTTPBIN_HTTP_PORT=8000 pytest`.

Install

• pip install pytest-httpbin requests Install stable version (includes requests for quickstart)

Imports

• httpbin
  wrong:

  from pytest_httpbin import httpbin

  correct:

  def test_example(httpbin):
      # httpbin fixture is automatically discovered by pytest and passed as argument
      response = requests.get(httpbin.url + '/get')

  pytest fixtures are automatically discovered and injected into test functions; explicit import is unnecessary and will lead to `ModuleNotFoundError` or incorrect usage.
• httpbin_secure
  wrong:

  from pytest_httpbin import httpbin_secure

  correct:

  def test_secure(httpbin_secure, httpbin_ca_bundle):
      # httpbin_secure fixture for HTTPS tests
      response = requests.get(httpbin_secure.url + '/get', verify=httpbin_ca_bundle)

  Same as 'httpbin', fixtures are discovered by pytest, not imported directly.
• httpbin_ca_bundle
  wrong:

  from pytest_httpbin import httpbin_ca_bundle

  correct:

  def test_ca_bundle(httpbin_secure, httpbin_ca_bundle):
      # httpbin_ca_bundle provides path to CA certificate for HTTPS verification
      response = requests.get(httpbin_secure.url + '/get', verify=httpbin_ca_bundle)

  Same as 'httpbin', fixtures are discovered by pytest, not imported directly.

Quickstart

Create a Python file (e.g., `test_my_app.py`) and define test functions that accept `pytest-httpbin` fixtures like `httpbin`, `httpbin_secure`, and `httpbin_ca_bundle`. Pytest will automatically discover and inject these fixtures. Run the tests using the `pytest` command in your terminal. Ensure `requests` is also installed (`pip install requests`) to make HTTP calls.

import pytest
import requests

def test_get_request(httpbin):
    """Test a simple GET request against the local httpbin instance."""
    print(f"Testing against httpbin at: {httpbin.url}")
    response = requests.get(httpbin.url + '/get')
    response.raise_for_status()
    data = response.json()
    assert data['headers']['Host'] == httpbin.host

def test_post_request(httpbin):
    """Test a POST request."""
    payload = {'key': 'value'}
    response = requests.post(httpbin.url + '/post', json=payload)
    response.raise_for_status()
    data = response.json()
    assert data['json'] == payload

def test_secure_request(httpbin_secure, httpbin_ca_bundle):
    """Test an HTTPS request with CA bundle verification."""
    print(f"Testing against secure httpbin at: {httpbin_secure.url}")
    # Note: requests must be explicitly told to verify with the provided CA bundle
    response = requests.get(httpbin_secure.url + '/get', verify=httpbin_ca_bundle)
    response.raise_for_status()
    data = response.json()
    assert data['headers']['Host'] == httpbin_secure.host

# To run this, save as `test_httpbin_example.py` and run `pytest` in your terminal.