pytest-httpserver Tutorial: Installation and 10 Practical Testing Examples

Introduction: pytest-httpserver is a pytest plugin that starts a simple HTTP server during testing, ideal for writing test cases that need to mock HTTP requests and responses.

Installation: Run pip install pytest-httpserver to install the plugin.

Example 1: Basic GET request – Scenario: Start an HTTP server listening on endpoint /test returning fixed content. Use requests to send GET and verify response.

Code:

from httpserver import HTTPServer import requests import pytest @pytest.fixture def httpserver_listen_port(): return 8000 def test_httpserver(httpserver): httpserver.expect_request("/test").respond_with_data("Hello, World!") response = requests.get(f"http://localhost:{httpserver.port}/test") assert response.text == "Hello, World!"

Output: PASSED

Example 2: POST request returning JSON – Scenario: Set up a POST route that receives JSON data and returns JSON response.

Code:

def test_httpserver(httpserver): httpserver.expect_request("/post", method="POST").respond_with_json({"message": "Received"}) response = requests.post(f"http://localhost:{httpserver.port}/post", json={"data": "Hello"}) assert response.json() == {"message": "Received"}

Output: PASSED

Example 3: Validate request headers – Scenario: Set up a route that checks for a specific header value.

Code:

def test_httpserver(httpserver): httpserver.expect_request("/header", headers={"X-Custom-Header": "My-Value"}).respond_with_data("Custom header received") response = requests.get(f"http://localhost:{httpserver.port}/header", headers={"X-Custom-Header": "My-Value"}) assert response.text == "Custom header received"

Output: PASSED

Example 4: Check query parameters – Scenario: Set up a route that inspects URL query parameters.

Code:

def test_httpserver(httpserver): httpserver.expect_request("/query", query_string="param=value").respond_with_data("Query param received") response = requests.get(f"http://localhost:{httpserver.port}/query?param=value") assert response.text == "Query param received"

Output: PASSED

Example 5: Multiple requests – Scenario: Set up a route that allows only a specific number of requests.

Code:

def test_httpserver(httpserver): httpserver.expect_request("/count").respond_with_data("Counting", times=2) response1 = requests.get(f"http://localhost:{httpserver.port}/count") response2 = requests.get(f"http://localhost:{httpserver.port}/count") response3 = requests.get(f"http://localhost:{httpserver.port}/count") assert response1.text == "Counting" assert response2.text == "Counting" assert response3.status_code == 404

Output: PASSED

Example 6: Return error status code – Scenario: Set up a route that returns a specific error status.

Code:

def test_httpserver(httpserver): httpserver.expect_request("/error").respond_with_status(404) response = requests.get(f"http://localhost:{httpserver.port}/error") assert response.status_code == 404

Output: PASSED

Example 7: Test redirects – Scenario: Set up a route that redirects to another URL.

Code:

def test_httpserver(httpserver): httpserver.expect_request("/redirect").respond_with_redirect("/target") response = requests.get(f"http://localhost:{httpserver.port}/redirect", allow_redirects=False) assert response.status_code == 302 assert response.headers["Location"] == "/target"

Output: PASSED

Example 8: File upload – Scenario: Set up a route that receives a file upload request.

Code:

def test_httpserver(httpserver): httpserver.expect_request("/upload", method="POST").respond_with_data("File uploaded") files = {'file': ('example.txt', 'Some file content'.encode('utf-8'))} response = requests.post(f"http://localhost:{httpserver.port}/upload", files=files) assert response.text == "File uploaded"

Output: PASSED

Example 9: Set timeout – Scenario: Set up a route that delays its response.

Code:

def test_httpserver(httpserver): httpserver.expect_request("/timeout", delay=2).respond_with_data("Delayed response") response = requests.get(f"http://localhost:{httpserver.port}/timeout", timeout=3) assert response.text == "Delayed response"

Output: PASSED

Example 10: Verify client certificate – Scenario: Set up a route that requires a client certificate.

Code:

import ssl def test_httpserver(httpserver): httpserver.expect_request("/cert", method="GET").respond_with_data("Certificate received") cert_file = "path/to/cert.pem" key_file = "path/to/key.pem" response = requests.get(f"https://localhost:{httpserver.port}/cert", verify=False, cert=(cert_file, key_file)) assert response.text == "Certificate received"

Output: PASSED

Note: For the certificate example, you need to generate an SSL certificate and key, and replace the paths. verify=False is used only for testing.