pytest-httpserver

1.1.5 · active · verified Fri Apr 10

pytest-httpserver is a Python package that allows you to start a real HTTP server for your tests. The server can be programmatically configured to respond to requests, providing an easy-to-use API to set up request handlers and shut down gracefully without configuration files or daemons. As the HTTP server runs in a separate thread and listens on a TCP port, it's compatible with any HTTP client. This library facilitates testing HTTP client applications and migrating between client libraries without rewriting tests. It is currently at version 1.1.5 and maintains an active release cadence, with multiple patch releases often occurring monthly or every few months.

Warnings

breaking Python 3.9 support was officially dropped in version 1.1.4. While code might still function, CI tests are no longer run for this version.
Fix: Upgrade your Python environment to version 3.10 or newer.
breaking Python 3.8 support was deprecated in version 1.1.2 to enable more robust type hinting. Users on 3.8 should expect potential compatibility issues and no active testing support.
Fix: Upgrade your Python environment to version 3.9 or newer. For full support and latest features, upgrade to Python 3.10+ as per the 1.1.4 requirements.
deprecated The `check_assertions()` method is less preferred starting from version 1.1.4. It is recommended to use the new `check()` method.
Fix: Replace `httpserver.check_assertions()` with `httpserver.check()`. The `check()` method calls both `check_assertions()` and `check_handler_errors()`, providing more comprehensive error checking.
gotcha Prior to version 1.1.0, there was a known issue where `httpserver` state could leak between function-scoped tests due to improper fixture teardown, leading to inconsistent test results.
Fix: Ensure you are using `pytest-httpserver` version 1.1.0 or newer. If upgrading is not possible, explicitly call `httpserver.clear()` at the end of each test to reset the server state.
gotcha When matching query parameters, do not include them directly in the URI path. The underlying Werkzeug library expects query parameters to be specified separately.
Fix: Use the `query_string` parameter in `expect_request` or similar methods. For example, `httpserver.expect_request("/foo", query_string="user=bar")` or `httpserver.expect_request("/foo", query_string={"user": "bar"})`.
breaking Version 1.0.0 introduced backward-incompatible changes to how request expectations are set. `httpserver.expect_request()` became a general function accepting a `handler_type` parameter, `expect_oneshot_request()` no longer accepts the `ordered` parameter, and `expect_ordered_request()` was introduced as a new method.
Fix: Review and update your usage of `expect_request`, `expect_oneshot_request`, and `expect_ordered_request` methods according to the 1.0.0 API documentation.

Install

pip install pytest-httpserver Install stable version

Imports

httpserver
```
def test_my_app(httpserver):
```
This is the primary pytest fixture provided by the library.
HTTPServer
```
from pytest_httpserver import HTTPServer
```
Used for type hinting or when using the library without pytest via its context API.

Quickstart

This quickstart demonstrates how to use the `httpserver` pytest fixture to set up an expected request for `/foobar` that responds with a JSON object. It then uses the `requests` library to make a call to the server's URL and asserts the response. The `url_for()` method constructs the full URL including the dynamically assigned port.

import requests

def test_json_client(httpserver):
    httpserver.expect_request("/foobar").respond_with_json({"foo": "bar"})
    
    response = requests.get(httpserver.url_for("/foobar"))
    assert response.status_code == 200
    assert response.json() == {"foo": "bar"}

# To run this, save as `test_example.py` and run `pytest` in the terminal.

view raw JSON →