How getsentry/responses works
Project Type and Purpose
• This is an open-source Python library (“responses”) for mocking HTTP calls made via the popular requests library.
• It provides decorators and context managers (@responses.activate, ResponsesMock) that intercept outbound HTTP requests in test code, match them against registered mocks, and return preconfigured responses.
High-Level File Structure and Architectural Patterns
• Top-level configuration files: CI/CD workflows (.github/workflows), linting and test configs (tox.ini, mypy.ini, pre-commit), packaging scripts (setup.py, pyproject.toml, Makefile).
• responses/ package directory, containing:
• _recorder.py – captures and persists real HTTP responses to YAML (recorder subsystem).
• matchers.py – predicate functions to match incoming requests (matcher subsystem).
• registries.py – registry implementations (FirstMatchRegistry, OrderedRegistry, etc.).
• __init__.py – public API (add, get, activate, RequestsMock).
• responses/tests/ – exhaustive pytest test suite verifying every feature.
Core Components
a. RequestMock Controller
• Exposed via @responses.activate decorator or with responses.RequestsMock() as rsps:.
• Internally patches requests.Session.send to reroute HTTP calls.
b. Registry Layer
• Holds registered Response or CallbackResponse objects in a Registry (FirstMatch or Ordered).
• Exposes operations: add, replace, remove, reset.
c. Response Objects
• Static mocks (status, headers, body, json).
• Dynamic mocks via callbacks.
• PassthroughResponse for forwarding to real network.
d. Matching Subsystem
• Matchers in responses.matchers validate URL, method, headers, query params, body, kwargs.
• Registry uses matchers to pick correct mock.
e. Call Recording
• responses.calls global list logs all Call objects (request+response pairs).
• _recorder module to capture and dump real HTTP interactions.
f. Integration Points
• The requests library (specifically Session.send) is monkey-patched.
• Test frameworks: pytest via pytest-responses plugin, unittest through decorator or fixture.
Relationships and Data Flow
1. User Test Code invokes requests.get/post/... within an activated Responses context.
2. RequestsMock intercepts the call by overriding Session.send.
3. Registry is queried for matching Response entries.
4. Matchers run against the actual PreparedRequest; on match, the corresponding Response (or callback result) is returned.
5. The fake response is returned to the user’s test, and the call is appended to responses.calls.
6. If recording is enabled, _recorder listens to real requests and writes YAML.
Architectural Patterns and Principles
• Decorator/Context Manager pattern for interception lifecycle.
• Inversion of Control by patching the requests send logic.
• Strategy/Matcher pattern: decoupled matchers for extensible request validation.
• Registry pattern for managing mock response lifecycles and injection order.
• Separation of Concerns: mocking core, matching logic, recording logic, and CLI/scripts are isolated.