responses: Mocking Python Requests for Robust Testing

Introduction

responses is a powerful utility library for mocking out the Python requests library. It enables developers to simulate HTTP responses in their tests, making it easier to write isolated, fast, and reliable unit tests for applications that depend on external APIs. With responses, you can register mock responses for specific URLs and HTTP methods, define custom status codes, headers, and body content, and even handle dynamic responses using callbacks. It supports various matching criteria for requests, including URL, query parameters, JSON bodies, and headers.

Installation

Installing responses is straightforward using pip:

pip install responses

Examples

Basic Usage

The core of responses involves registering mock responses and activating the mocking functionality, typically with the @responses.activate decorator:

import responses
import requests

@responses.activate
def test_simple_get():
    responses.get(
        "http://twitter.com/api/1/foobar",
        json={"error": "not found"},
        status=404,
    )
    resp = requests.get("http://twitter.com/api/1/foobar")
    assert resp.json() == {"error": "not found"}
    assert resp.status_code == 404

Context Manager

Alternatively, you can use responses as a context manager, which limits its scope to a specific block of code:

import responses
import requests

def test_my_api_context():
    with responses.RequestsMock() as rsps:
        rsps.add(
            responses.GET,
            "http://twitter.com/api/1/foobar",
            body="{}",
            status=200,
            content_type="application/json",
        )
        resp = requests.get("http://twitter.com/api/1/foobar")
        assert resp.status_code == 200

Matching Requests

responses provides powerful matchers to precisely control which mock response is returned based on the incoming request's attributes. This includes matching based on JSON encoded data, URL-encoded parameters, query parameters, request headers, and even custom keyword arguments.

Here's an example using a JSON body matcher:

import responses
import requests
from responses import matchers

@responses.activate
def test_json_matcher():
    responses.post(
        url="http://example.com/",
        body="one",
        match=[
            matchers.json_params_matcher({"page": {"name": "first", "type": "json"}})
        ],
    )
    resp = requests.request(
        "POST",
        "http://example.com/",
        headers={"Content-Type": "application/json"},
        json={"page": {"name": "first", "type": "json"}},
    )
    assert resp.status_code == 200

Dynamic Responses with Callbacks

For more complex scenarios, responses allows you to define dynamic responses using callback functions. These callbacks receive the incoming request and can return a custom status, headers, and body, enabling highly flexible test setups.

import json
import responses
import requests

@responses.activate
def test_dynamic_response():
    def request_callback(request):
        payload = json.loads(request.body)
        resp_body = {"value": sum(payload["numbers"])}
        headers = {"request-id": "123"}
        return (200, headers, json.dumps(resp_body))

    responses.add_callback(
        responses.POST,
        "http://calc.com/sum",
        callback=request_callback,
        content_type="application/json",
    )

    resp = requests.post(
        "http://calc.com/sum",
        json.dumps({"numbers": [1, 2, 3]}),
        headers={"content-type": "application/json"},
    )
    assert resp.json() == {"value": 6}

Why Use It

Using responses brings significant advantages to your Python testing workflow. It ensures that your tests are fast and deterministic, as they don't rely on external network conditions or slow API calls. By isolating your application logic from external dependencies, you can write more robust and reliable tests that accurately reflect your code's behavior. This also makes it easier to test error handling, edge cases, and different API responses without needing to set up complex test servers.