# getsentry/responses architecture

> Architecture diagram of the GitHub repository getsentry/responses, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/getsentry/responses
- Repository: https://github.com/getsentry/responses

## Overview

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

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "User Layer"
        UserTest["User Test Code"]:::external
    end

    subgraph "Core Library" 
        Controller["Responses.activate / RequestsMock"]:::core
        Registry["Registry Layer<br>(FirstMatch, Ordered)"]:::core
        Matchers["Matching Subsystem"]:::core
        ResponseObjs["Response Objects<br>(Static, Callback, Passthrough)<br>global calls list"]:::core
    end

    subgraph "External Dependencies"
        Session["requests.Session.send (patched)"]:::external
        ExternalNetwork["External Network / Real Server"]:::external
        TestSuite["Test Suite"]:::external
    end

    subgraph "Extension Modules"
        Recorder["Recorder Subsystem"]:::extension
    end

    %% Data flows
    UserTest -->|"invoke HTTP"| Controller
    Controller -->|"intercept"| Session
    Session -->|"lookup"| Registry
    Registry -->|"match using"| Matchers
    Matchers -->|"returns chosen mock"| ResponseObjs
    ResponseObjs -->|"mock response"| UserTest

    Session -->|"passthrough"| ExternalNetwork
    ExternalNetwork -->|"real response"| Recorder
    Session -->|"record"| Recorder
    Recorder -->|"dump YAML"| Recorder

    %% Test Suite coverage
    TestSuite -->|"tests Controller"| Controller
    TestSuite -->|"tests Registry"| Registry
    TestSuite -->|"tests Matchers"| Matchers
    TestSuite -->|"tests Recorder"| Recorder
    TestSuite -->|"tests overall behavior"| ResponseObjs

    %% Click events
    click Controller "https://github.com/getsentry/responses/blob/master/responses/__init__.py"
    click Registry "https://github.com/getsentry/responses/blob/master/responses/registries.py"
    click ResponseObjs "https://github.com/getsentry/responses/blob/master/responses/__init__.py"
    click Matchers "https://github.com/getsentry/responses/blob/master/responses/matchers.py"
    click Recorder "https://github.com/getsentry/responses/blob/master/responses/_recorder.py"
    click TestSuite "https://github.com/getsentry/responses/tree/master/responses/tests/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef extension fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef external fill:#D3D3,stroke:#333,stroke-width:1px;
```
