df-test-framework 4.3.1__tar.gz → 4.4.2__tar.gz

{df_test_framework-4.3.1 → df_test_framework-4.4.2}/CHANGELOG.md

@@ -5,6 +5,72 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [4.4.2] - 2026-04-20
+
+### 🐛 修复
+
+- **(P2) `_check_observability` 漏报**：装饰器声明了显式依赖（如 `token="..."`）时，auto-inject 整体跳过，即使 `__init__` 有 `runtime` 形参也不会被注入，但原逻辑判断 `runtime in params` 就不告警。修复后仅以 `dependencies` 是否含 `runtime` 为判据，两种漏报场景均能告警，且文案区分"缺形参"与"依赖未点名"两种修复路径
+- **(P3) HTTP Context form body 明文泄露**：`_format_body` 对非 JSON 文本调用 `sanitize_message()` 时，该方法硬编码检查 `logging.enabled`，导致 `logging` 关闭而 `console` 开启时 form-urlencoded body 原样输出
+
+### ♻️ 重构
+
+- **统一脱敏 API**：将 `sanitize_dict(data, context="default")` 重命名为 `sanitize_data(data, context)`，`sanitize_message(text)` 重命名为 `sanitize_text(text, context)`；两个方法均要求显式传 `context`，消除硬编码上下文的历史问题。`sanitize_data` 同时支持顶层 `list`，allure observer 中的 list 元素循环可简化为一次调用
+- 所有输出通道（HTTP Context、console_debugger、Allure、structlog）均已对齐新 API
+
+### 📚 文档 & 模板
+
+- 重写 `docs/guides/sanitize_guide.md`，以"三条统一入口 + context 归属表 + 业务补字段"为主线，删除旧版散碎写法和错误的调试建议
+- 修正脚手架 `readme.py` 两处 `logging.sanitize: false`（无效路径）→ `sanitize.console.enabled: false`
+- 更新 `env_files.py` base 注释，从 `enabled/strategy` 改为 `sensitive_keys` 业务扩展示例
+
+## [4.4.1] - 2026-04-18
+
+### 🐛 修复
+
+- **(P1, 安全) `sanitize_header()` 不再绕过脱敏策略**: 早期实现把 Bearer 截断写死，忽略 `default_strategy` 配置，导致用户在生产环境设为 FULL/HASH 时仍会暴露明文。修复后 scheme-prefixed 短路仅在 `PARTIAL` 下生效，FULL/HASH 一律路由到 `sanitize_value` 得到 `******` 或 `sha256:xxx`
+- **(P2) HTTP Context 阶段覆盖**: 之前仅 `call` 阶段失败时注入，setup / teardown 失败拿不到上下文
+
+### 🔧 改进
+
+- 🩺 **`HttpRequestRecorder` 组件** (`testing/fixtures/http_recorder.py`): 轻量 HTTP 请求/响应缓存器，订阅 EventBus，自动排除认证类 URL，按 `correlation_id` 关联 Start/End 事件。`_pending` 中已发出但响应事件未到达的请求在格式化时附加 `← no response (async)` 标记
+- 🛟 **`_http_failure_section` autouse fixture** (`testing/fixtures/debugging.py`): 测试失败时自动把最近 3 次业务请求/响应作为 `HTTP Context` section 注入 pytest 报告。无需 `-s` / `--log-cli-level=DEBUG`，无需任何配置或显式声明，对所有测试生效；用例成功时不输出
+- 🔐 **`SanitizeService.sanitize_header()` 公共 API** (`infrastructure/sanitize/service.py`): HTTP header 专用脱敏方法，统一 ConsoleDebugObserver、AllureObserver、HttpRequestRecorder 三处实现
+- ✂️ **scheme-prefixed token 截断**: PARTIAL 策略下 `Authorization: Bearer eyJhbGciOi...KS8yo`（前 8 + ... + 后 5），覆盖 Bearer/Basic/Token/Digest/Mac/Hawk
+- **`ConsoleDebugObserver` HTTP header 输出**: 改为直接调用 `sanitize_header()`，与 `HttpRequestRecorder.format_section()` 输出格式完全一致；非 HTTP 路径（gRPC metadata、MQ 消息）的通用 `_sanitize_value` 行为保持不变
+- 🚧 **`ServiceClientObservabilityWarning`** (`testing/decorators/service_client.py`): `@service_client` 装饰的 `HttpClient`/`AsyncHttpClient` 子类未在 `__init__` 声明 `runtime` 参数时，注册期发出警告。提示用户：该客户端的 HTTP 请求会绕过 EventBus，失败 section / console_debugger / Allure attachment 都拿不到。CI 可通过 `filterwarnings = ["error::df_test_framework.testing.decorators.ServiceClientObservabilityWarning"]` 升级为错误
+
+### 📚 文档
+
+- 新增 [v4.4.1 发布说明](docs/releases/v4.4.1.md)
+- 更新 `docs/guides/sanitize_guide.md` —— 新增 "HTTP Header 脱敏" 小节
+- 更新 `docs/guides/fixtures_guide.md` —— 新增 "失败上下文 Fixture" 小节
+- 更新 `docs/guides/local_debug_quickstart.md` —— 业务失败时无需 `-s` 即可看到 HTTP Context
+- 更新 `docs/guides/service_client_guide.md` —— 所有 `HttpClient` 子类示例统一加 `runtime=None`；新增 "事件发布与可观测性（必读）" 章节
+
+---
+
+## [4.4.0] - 2026-04-17
+
+### ✨ 新增功能
+
+- 📐 **长链路前置造数 Fixture 链范式** (`cli/templates/project/fixture_chain_example.py`): 新增可复制的两层结构骨架，解决 E2E 测试 ≥3 步业务前置在 ≥2 个文件复用时的"跨文件偷 import 私有函数"坏味道
+  - **底层 step 函数**：公开签名 + `cleanup.add(...)` 内嵌，独立可调用
+  - **组合 + Fixture 层**：`provision_*(...)` 顶层语义函数 + `business_prerequisite` 一站式 fixture + `account_created` / `resource_created` 细粒度 fixture
+  - **数据契约**：每层返回 `@dataclass(frozen=True)` + `@property` 便捷访问
+  - **加载机制**：通过 `tests/conftest.py` 的 `pytest_plugins = ["{project}.fixtures.example_chain"]` 加载
+
+- 📦 **脚手架自动生成范式骨架**: `df-test init my-project --type api|full` 现会在 `src/{project}/fixtures/example_chain.py` 生成可改写的副本
+
+- 📚 **新增范式指南** (`docs/guides/fixture_chain_pattern.md`): 涵盖问题陈述、决策标准（何时启用 / 不启用）、两层结构、线性 vs 分叉链路、Cleanup 集成、反模式清单，以及 **UI 测试的对应思考**（默认推荐 `storage_state` + Page Object，仅当 ≥3 个 page action 业务流程才升级到链范式）
+
+### 🔧 改进
+
+- **`conftest.py` / `full_conftest.py` 模板**: 新增注释化 `pytest_plugins` 块，引导用户启用业务领域 fixture 链
+- **`fixtures_init.py` 模板**: 新增范式提示，避免在 `__init__.py` 里 `from .xxx_chain import *` 绕开 pytest fixture 注册的反模式
+- **`enhanced_gitignore` 模板**: `config/secrets/` → `config/secrets/*`，配合 `!.gitkeep` 和 `!.env.local.example` 例外规则正确生效
+
+---
+
 ## [4.3.1] - 2026-04-16
 
 ### 🔧 改进

