# responses: Mocking Python Requests for Robust Testing

This repository profile is provided by osrepos.com, an open source repository discovery platform.

Source: osrepos.com
Repository profile: https://osrepos.com/repo/getsentry-responses
Generated for open source discovery and AI-assisted research.

responses is a Python library designed to simplify the process of mocking the `requests` library during testing. It allows developers to define predictable HTTP responses, enabling isolated and reliable unit tests for applications that interact with external APIs. This utility is essential for ensuring test stability and speed by avoiding actual network calls.

GitHub: https://github.com/getsentry/responses
OSRepos URL: https://osrepos.com/repo/getsentry-responses

## Summary

responses is a Python library designed to simplify the process of mocking the `requests` library during testing. It allows developers to define predictable HTTP responses, enabling isolated and reliable unit tests for applications that interact with external APIs. This utility is essential for ensuring test stability and speed by avoiding actual network calls.

## Topics

- Python
- testing
- mocking
- HTTP
- requests
- development
- production

## Repository Information

Last analyzed by OSRepos: Tue Feb 17 2026 08:01:20 GMT+0000 (Western European Standard Time)
Detail views: 4
GitHub clicks: 5

## Safety Notice

OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything.

## Content

## 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:

bash
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:

python
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:

python
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:

python
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.

python
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.

## Links

*   **GitHub Repository**: [https://github.com/getsentry/responses](https://github.com/getsentry/responses)