Responses：mock requests 的实用工具

Sentry 开源的 Python 测试工具 Responses，目前积累了 4,349 Star：

Responses 是一个用于 mock Python requests 库的实用工具。它可以在测试中拦截 HTTP 请求，返回预设的响应数据，避免对外部服务产生真实调用。

核心用法

Responses 的核心机制是通过装饰器注册 mock 响应。使用 @responses.activate 装饰测试函数后，所有 requests 调用都会被拦截，根据注册规则返回对应结果。

它也提供了快捷方法，如 responses.get()、responses.post()、responses.put() 等，省去了手动传入 HTTP 方法的步骤。

除了装饰器模式，Responses 还支持上下文管理器。在 with responses.RequestsMock() 块内，请求被 mock；离开块后，恢复真实网络行为。

请求匹配

Responses 内置了多种匹配器，用于精确验证请求内容：

• json_params_matcher：匹配 JSON 格式的请求体
• urlencoded_params_matcher：匹配 URL 编码数据
• query_param_matcher：匹配查询参数
• header_matcher：匹配请求头
• fragment_identifier_matcher：匹配 URL 片段标识符
• request_kwargs_matcher：匹配请求关键字参数

如果内置匹配器不够用，也可以创建自定义匹配器，返回布尔值和失败原因字符串即可。

响应注册表

Responses 默认采用 FirstMatchRegistry，多个响应对应同一 URL 时，按注册顺序依次返回并移除。如果需要强制按顺序执行，可以切换到 OrderedRegistry。也支持继承 FirstMatchRegistry 实现自定义查找逻辑。

动态响应

通过 add_callback 方法，可以传入回调函数根据请求内容动态生成响应。回调函数接收 request 对象，返回状态码、响应头和响应体三元组。URL 参数支持正则表达式，一个回调可以覆盖多个路径。

测试框架集成

Responses 与主流测试框架配合良好。安装 pytest-responses 包后，可以直接在 pytest 测试函数中注入 responses fixture。对于 unittest，也提供了 start、stop、reset 方法，方便在 setUp 和 tearDown 中管理 mock 生命周期。

其他功能

• 断言未触发的已注册请求
• 统计每个响应的调用次数
• 为同一 URL 注册多个按序返回的响应
• 模拟 URL 重定向链
• 透传特定请求到真实服务器
• 运行时替换或移除已注册的响应
• 支持协程和多线程环境

安装

Responses 要求 Python 3.8 以上，requests 版本不低于 2.30.0。通过 pip 安装：

pip install responses

或使用 pytest 集成包：

pip install pytest-responses

录制与回放（BETA）

Responses 提供了实验性的录制功能。给函数加上 @responses._recorder.record() 装饰器，执行真实请求后会将响应数据以 YAML 格式保存到指定文件。后续测试中可以通过 responses._add_from_file() 从文件加载这些响应，快速复现相同的 mock 环境。

对于需要频繁对接口进行单元测试的 Python 项目，Responses 是一个直接可用的选择。它覆盖了常见的 mock 场景，API 设计与 requests 保持一致，学习成本较低。

on 项目，Responses 是一个直接可用的选择。它覆盖了常见的 mock 场景，API 设计与 requests 保持一致，学习成本较低。