Library / SDK
getsentry/responses avatar
getsentry/responses

responses mocks the requests library, and an unmatched URL is an error

A utility for mocking out the Python Requests library.

4,343 stars393 forksPythonApache-2.0

At a glance

What is it?
responses replaces the requests HTTP transport inside a test so no socket leaves the machine. It is strict by design: a URL nobody registered raises ConnectionError rather than returning an empty body.
Who is it for?
Adopt responses when your unit tests call requests directly and you want a missing mock to fail loudly as a ConnectionError, and keep a real HTTP client in the integration layer where the code runs outside the interpreter. Skip it if the code under test talks to anything other than requests, since nothing here intercepts other clients.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 12 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • getsentry/responses4,343 ★ · +1
Star history
Repository2026-09-232026-11-15
getsentry/responses4.3k4.3k

1 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Registering a Response so requests never opens a socket

responses does not run a fake server. It stands in front of the requests library inside your test process, so a test that would have reached the internet instead resolves a value you registered by hand. The audience is narrow and specific: engineers writing unit tests for Python services that call third party HTTP APIs with requests, where a live call makes the test slow, flaky or billable.

Registration takes one of two shapes. You build a responses.Response object and hand it to responses.add, or you pass the arguments directly. The method and url fields decide which request the mock answers; json sets the body and configures the Content-Type for you, and status sets the status code. Because the returned object is a genuine requests response, the same assertions work as in production code, down to checking resp.request.method after a PUT.

The scope is deliberately small. Only requests is covered. Code that opens a urllib3 pool directly, or that reaches an API through a different client library, is not intercepted by anything in this package.

An unregistered URL raises ConnectionError, not a 404

Here is the design decision that separates responses from looser fakes. If your code requests a URL that hits no registered mock, responses does not return a 404 and does not return an empty body. It raises ConnectionError, the same exception requests raises when a socket cannot be opened.

That choice is what makes the library useful in a regression suite. A test whose mock drifted out of sync with the production code fails loudly at the point of the call, with an exception type the calling code may already handle, instead of passing against a fabricated success. The trade is that a missing mock and a real network outage look identical to the code under test, and a reader of the traceback has to check the mock registry before they check the network.

There is also an escape hatch for this strictness. passthru_prefixes exists on responses.mock, and it lets registered URL prefixes reach the real network while everything else stays mocked. It is the option you reach for when part of a test genuinely depends on a live endpoint.

match_querystring and stream are still listed as Response parameters

The deprecation table in README.rst moves five items to new homes, and one detail there is easy to skim past. The Response Parameters section still describes match_querystring and stream as attributes you can pass, with DEPRECATED labels attached, even though the table above already sends both elsewhere. match_querystring is superseded by responses.matchers.query_param_matcher or responses.matchers.query_string_matcher, deprecated in 0.17.0. stream is deprecated from 0.15.0 in favour of passing stream to the request itself rather than to the mock.

match_querystring also carries a matching rule worth knowing, because it is silent failure by design. It is enabled by default only when the registered URL contains a query string, disabled when the URL has none, and disabled when the URL is a compiled regular expression. Register a plain URL with no query and the library will not compare query parameters at all.

Two more parameters behave in ways that are easy to misread. content_type defaults to text/plain, so a mock that returns JSON without the json argument will hand your code the wrong Content-Type header. auto_calculate_content_length is disabled by default, which means a supplied string or JSON body carries no calculated length unless you turn it on.

assert_all_requests_are_fired, passthru_prefixes and target moved to responses.mock

The 0.20.0 row of the deprecation table is the widest move in the project. responses.assert_all_requests_are_fired, responses.passthru_prefixes and responses.target were deprecated in 0.20.0, and the migration path is responses.mock.assert_all_requests_are_fired, responses.mock.passthru_prefixes and responses.mock.target. Anyone upgrading should rewrite three call sites.

The same pattern applies to the two matcher helpers deprecated in 0.14.0. responses.json_params_matcher and responses.urlencoded_params_matcher became responses.matchers.json_params_matcher and responses.matchers.urlencoded_params_matcher. The signature did not change; the namespace did.

Read that table as a maintenance signal about the project shape. Five deprecations across versions 0.14.0 to 0.20.0, each with a one line migration path, and the last push on this repository was on 2026-10-06. Setup.py pins the version at 0.26.3. The licence is Apache-2.0, which is permissive and carries no copyleft obligation on code that imports the package.