{df_test_framework-4.3.1 → df_test_framework-4.4.2}/CLAUDE.md

@@ -127,6 +127,24 @@ def test_login(self): ...
 
 ## 版本发布
 
+### 版本号选择规则（语义化版本）
+
+**完整规范**: `docs/development/VERSION_CONTROL_RULES.md`
+
+**MAJOR / MINOR / PATCH 决策三问**（在改 `pyproject.toml` 前先回答）：
+
+1. 这是**独立的功能模块**吗？（不是现有功能的延续/增强）
+2. 值得**单独写一篇发布文档**吗？
+3. 用户会**专门为它升级**吗？
+
+- 三个都是 YES → **MINOR +1**（如新增 GraphQL 客户端、新增分布式追踪）
+- 否则 → **PATCH +1**（bug 修复、性能优化、内部统一、辅助方法、现有主题的延续补强）
+- 不兼容变更 / 移除 API / 升级最低 Python 版本 → **MAJOR +1**
+
+**核心原则**：MINOR 要克制，相关功能合并发布；PATCH 要积极，bug 立即修。
+
+### 发布步骤
+
 发布新版本时，严格按以下顺序执行：
 
 ### Step 1: 更新文件

{df_test_framework-4.3.1 → df_test_framework-4.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.3.1
+Version: 4.4.2
 Summary: 基于交互模式的现代化测试自动化框架，支持多种测试场景
 Project-URL: Homepage, https://github.com/yourorg/df-test-framework
 Project-URL: Repository, https://github.com/yourorg/df-test-framework

{df_test_framework-4.3.1 → df_test_framework-4.4.2}/docs/api-reference/testing.md

@@ -1161,7 +1161,7 @@ def test_create_card(
 | 维度 | @api_class | @service_client |
 |------|-----------|----------------|
 | 基类要求 | 必须继承 `BaseAPI` | 无要求 |
-| HTTP 客户端 | 共享框架的 `http_client` | 自行管理 |
+| HTTP 客户端 | 共享框架的 `http_client` | 推荐基于框架 `HttpClient` / `AsyncHttpClient` 自行封装 |
 | base_url | 从框架配置统一获取 | 通过 `base_url_config` 注入 |
 | 认证方式 | 框架中间件统一处理 | 各客户端自行实现 |
 
@@ -1171,6 +1171,25 @@ def test_create_card(
 
 `settings`、`database`、`async_database`、`redis_client`、`async_redis_client`、`runtime`、`rabbitmq_client`、`kafka_client`、`rocketmq_client`
 
+### 推荐写法
+
+当 fixture 本身就是“一个独立 HTTP 客户端”时，推荐直接继承框架 `HttpClient`：
+
+```python
+from df_test_framework import HttpClient
+from df_test_framework.testing.decorators import service_client
+
+
+@service_client("payment_client", base_url_config="business.payment_url")
+class PaymentClient(HttpClient):
+    def __init__(self, base_url: str, runtime=None) -> None:
+        super().__init__(base_url=base_url, max_retries=0, runtime=runtime)
+```
+
+> **v4.4.1 起强制要求**：`HttpClient` / `AsyncHttpClient` 子类必须在 `__init__` 声明 `runtime=None` 并透传给 `super().__init__()`，否则该客户端发出的 HTTP 请求不会经过 EventBus，失败 section 的 `HTTP Context`、`console_debugger`、Allure HTTP attachment 都拿不到。注册期会发出 `ServiceClientObservabilityWarning`。详见 [service_client_guide.md → 事件发布与可观测性](../guides/service_client_guide.md)。
+
+`@service_client` 仍兼容普通类和其他 HTTP 库，但那属于兼容场景，不是首选推荐。对于需要统一重试、中间件、事件发布和调试链路的项目，优先使用框架 `HttpClient` / `AsyncHttpClient`。
+
 ---
 
 ## 🔗 相关文档

{df_test_framework-4.3.1 → df_test_framework-4.4.2}/docs/architecture/failure-diagnosis-hook-example.py

@@ -43,10 +43,11 @@ def pytest_runtest_makereport(item, call):
                 # 附加到 Allure 报告
                 try:
                     import allure
+
                     allure.attach.file(
                         str(screenshot_path),
                         name="失败截图",
-                        attachment_type=allure.attachment_type.PNG
+                        attachment_type=allure.attachment_type.PNG,
                     )
                 except ImportError:
                     pass  # 未安装 allure-pytest，跳过
@@ -64,10 +65,11 @@ def pytest_runtest_makereport(item, call):
                     # 附加到 Allure 报告
                     try:
                         import allure
+
                         allure.attach.file(
                             str(video_path),
                             name="测试视频",
-                            attachment_type=allure.attachment_type.WEBM
+                            attachment_type=allure.attachment_type.WEBM,
                         )
                     except ImportError:
                         pass

df_test_framework-4.4.2/docs/guides/fixture_chain_pattern.md

@@ -0,0 +1,224 @@
+# 长链路前置造数：Fixture 链范式
+
+> **最后更新**: 2026-04-17
+> **适用版本**: v4.4.0+
+> **配套模板**: `cli/templates/project/fixture_chain_example.py`（脚手架生成 `src/{project}/fixtures/example_chain.py`）
+
+---
+
+## 目录
+
+- [问题：为什么需要这个范式](#问题为什么需要这个范式)
+- [何时启用 / 何时不启用](#何时启用--何时不启用)
+- [两层结构](#两层结构)
+- [完整示例](#完整示例)
+- [线性链路 vs 分叉链路](#线性链路-vs-分叉链路)
+- [Cleanup 集成](#cleanup-集成)
+- [反模式](#反模式)
+- [UI 测试的对应思考](#ui-测试的对应思考)
+
+---
+
+## 问题：为什么需要这个范式
+
+E2E 测试常常需要"建租户 → 建账号 → 建商品 → 建订单"这种 N 步业务前置。如果不抽取，会出现 3 类典型坏味道：
+
+1. **跨文件偷 import 私有函数**
+   `from tests.api.test_order_e2e import _step1_create_supplier`
+   → 修改测试 A 时悄悄改坏了测试 B；新成员不知道哪些 `_step` 是公共契约。
+
+2. **每个 e2e 文件复制一份相同的 7 步**
+   → 业务 schema 升级时要改 N 处；漏改一处 → 测试间断式失败。
+
+3. **fixture 写在 conftest 里没有清晰边界**
+   → conftest 越长越难读；fixture 之间的依赖关系隐式藏在闭包里。
+
+**本范式的目标**：让"业务前置数据链"成为一等公民——**有显式的模块、有公开的契约、有明确的扩展点**。
+
+---
+
+## 何时启用 / 何时不启用
+
+| 启用 | 不启用 |
+|------|--------|
+| E2E 测试有 ≥3 步业务前置 | 单测试只用 1-2 步 → 直接 inline |
+| 这套前置在 ≥2 个测试文件里复用 | 仅 1 个文件复用 → 抽到 module 顶部 helper |
+| 之前为了复用偷 `from tests.xxx import _step_*` | 单元测试 / mock 化测试 |
+| 业务链路有自然的"分叉点"（1 个账号 × 多个资源） | UI 测试以登录态为前置 → 优先 `storage_state` |
+
+**判断口诀**：拿出代码统计——单文件 + ≤2 步 → 不抽；多文件 + ≥3 步 → 抽。中间地带（如 2 文件 + 2 步）多半也不值得抽，等第 3 个文件出现再说。
+
+---
+
+## 两层结构
+
+```
+┌──────────────────────────────────────────────────────────┐
+│  二、组合 + Fixture 层（pytest 入口）                     │
+│   - business_prerequisite fixture（一站式，覆盖 80% 场景）│
+│   - account_created / resource_created（细粒度，分叉用） │
+│   - provision_*(...) 顶层语义函数（一次造完一段）         │
+└────────────────────────┬─────────────────────────────────┘
+                         │ 调用
+┌────────────────────────▼─────────────────────────────────┐
+│  一、底层 step 函数（pure function）                       │
+│   - step_create_account(...)                              │
+│   - step_create_resource(...)                             │
+│   - step_bind_resource_to_account(...)                    │
+│   签名公开、参数显式；cleanup.add(...) 内嵌                 │
+└──────────────────────────────────────────────────────────┘
+```
+
+**核心约定**：
+- **底层 step 函数公开签名**——`step_create_account(account_api, test_id, cleanup)`，不藏 `_` 前缀。
+- **每层返回 `frozen=True` 的 dataclass**，不返回 `dict` / `tuple`，避免下游用魔法字符串取值。
+- **dataclass 上加 `@property` 便捷访问**：`prerequisite.account_id` 比 `prerequisite.account.account_id` 更顺手。
+- **`provision_*(...)` 是顶层语义函数**，把"造一段链路"封装为一行调用，给分叉用例循环时用。
+- **fixture 分两档**：一站式（`business_prerequisite`）+ 细粒度（`account_created`），不要只提供一站式。
+
+---
+
+## 完整示例
+
+完整骨架见 `cli/templates/project/fixture_chain_example.py`。脚手架 `df-test init my-project --type api` 会在 `src/my_project/fixtures/example_chain.py` 生成可改写的副本。
+
+启用步骤（5 步）：
+
+```python
+# 1. 把模板里的 Account / Resource / Workflow 等占位实体替换为真实业务名词
+# 2. 把 step_* 内的 API 调用替换为真实业务调用
+# 3. 保留 cleanup.add(...) 内嵌写法（cleanup 与 step 同生命周期，调试时不易遗漏）
+# 4. 在 tests/conftest.py 添加：
+pytest_plugins = ["my_project.fixtures.example_chain"]
+
+# 5. E2E 测试直接消费 fixture：
+def test_main_flow(business_prerequisite):
+    assert business_prerequisite.account_id > 0
+    assert business_prerequisite.resource_id > 0
+```
+
+---
+
+## 线性链路 vs 分叉链路
+
+### 场景 A：线性 1×1×1（80% 用例）
+
+`business_prerequisite` 一站式 fixture 直接覆盖：
+
+```python
+def test_full_order_flow(order_prerequisite):
+    """完整下单链路：1 账号 + 1 商品 + 1 订单"""
+    place_order(order_prerequisite.account_id, order_prerequisite.resource_id)
+```
+
+### 场景 B：分叉 1 账号 × N 资源（如回调三态测试）
+
+不要为分叉造一个新 fixture——**直接消费细粒度 fixture + 在测试里循环调用 `provision_*`**：
+
+```python
+def test_callback_three_states(account_created, resource_api, binding_api,
+                                business_test_id, cleanup):
+    """1 账号 × 3 通道（成功/失败/处理中）"""
+    channels = {
+        ch_type: provision_resource(
+            resource_api, binding_api, account_created, business_test_id,
+            cleanup, resource_type=ch_type,
+        )
+        for ch_type in ("success", "fail", "processing")
+    }
+    for ch_type, ch in channels.items():
+        trigger_callback(account_created.account_id, ch.resource_id, state=ch_type)
+```
+
+**关键设计**：
+- `step_create_resource(..., resource_type="default")` 用 keyword-only 参数支持分叉。
+- `provision_resource(...)` 把"建+绑"打包成一次调用，循环时不必重复 step 序列。
+- 共用 `account_created` fixture，N 个资源真正复用 1 个账号。
+
+---
+
+## Cleanup 集成
+
+**约定**：`cleanup.add(key, id)` 必须**内嵌在 `step_*` 函数内**，不要让调用方手动注册。
+
+```python
+def step_create_account(account_api, test_id, cleanup) -> AccountData:
+    with step("步骤1: 新建账号"):
+        response = account_api.create(name=f"acct_{test_id}")
+        cleanup.add("account", response.id)  # ⭐ 内嵌，不依赖调用方
+        return AccountData(account_id=response.id, ...)
+```
+
+**理由**：
+- 造数 = 造 + 注册清理是一对原子操作，分开写迟早漏。
+- 调试时把 step 函数单独 import 也能正常清理。
+- `cleanup` fixture 是配置驱动的（`CLEANUP__MAPPINGS__*`），重复注册同一 ID 是幂等的。
+
+---
+
+## 反模式
+
+| ❌ 不要这样 | ✅ 改成这样 |
+|------------|------------|
+| `from tests.api.test_x import _step1, _step2` | 抽到 `src/{project}/fixtures/xxx_chain.py` |
+| `step` 函数返回 `dict` 或 `tuple` | 返回 `@dataclass(frozen=True)` |
+| `cleanup.add` 写在测试里 | 写在 `step_*` 函数里 |
+| 只提供一站式 `business_prerequisite` | 同时暴露 `account_created` 等细粒度 fixture |
+| 分叉用例新建一个 `branched_prerequisite` fixture | 复用 `account_created` + 循环调用 `provision_*` |
+| step 函数加 `_` 前缀 | 公开签名、放进 `__all__` |
+| 在 `fixtures/__init__.py` 里 `from .xxx_chain import *` | 通过 `pytest_plugins = [...]` 加载 |
+
+最后一条特别重要：**fixture 模块要通过 `pytest_plugins` 加载，不要在 `__init__.py` 里 import**。后者会绕开 pytest 的 fixture 注册机制，触发 collection 期的奇怪错误。
+
+---
+
+## UI 测试的对应思考
+
+UI 测试的"前置"和 API 测试形态不同，**默认不需要本范式**：
+
+### 默认方案：`storage_state` + Page Object
+
+> v4.0.3+ 框架原生支持 `storage_state`，详见 `docs/guides/auth_session_guide.md`。
+
+90% 的 UI 测试前置就是"已登录用户"，框架的 `AuthSetup` 已经把这一步做掉了：
+
+```python
+# tests/conftest.py
+@pytest.fixture(scope="session")
+def storage_state(auth_setup):
+    return auth_setup.create_state(login_func=lambda page: ...)
+
+# 测试里直接用 page，已是登录态
+def test_dashboard(page):
+    page.goto("/dashboard")
+    expect(page.get_by_text("Welcome")).to_be_visible()
+```
+
+这比 API 链路简单得多：UI 状态可以"序列化到磁盘 + 跨 session 复用"，而 API 业务数据通常需要每次新建（避免数据污染）。
+
+### 何时 UI 也用 Fixture 链范式
+
+仅当 **UI 业务流程 ≥3 个 page action 且在 ≥2 个测试文件里复用** 时才考虑。例如：
+
+- 配置向导：登录 → 选模板 → 填表单 → 预览 → 发布（5 步）
+- 商家入驻：登录 → 填资质 → 上传证件 → 提交审核 → 等待通过（5 步）
+
+UI 范式的对应映射：
+
+| API 范式 | UI 范式 |
+|---------|---------|
+| `step_create_xxx(api, ...)` | `step_xxx_action(page, ...)` |
+| `provision_*(...)` | `provision_ui_state(...)` |
+| `cleanup.add("table", id)` | 通常无需清理（storage_state 已隔离）|
+| 返回 `@dataclass(frozen=True)` | 返回 `@dataclass(frozen=True)`，记录 page state |
+| 通过 `pytest_plugins` 加载 | 通过 `pytest_plugins` 加载 |
+
+**警惕**：UI 链通常比 API 慢一个数量级（每步要等渲染），如果能用 API 造数 + UI 验证的组合，**优先用 API 造前置**，让 UI 只负责验证用户可见的部分。
+
+---
+
+## 参考
+
+- 完整范式骨架: `src/df_test_framework/cli/templates/project/fixture_chain_example.py`
+- 真实案例: `D:\Git\DF\master_test\src\master_test\fixtures\order_chain.py`（7 步下单前置链）
+- 相关文档: [Fixtures 使用指南](./fixtures_guide.md) · [测试数据管理](./test_data.md) · [认证会话指南](./auth_session_guide.md)

{df_test_framework-4.3.1 → df_test_framework-4.4.2}/docs/guides/fixtures_guide.md

@@ -1,7 +1,7 @@
 # Fixtures 使用指南
 
-> **最后更新**: 2026-03-03
-> **适用版本**: v3.0.0+
+> **最后更新**: 2026-04-18
+> **适用版本**: v3.0.0+；v4.4.1+ 新增 `_http_failure_section` autouse fixture
 
 ---
 
@@ -423,6 +423,71 @@ def test_with_test_runtime(test_runtime):
 
 ---
 
+### 失败上下文 Fixture（v4.4.1+，autouse）
+
+#### `_http_failure_section` - 失败时自动注入 HTTP 上下文
+
+**Scope**: `function`
+**自动**: 是（autouse=True，无需声明）
+**版本**: v4.4.1+
+**位置**: `df_test_framework/testing/fixtures/debugging.py`
+
+对所有测试自动生效，**不需要写在测试参数里、不需要任何配置**：
+
+- 测试开始时为该用例创建 `HttpRequestRecorder`，订阅当前 EventBus
+- 测试通过时不输出任何内容（不污染正常日志）
+- 测试在 **任意阶段（setup / call / teardown）** 失败时，把最近 3 次业务请求/响应作为
+  `HTTP Context` section 注入 pytest 报告
+
+#### 输出示例
+
+```text
+_______________________ TestOrder.test_create_order ______________________
+...
+E   AssertionError: 期望 retCode=0，实际为 1
+
+----------------------------- HTTP Context -----------------------------
+[1] POST https://api.example.com/orders  ← business failure
+    Request Headers:
+      Authorization: Bearer eyJhbGciOi...KS8yo
+      Content-Type: application/json
+    Request Body: {"product_id":"P001","quantity":2}
+    Response: ❌ 200  (123ms)
+      {"retCode":"1","retMsg":"IP地址非法,请求IP:113.57.21.67"}
+```
+
+三种 tag：
+
+| tag | 含义 |
+|-----|------|
+| `← business failure` | HTTP 状态码 ≥ 400，或响应体内 `retCode/code/errCode` 等键非成功值 |
+| `← request error` | 请求层异常（连接拒绝、超时、DNS 失败等） |
+| `← no response (async)` | 已发出 Start 事件但 End 事件尚未到达（async 时序兜底） |
+
+#### 配置
+
+无需任何配置。框架自动：
+
+- 排除认证类 URL（`/login/token`、`/auth/token`、`/oauth/token` 等），避免污染上下文
+- 缓存最近 **3** 条业务请求（队列大小由 `HttpRequestRecorder(max_records=3)` 控制）
+- header 输出走 `SanitizeService.sanitize_header()`，与 console / Allure 格式一致
+- request/response body 超过 500 字符自动截断并注明 `共 N 字符`
+
+#### 与 `console_debugger` / `debug_mode` 的区别
+
+| Fixture | 何时输出 | 是否需要 `-s` | 适用场景 |
+|---------|---------|--------------|----------|
+| `_http_failure_section` | **失败时**，写入 pytest section | 否 | 默认兜底，CI 失败排查 |
+| `console_debugger` | **每个请求实时**输出彩色调试信息 | 是 | 主动调试，本地开发 |
+| `debug_mode` | 同 `console_debugger`（依赖它） | 是 | 用例级别开关 |
+
+> **重要前置**：`HttpRequestRecorder` 通过订阅 `HttpRequest{Start,End,Error}Event` 工作。
+> 若项目里 `@service_client` 装饰类直接使用原生 `httpx.Client(...)` 而不是框架的
+> `HttpClient`，事件不会发布，section 自然拿不到这些请求。详见
+> [service_client 指南](service_client_guide.md)。
+
+---
+
 ## API 封装 Fixtures
 
 ### 自动加载机制（v3.45.0+）
@@ -1128,6 +1193,7 @@ def test_user_order_flow(user_api, order_api):
 
 ## 版本历史
 
+- **v4.4.1** (2026-04-18): 新增 `_http_failure_section` autouse fixture，失败时自动注入 `HTTP Context` section（覆盖 setup/call/teardown 全阶段）
 - **v4.1.0** (2026-03-03): Browser Session 复用，`browser_manager`/`browser` 提升为 session scope，context/page 保持 function scope 每测试隔离
 - **v4.0.0** (2026-01-16): 全面异步化，新增 `async_http_client`、`async_database`、`async_redis_client`、`async_page` 等异步 fixtures
 - **v3.45.0** (2025-12): 新增 `@api_class` 和 `@actions_class` 装饰器，API/Actions 自动加载

{df_test_framework-4.3.1 → df_test_framework-4.4.2}/docs/guides/local_debug_quickstart.md

@@ -1,7 +1,7 @@
 # 本地开发调试快速指南
 
-> **最后更新**: 2026-01-16
-> **适用版本**: v3.38.0+（本地调试配置）
+> **最后更新**: 2026-04-18
+> **适用版本**: v3.38.0+（本地调试配置）；v4.4.1+ 失败自动注入 HTTP Context section
 
 ---
 
@@ -140,6 +140,12 @@ uv run pytest tests/ -k "login or register" --env=local -v
 
 ### 失败调试
 
+> **v4.4.1+ 默认行为**：测试失败时框架自动在 pytest 报告里注入 `HTTP Context` section，
+> 显示最近 3 次业务请求/响应（含 headers / body / 状态码 / 耗时），**无需 `-s`，
+> 无需 `--log-cli-level=DEBUG`，无需任何 fixture 声明**。详见
+> [fixtures_guide.md → 失败上下文 Fixture](fixtures_guide.md#失败上下文-fixturev441autouse)。
+> 仅当需要观察 **成功用例** 的实时请求时，才需要 `-s` + `console_debugger`。
+
 ```bash
 # 首次失败即停止
 uv run pytest tests/ --env=local -x -v
@@ -332,6 +338,11 @@ uv run pytest tests/ --log-cli-level=DEBUG -v
 
 ### Q2: 想看到完整的请求/响应体？
 
+**失败用例（v4.4.1+ 默认）**：直接看 pytest 输出里的 `HTTP Context` section，
+无需任何额外标志。最近 3 次业务请求/响应已自动展开。
+
+**成功用例（主动调试）**：
+
 ```bash
 # 方式 1：环境变量
 OBSERVABILITY__DEBUG_OUTPUT=true uv run pytest tests/ -v -s
@@ -342,6 +353,11 @@ def test_api(http_client):
     pass
 ```
 
+> 三者职责区分：
+> - `_http_failure_section`（autouse，v4.4.1+）— 失败兜底，写 pytest section
+> - `console_debugger` / `debug_mode` — 实时输出，需要 `-s`
+> - `OBSERVABILITY__DEBUG_OUTPUT=true` — 全局打开 `console_debugger` 行为
+
 ### Q3: 如何在测试中打断点？
 
 ```python
@@ -423,5 +439,5 @@ uv run pytest tests/ --env=test -v
 
 ---
 
-**文档版本**: v1.0.0
-**最后更新**: 2025-12-26
+**文档版本**: v1.1.0
+**最后更新**: 2026-04-18（v4.4.1 失败自动注入 HTTP Context）