Add example for using requests-cache with responses

4 files changed, 93 insertions, 1 deletions

diff --git a/docs/advanced_usage.md b/docs/advanced_usage.md
index eba019e..fd65db3 100644
--- a/docs/advanced_usage.md
+++ b/docs/advanced_usage.md
@@ -417,3 +417,13 @@ To turn that into a complete example:
 ```{literalinclude} ../tests/compat/test_requests_mock_load_cache.py
 ```
 :::
+
+### Responses
+Usage with the [responses](https://github.com/getsentry/responses) library is similar to the
+requests-mock examples above.
+
+:::{admonition} Example code
+:class: toggle
+```{literalinclude} ../tests/compat/test_responses_load_cache.py
+```
+:::
\ No newline at end of file
diff --git a/poetry.lock b/poetry.lock
index e643b9e..cd8fa12 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -891,6 +891,22 @@ fixture = ["fixtures"]
 test = ["fixtures", "mock", "purl", "pytest", "sphinx", "testrepository (>=0.0.18)", "testtools"]
 
 [[package]]
+name = "responses"
+version = "0.13.3"
+description = "A utility library for mocking out the `requests` Python library."
+category = "dev"
+optional = false
+python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*"
+
+[package.dependencies]
+requests = ">=2.0"
+six = "*"
+urllib3 = ">=1.25.10"
+
+[package.extras]
+tests = ["coverage (>=3.7.1,<6.0.0)", "pytest-cov", "pytest-localserver", "flake8", "pytest (>=4.6,<5.0)", "pytest (>=4.6)", "mypy"]
+
+[[package]]
 name = "rich"
 version = "10.7.0"
 description = "Render rich text, tables, progress bars, syntax highlighting, markdown and more to the terminal"
@@ -1266,7 +1282,7 @@ yaml = ["cattrs"]
 [metadata]
 lock-version = "1.1"
 python-versions = "^3.6"
-content-hash = "b50d2aa5beb53dc09e67119f21e1371fe359491baa38e9045d2fd3b533df9af8"
+content-hash = "b929dee81e6ded9ed88ac9fb34d526956c876407d66673bd4205a0e8a85ca203"
 
 [metadata.files]
 alabaster = [
@@ -1851,6 +1867,10 @@ requests-mock = [
     {file = "requests-mock-1.9.3.tar.gz", hash = "sha256:8d72abe54546c1fc9696fa1516672f1031d72a55a1d66c85184f972a24ba0eba"},
     {file = "requests_mock-1.9.3-py2.py3-none-any.whl", hash = "sha256:0a2d38a117c08bb78939ec163522976ad59a6b7fdd82b709e23bb98004a44970"},
 ]
+responses = [
+    {file = "responses-0.13.3-py2.py3-none-any.whl", hash = "sha256:b54067596f331786f5ed094ff21e8d79e6a1c68ef625180a7d34808d6f36c11b"},
+    {file = "responses-0.13.3.tar.gz", hash = "sha256:18a5b88eb24143adbf2b4100f328a2f5bfa72fbdacf12d97d41f07c26c45553d"},
+]
 rich = [
     {file = "rich-10.7.0-py3-none-any.whl", hash = "sha256:517b4e0efd064dd1fe821ca93dd3095d73380ceac1f0a07173d507d9b18f1396"},
     {file = "rich-10.7.0.tar.gz", hash = "sha256:13ac80676e12cf528dc4228dc682c8402f82577c2aa67191e294350fa2c3c4e9"},
diff --git a/pyproject.toml b/pyproject.toml
index a558ff1..be5a1c6 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -74,6 +74,7 @@ pytest-order = "1.0"
 pytest-xdist = ">=2.2"
 radon = "^5.0"
 requests-mock = "^1.8"
+responses = ">=0.13"
 rich = ">=10.0"
 timeout-decorator = "^0.5"
 types-pyyaml = ">=5.4.3"
diff --git a/tests/compat/test_responses_load_cache.py b/tests/compat/test_responses_load_cache.py
new file mode 100644
index 0000000..d9a35b7
--- /dev/null
+++ b/tests/compat/test_responses_load_cache.py
@@ -0,0 +1,61 @@
+"""Example of using requests-cache with the responses library"""
+from contextlib import contextmanager
+from os.path import dirname, join
+from unittest.mock import patch
+
+import pytest
+import requests
+from responses import RequestsMock, Response
+from requests.exceptions import ConnectionError
+from requests_cache import CachedSession
+
+TEST_DB = join(dirname(__file__), 'httpbin_sample.test-db')
+TEST_URLS = [
+    'https://httpbin.org/get',
+    'https://httpbin.org/html',
+    'https://httpbin.org/json',
+]
+PASSTHRU_URL = 'https://httpbin.org/gzip'
+UNMOCKED_URL = 'https://httpbin.org/ip'
+
+
+@contextmanager
+def get_responses():
+    """Contextmanager that provides a RequestsMock object mocked URLs and responses
+    based on cache data
+    """
+    with RequestsMock() as mocker:
+        cache = CachedSession(TEST_DB).cache
+        for response in cache.values():
+            mocker.add(
+                Response(
+                    response.request.method,
+                    response.request.url,
+                    body=response.content,
+                    headers=response.headers,
+                    status=response.status_code,
+                )
+            )
+        mocker.add_passthru(PASSTHRU_URL)
+        yield mocker
+
+
+# responses patches HTTPAdapter.send(), so we need to patch one level lower to verify request mocking
+@patch.object(
+    requests.adapters.HTTPAdapter, 'get_connection', side_effect=ValueError('Real request made!')
+)
+def test_mock_session(mock_http_adapter):
+    """Test that the mock_session fixture is working as expected"""
+    with get_responses():
+        # An error will be raised if a real request is made
+        with pytest.raises(ValueError):
+            requests.get(PASSTHRU_URL)
+
+        # All mocked URLs will return a response based on requests-cache data
+        for url in TEST_URLS:
+            response = requests.get(url)
+            assert getattr(response, 'from_cache', False) is False
+
+        # responses will raise an error for an unmocked URL, as usual
+        with pytest.raises(ConnectionError):
+            requests.get(UNMOCKED_URL)