Installing the package and running the first mocked call

The install is a single pip command, and the runtime floor is stated in the README: Python 3.8 or newer, and requests 2.30.0 or newer.

bash
pip install responses

Setup.py is stricter than the README note. Its install_requires list pins requests>=2.30.0,<3.0 and urllib3>=1.25.10,<3.0 alongside pyyaml, and python_requires is >=3.8. A project pinned below that floor will not resolve cleanly with responses 0.26.3.

The first use is the decorator plus one registration. Wrap the test function with responses.activate, register a response for the URL your code calls, then make the call:

python
@responses.activate
def test_simple():
    responses.get(
        "http://twitter.com/api/1/foobar",
        json={"type": "get"},
    )
    resp_get = requests.get("http://twitter.com/api/1/foobar")
    assert resp_get.json() == {"type": "get"}

Check three things when that runs. The json body decodes without any header work, resp_get.status_code reads 200, and resp_get.request.method confirms which registered mock answered. The shortcuts responses.get, responses.post, responses.put, responses.delete, responses.head, responses.options and responses.patch are the same call as responses.add with the method prefilled.

RequestsMock keeps the mock scoped to one block of a test

The decorator covers an entire test function. When you only want the mock alive for part of a test, RequestsMock is the context manager form, and the example in the README registers a body, a status and an explicit content_type.

python
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

The behaviour worth planning for is at the exit. Once the block ends, requests is no longer patched, and the next call to the same URL goes to the remote server. A test that mixes a mocked assertion and a live assertion in one function therefore has a network dependency in its second half, which is the opposite of what the mock bought you. Keep the block tight around the code you are testing.

The Response object also accepts an Exception as its body, which is how you simulate a transport level failure inside a request that otherwise matches.

pytest-httpserver runs a real socket, which is the alternative approach

responses is not the only way to test code that calls requests. The difference is architectural, and this repository already depends on both worlds. Its own test extras include pytest-httpserver, alongside pytest, pytest-cov, pytest-asyncio and mypy. That library starts an actual HTTP server on a local port and points the client at it.

A local server approach does what an interceptor cannot. It exercises the real urllib3 connection path, real header serialisation and real chunked transfer, and your code under test is unaware that anything is standing in. It also forces you to deal with ports and with the possibility that the server is not reachable. An interceptor swaps the transport underneath requests, so the test is fast and hermetic, and it never proves that responses own transport works.

The repository comment in setup.py about checking different parsers in the recorder points at a third path, one where real traffic is recorded and replayed.

Editorial conclusion

Adopt responses when your unit tests call requests directly and you want a missing mock to fail loudly as a ConnectionError, and keep a real HTTP client in the integration layer where the code runs outside the interpreter. Skip it if the code under test talks to anything other than requests, since nothing here intercepts other clients. Verify first that your own pin for requests falls inside the setup.py range of requests>=2.30.0,<3.0, because responses installs beside the library it replaces the transport of, and a mismatch there breaks resolution rather than your assertions. Then check whether your tests depend on query string matching, since match_querystring is already deprecated and its default changes with the shape of the registered URL.

Frequently asked questions

What does the responses library require to run?

The README states that responses requires Python 3.8 or newer and requests 2.30.0 or newer. Setup.py pins the range as requests>=2.30.0,<3.0.

What happens when responses has no mock registered for a URL?

It raises ConnectionError, the same exception requests raises when a connection cannot be opened, rather than returning a fabricated status code.

How do I install the responses library?

The README gives one command: pip install responses. For a development checkout the Makefile installs the project in editable mode with the tests extra.

Which responses arguments have been deprecated?

json_params_matcher and urlencoded_params_matcher from 0.14.0, the stream argument from 0.15.0, match_querystring from 0.17.0, and assert_all_requests_are_fired, passthru_prefixes and target from 0.20.0. Each has a named replacement in the migration table.

Can responses mock only part of a test function?

Yes. RequestsMock is a context manager, so the mock applies inside the with block and requests is unpatched once the block exits. The README notes that a call after the block hits the remote server.

Official sources

  1. getsentry/responses on GitHub
  2. Issues
  3. License: Apache-2.0
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/getsentry-responses.svg)](https://hysenlabs.com/projects/getsentry-responses)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/getsentry-responses.svg)](https://hysenlabs.com/projects/getsentry-responses)

Was this useful?