df-test-framework 4.1.0__tar.gz → 4.1.2__tar.gz

{df_test_framework-4.1.0 → df_test_framework-4.1.2}/CHANGELOG.md

@@ -5,6 +5,65 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [4.1.2] - 2026-03-16
+
+### ✨ 新增功能
+
+- ⏱️ **Per-request timeout**: `HttpClient`/`AsyncHttpClient` 支持单请求级别超时覆盖客户端默认值
+- 🔄 **AsyncHttpClient 同步版对齐**: 补齐 `head()`/`options()`/`request_raw()`/认证状态管理方法
+
+### 🔧 修复
+
+- 🔗 **绝对 URL 修复**: `_convert_to_httpx_response()` 对绝对 URL 不再错误拼接 base_url
+
+### 🗑️ 移除
+
+- **Worker 模块**: 移除 `worker/` 模块（app.py/schemas.py/__init__.py）及 `df-test-worker` 入口点
+  - 经调研 MeterSphere/HttpRunnerManager/testhub_platform，业界无测试平台使用独立 HTTP 服务转发模式
+  - OMS 测试平台应通过库导入方式（`from df_test_framework import AsyncHttpClient`）使用框架能力
+  - 框架回归纯粹的"库 + CLI 工具"定位
+
+### 📚 文档
+
+- 📝 API 参考、HTTP 客户端指南补充 v4.1.2 新增方法和用法
+
+## [4.1.1] - 2026-03-11
+
+### ✨ 新增功能
+
+- 🔄 **统一 Response 层**: `HttpClient`/`AsyncHttpClient` 的所有方法统一返回框架 `Response` 对象，不再返回 `httpx.Response`
+- ⏱️ **请求计时**: `Response` 新增 `elapsed` 字段（秒），自动记录每次请求耗时
+- 🧩 **Response 兼容方法**: 新增 `text` 属性、`json()` 方法、`raise_for_status()` 方法，兼容 httpx.Response 用法
+- 🏊 **AsyncBrowserPool**: 新增异步浏览器实例池，支持并发 UI 测试（Semaphore 控制并发，按最少 context 分配）
+- 🔙 **request_raw()**: `HttpClient` 新增 `request_raw()` 方法，供需要原始 `httpx.Response` 的场景使用
+- 🛠️ **fetch_swagger 增强**: 重构为 argparse，支持 `-H` 自定义请求头、`-d` 输出目录、中文文件名保留
+
+### 🔄 变更
+
+- ⚠️ **异常统一**: httpx 异常（`TimeoutException`/`ConnectError`/`HTTPError`）统一包装为框架 `HttpError`，原始异常通过 `__cause__` 保留
+- ⚠️ **BaseAPI 异常变更**: `_parse_response()` 中 HTTP 错误从 `httpx.HTTPStatusError` 改为 `HttpError`
+- 📏 **ResponseAssertions**: `assert_response_time` 兼容 `timedelta`（httpx）和 `float` 秒数（框架 Response）
+
+### 📚 文档
+
+- 📝 API 参考、认证指南、中间件指南中 `HTTPStatusError` 更新为 `HttpError`
+
+### ⚠️ 迁移指南
+
+用户项目中捕获 httpx 异常的代码需要更新：
+
+```python
+# 之前
+from httpx import HTTPStatusError
+with pytest.raises((BusinessError, HTTPStatusError)):
+    ...
+
+# 现在
+from df_test_framework.core.exceptions import HttpError
+with pytest.raises((BusinessError, HttpError)):
+    ...
+```
+
 ## [4.1.0] - 2026-03-03
 
 ### ✨ 新增功能

{df_test_framework-4.1.0 → df_test_framework-4.1.2}/CLAUDE.md

@@ -8,8 +8,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **DF Test Framework** - 现代化 Python 测试自动化框架
 
-- **版本**: v4.0.0
-- **更新时间**: 2026-01-16
+- **版本**: v4.1.2
+- **更新时间**: 2026-03-16
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）
@@ -50,16 +50,21 @@ uv run pytest --cov=src/df_test_framework --cov-report=term-missing
 ## 五层架构
 
 ```
-Layer 4 ─── bootstrap/          # 引导层：Bootstrap、Providers、Runtime
-Layer 3 ─── testing/ + cli/     # 门面层：Fixtures、CLI 工具、脚手架
-Layer 2 ─── capabilities/       # 能力层：HTTP/UI/DB/MQ/Storage
-Layer 1 ─── infrastructure/     # 基础设施：config/logging/events/plugins
-Layer 0 ─── core/               # 核心层：纯抽象（无依赖）
-横切 ───── plugins/             # 插件：MonitoringPlugin、AllurePlugin
+Layer 4 ─── bootstrap/                  # 引导层：Bootstrap、Providers、Runtime
+Layer 3 ─── testing/ + cli/             # 门面层：Fixtures、CLI
+Layer 2 ─── capabilities/               # 能力层：HTTP/UI/DB/MQ/Storage
+Layer 1 ─── infrastructure/             # 基础设施：config/logging/events/plugins
+Layer 0 ─── core/                       # 核心层：纯抽象（无依赖）
+横切 ───── plugins/                     # 插件：MonitoringPlugin、AllurePlugin
 ```
 
 **依赖规则**: 高层可依赖低层，反之不行。Layer 0 无任何依赖。
 
+**层级 ≠ 目录**: 层级是依赖规则，不是目录划分。同一层可以有多个顶级目录：
+- Layer 3 包含两个独立接口：`testing/`（pytest fixtures）、`cli/`（命令行）
+- 它们都是框架能力的"门面"，依赖 Layer 0-2，互相不依赖
+- 新增接口层时放在 `src/df_test_framework/` 下作为独立目录，不要嵌入 bootstrap/ 等其他层
+
 ---
 
 ## 核心模式

{df_test_framework-4.1.0 → df_test_framework-4.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.1.0
+Version: 4.1.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.1.0 → df_test_framework-4.1.2}/docs/api-reference/clients.md

@@ -73,15 +73,31 @@ print(f"用户名: {user['name']}")
 
 #### 请求方法
 - `get(url, params=None, **kwargs)` - GET请求
-- `post(url, json=None, data=None, **kwargs)` - POST请求
-- `put(url, json=None, **kwargs)` - PUT请求
-- `patch(url, json=None, **kwargs)` - PATCH请求
+- `post(url, json=None, data=None, files=None, content=None, **kwargs)` - POST请求
+- `put(url, json=None, data=None, files=None, content=None, **kwargs)` - PUT请求
+- `patch(url, json=None, data=None, files=None, content=None, **kwargs)` - PATCH请求
 - `delete(url, **kwargs)` - DELETE请求
+- `head(url, **kwargs)` - HEAD请求（v3.20.0+）
+- `options(url, **kwargs)` - OPTIONS请求（v3.20.0+）
 - `request(method, url, **kwargs)` - 通用请求方法
+- `request_raw(method, url, **kwargs)` - 通用请求，返回原始 httpx.Response（v3.20.0+）
+
+**通用 kwargs**（v4.1.2+）:
+- `timeout` - per-request 超时（秒），覆盖客户端默认值
+- `skip_auth` - 跳过认证中间件（v3.19.0+）
+- `token` - 使用自定义 Token（v3.19.0+）
 
 #### 认证方法
 - `set_auth_token(token, token_type="Bearer")` - 设置认证Token
 
+#### 认证状态管理（v3.19.0+）
+- `clear_auth_cache()` - 清除 BearerTokenMiddleware 的 Token 缓存
+- `clear_cookies()` - 清除所有 Cookies（v3.21.0+）
+- `clear_cookie(name)` - 清除指定 Cookie，返回 bool（v3.25.0+）
+- `get_cookies()` - 获取所有 Cookies 字典（v3.25.0+）
+- `reset_auth_state()` - 重置认证状态（清缓存+清Cookie）（v3.25.0+）
+- `get_auth_info()` - 获取认证信息（Token 预览、中间件数、Cookie 列表）（v3.25.0+）
+
 #### 管理方法
 - `close()` - 关闭客户端连接
 

{df_test_framework-4.1.0 → df_test_framework-4.1.2}/docs/api-reference/core.md

@@ -85,12 +85,10 @@ def request(
 - `url`: 请求路径（相对于base_url）
 - `**kwargs`: 其他请求参数（params, json, data, headers等）
 
-**返回**: `httpx.Response` 对象
+**返回**: `Response` 对象（框架统一响应）
 
 **异常**:
-- `httpx.TimeoutException`: 请求超时（重试max_retries次后仍失败）
-- `httpx.HTTPStatusError`: HTTP状态错误
-- `httpx.RequestError`: 请求错误
+- `HttpError`: HTTP 请求错误（超时、连接失败、状态码错误等）
 
 **重试策略**:
 - ✅ **自动重试**: 超时异常和5xx服务器错误

{df_test_framework-4.1.0 → df_test_framework-4.1.2}/docs/architecture/ARCHITECTURE_V4.0.md

@@ -23,12 +23,12 @@ DF Test Framework v4.0 采用**清晰分层、职责单一、依赖倒置**的
 ## 🏗️ 五层架构
 
 ```
-Layer 4 ─── bootstrap/          # 引导层：Bootstrap、Providers、Runtime
-Layer 3 ─── testing/ + cli/     # 门面层：Fixtures、CLI 工具、脚手架
-Layer 2 ─── capabilities/       # 能力层：HTTP/UI/DB/MQ/Storage
-Layer 1 ─── infrastructure/     # 基础设施：config/logging/events/plugins
-Layer 0 ─── core/               # 核心层：纯抽象（无依赖）
-横切 ───── plugins/             # 插件：MonitoringPlugin、AllurePlugin
+Layer 4 ─── bootstrap/                  # 引导层：Bootstrap、Providers、Runtime
+Layer 3 ─── testing/ + cli/             # 门面层：Fixtures、CLI
+Layer 2 ─── capabilities/               # 能力层：HTTP/UI/DB/MQ/Storage
+Layer 1 ─── infrastructure/             # 基础设施：config/logging/events/plugins
+Layer 0 ─── core/                       # 核心层：纯抽象（无依赖）
+横切 ───── plugins/                     # 插件：MonitoringPlugin、AllurePlugin
 ```
 
 ### 依赖规则
@@ -37,6 +37,19 @@ Layer 0 ─── core/               # 核心层：纯抽象（无依赖）
 - ❌ **禁止向上依赖**: Layer 0 不依赖任何层，Layer 1 只能依赖 Layer 0
 - ✅ **横切独立**: Plugins 可依赖所有层，提供跨层能力增强
 
+### 层级与目录的关系
+
+> **层级是依赖规则，不是目录映射。** 同一层可以有多个独立的顶级目录。
+
+Layer 3（门面层）包含两个并列的"接口"目录，它们是框架能力的不同访问方式：
+
+| 目录 | 访问者 | 访问方式 |
+|------|--------|---------|
+| `testing/` | pytest | Fixtures + 装饰器 |
+| `cli/` | 开发者 | 命令行（`df-test`） |
+
+这两个目录互相独立、互不依赖，都只依赖 Layer 0-2。新增接口层时应在 `src/df_test_framework/` 下创建独立目录，**不要嵌入** `bootstrap/`、`capabilities/` 等其他层目录中。
+
 ---
 
 ## 📦 各层职责
@@ -102,11 +115,11 @@ Layer 0 ─── core/               # 核心层：纯抽象（无依赖）
 
 ### Layer 3: Testing + CLI 门面层
 
-**职责**: 为测试开发提供便捷的工具和接口
+**职责**: 为不同访问者提供框架能力的便捷接口
 
 **包含**:
 
-**testing/** - 测试支持
+**testing/** - 测试支持（访问者：pytest）
 - `fixtures/` - Pytest Fixtures（async_http_client, async_database, etc.）
 - `decorators/` - 类和方法装饰器（@api_class, @actions_class）
 - `data/` - 测试数据管理
@@ -119,7 +132,7 @@ Layer 0 ─── core/               # 核心层：纯抽象（无依赖）
 - `debugging/` - 调试工具（ConsoleDebugObserver）
 - `reporting/` - Allure 报告集成
 
-**cli/** - 命令行工具
+**cli/** - 命令行工具（访问者：开发者）
 - `commands/` - df-test 命令集（init, gen, env）
 - `templates/` - 项目和代码模板
 

{df_test_framework-4.1.0 → df_test_framework-4.1.2}/docs/architecture/CODE_STRUCTURE.md

@@ -1,8 +1,8 @@
 # 代码结构导航
 
 > **目标读者**: 框架开发者、问题修复者、代码贡献者
-> **更新日期**: 2026-01-19
-> **框架版本**: v4.0.0
+> **更新日期**: 2026-03-16
+> **框架版本**: v4.1.2
 
 ---
 
@@ -13,6 +13,7 @@
 - [Layer 1: 基础设施层 (infrastructure/)](#layer-1-基础设施层-infrastructure)
 - [Layer 2: 能力层 (capabilities/)](#layer-2-能力层-capabilities)
 - [Layer 3: 门面层 (testing/ + cli/)](#layer-3-门面层-testing--cli)
+
 - [Layer 4: 引导层 (bootstrap/)](#layer-4-引导层-bootstrap)
 - [横切关注点 (plugins/)](#横切关注点-plugins)
 - [依赖关系图](#依赖关系图)
@@ -502,7 +503,7 @@ plugins/
 └────────────────────┬────────────────────────────────────┘
                      │ 依赖
 ┌────────────────────▼────────────────────────────────────┐
-│  Layer 3: testing/ + cli/                               │
+│  Layer 3: testing/ + cli/                                │
 │  (只依赖 Layer 0-2)                                     │
 └────────────────────┬────────────────────────────────────┘
                      │ 依赖
@@ -630,5 +631,5 @@ from df_test_framework.capabilities.clients.http import HttpClient  # 违反依
 
 ---
 
-**最后更新**: 2026-01-19
+**最后更新**: 2026-03-16
 

{df_test_framework-4.1.0 → df_test_framework-4.1.2}/docs/architecture//344/272/224/345/261/202/346/236/266/346/236/204/350/257/246/350/247/243.md

@@ -12,12 +12,12 @@
 
 **架构层级**:
 ```
-Layer 4 ─── bootstrap/          # 引导层
-Layer 3 ─── testing/ + cli/     # 门面层
-Layer 2 ─── capabilities/       # 能力层
-Layer 1 ─── infrastructure/     # 基础设施层
-Layer 0 ─── core/               # 核心层
-横切 ───── plugins/             # 插件层
+Layer 4 ─── bootstrap/                  # 引导层
+Layer 3 ─── testing/ + cli/             # 门面层（接口层）
+Layer 2 ─── capabilities/               # 能力层
+Layer 1 ─── infrastructure/             # 基础设施层
+Layer 0 ─── core/                       # 核心层
+横切 ───── plugins/                     # 插件层
 ```
 
 **依赖规则**:
@@ -25,6 +25,8 @@ Layer 0 ─── core/               # 核心层
 - ✅ Layer 0 无任何第三方依赖
 - ✅ Plugins 可依赖所有层
 
+> **层级 ≠ 目录**：层级定义的是依赖规则，而非目录映射。同一层可以有多个独立的顶级目录（如 Layer 3 的 testing/、cli/），它们互不依赖。新增接口层时应在 `src/df_test_framework/` 下创建独立目录，不要嵌入其他层的目录中。
+
 ---
 
 ## 🔷 Layer 0: Core 核心层
@@ -289,7 +291,14 @@ async def test_login(app_actions: AppActions):
 
 ### 职责
 
-为测试开发提供**便捷工具和最佳实践**。
+为**不同访问者**提供框架能力的便捷接口。Layer 3 是框架的"门面"，包含两个并列的接口目录：
+
+| 目录 | 访问者 | 访问方式 | 版本 |
+|------|--------|---------|------|
+| `testing/` | pytest 测试用例 | Fixtures + 装饰器 | v2.0+ |
+| `cli/` | 开发者 | 命令行 `df-test` | v3.0+ |
+
+这两个目录**互相独立、互不依赖**，都只依赖 Layer 0-2（通过 Layer 4 Bootstrap 引导框架）。
 
 ### 目录结构
 
@@ -478,8 +487,11 @@ plugins/
 | 添加配置项 | Layer 1 | 新增配置模型 |
 | 与外部系统交互 | Layer 2 | 新增 Elasticsearch 客户端 |
 | 测试辅助工具 | Layer 3 | 新增数据生成器 |
+| 新的框架访问接口 | Layer 3 | WebSocket 接口等 |
 | 跨层功能增强 | Plugins | 新增性能分析插件 |
 
+> **注意**：新增 Layer 3 接口时，在 `src/df_test_framework/` 下创建独立目录，不要放入 `bootstrap/`、`capabilities/` 或其他层的目录中。Layer 3 的每个目录是框架能力的一种访问方式，它们互不依赖。
+
 ### 2. 如何遵循依赖规则？
 
 ✅ **正确示例**:

{df_test_framework-4.1.0 → df_test_framework-4.1.2}/docs/guides/auth_session_guide.md

@@ -205,7 +205,7 @@ http_client.clear_cookies()
 def test_full_auth_flow(admin_auth_api, settings):
     """测试完整的登录-获取用户-登出流程"""
     from df_test_framework import BusinessError
-    from httpx import HTTPStatusError
+    from df_test_framework.core.exceptions import HttpError
 
     username = settings.business.admin_username
     password = settings.business.admin_password
@@ -222,7 +222,7 @@ def test_full_auth_flow(admin_auth_api, settings):
     admin_auth_api.logout(token=token)
 
     # 4. 验证 Token 已失效
-    with pytest.raises((BusinessError, HTTPStatusError)):
+    with pytest.raises((BusinessError, HttpError)):
         admin_auth_api.get_current_user(token=token)
 
     # 5. 清理（确保不影响其他测试）
@@ -236,10 +236,10 @@ def test_full_auth_flow(admin_auth_api, settings):
 def test_get_current_user_without_login(admin_auth_api):
     """测试未登录状态下获取当前用户"""
     from df_test_framework import BusinessError
-    from httpx import HTTPStatusError
+    from df_test_framework.core.exceptions import HttpError
 
     # 使用 skip_auth=True 跳过认证中间件
-    with pytest.raises((BusinessError, HTTPStatusError)):
+    with pytest.raises((BusinessError, HttpError)):
         admin_auth_api.get_current_user(skip_auth=True)
 ```
 
@@ -311,7 +311,7 @@ admin_auth_api.logout(token=token)
 
 ```python
 # ✅ 推荐：使用 skip_auth 测试未登录场景
-with pytest.raises((BusinessError, HTTPStatusError)):
+with pytest.raises((BusinessError, HttpError)):
     admin_auth_api.get_current_user(skip_auth=True)
 ```
 

{df_test_framework-4.1.0 → df_test_framework-4.1.2}/docs/guides/http_client_guide.md

@@ -213,7 +213,7 @@ async with AsyncHttpClient("https://api.example.com") as client:
     response = await client.get("/users")
     response = await client.get("/users", params={"page": 1, "size": 10})
 
-    # POST 请求
+    # POST 请求（v4.1.2: 显式签名 json/data/files/content）
     response = await client.post("/users", json={"name": "Alice", "age": 30})
 
     # PUT 请求
@@ -224,6 +224,12 @@ async with AsyncHttpClient("https://api.example.com") as client:
 
     # PATCH 请求
     response = await client.patch("/users/1", json={"age": 31})
+
+    # HEAD 请求（v4.1.2 异步版对齐）
+    response = await client.head("/files/123")
+
+    # OPTIONS 请求（v4.1.2 异步版对齐）
+    response = await client.options("/api/users")
 ```
 
 ### 并发请求（核心优势）
@@ -711,6 +717,70 @@ response = client.get("/users/profile", token="custom_token_here")
 client.clear_auth_cache()
 ```
 
+### 认证状态管理（v3.19.0+）
+
+```python
+# 清除所有认证状态（Token 缓存 + Cookies）
+client.reset_auth_state()
+
+# 或分别操作
+client.clear_auth_cache()   # 仅清除 BearerTokenMiddleware 缓存
+client.clear_cookies()      # 仅清除 httpx Cookies
+client.clear_cookie("sid")  # 清除指定 Cookie
+
+# 查看当前认证信息（调试用）
+info = client.get_auth_info()
+print(info)
+# {
+#   "has_token_cache": True,
+#   "token_preview": "eyJhbGciOiJIUzI1Ni...",
+#   "middleware_count": 1,
+#   "cookies_count": 2,
+#   "cookies": ["session_id", "csrf_token"]
+# }
+
+# 获取所有 Cookies
+cookies = client.get_cookies()  # {"session_id": "abc", "csrf_token": "xyz"}
+```
+
+> **注意**：以上认证状态管理方法在 HttpClient 和 AsyncHttpClient 上签名一致（同步方法，无需 await）。
+
+### Per-request 超时（v4.1.2+）
+
+单个请求可以覆盖客户端级别的默认超时：
+
+```python
+# 客户端默认 30 秒超时
+client = HttpClient("https://api.example.com", timeout=30)
+
+# 慢接口：单独设置 120 秒超时
+response = client.get("/reports/generate", timeout=120)
+
+# 快接口：使用客户端默认超时（30 秒）
+response = client.get("/health")
+```
+
+异步客户端同样支持：
+
+```python
+async with AsyncHttpClient("https://api.example.com", timeout=30) as client:
+    # per-request 超时覆盖客户端默认值
+    response = await client.post("/long-running-task", json=data, timeout=300)
+```
+
+### 获取原始 httpx.Response（v3.20.0+）
+
+当需要访问 httpx 原始 Response 对象时（如流式读取、底层 headers 操作）：
+
+```python
+# 同步
+raw_response = client.request_raw("GET", "/files/123")
+assert isinstance(raw_response, httpx.Response)
+
+# 异步（v4.1.2 对齐）
+raw_response = await async_client.request_raw("GET", "/files/123")
+```
+
 更多中间件使用细节请参考：[中间件使用指南](./middleware_guide.md)
 
 ---
@@ -1246,6 +1316,7 @@ async def test_concurrent():
 
 ## 版本历史
 
+- **v4.1.2**: AsyncHttpClient 与同步版对齐（head/options/request_raw/认证状态管理/per-request timeout）
 - **v4.0.0**: 异步性能优化（30倍提升）
 - **v3.36.0**: HTTPConfig 支持顶层配置和环境变量
 - **v3.22.0**: HttpEventPublisherMiddleware 发布事件

{df_test_framework-4.1.0 → df_test_framework-4.1.2}/docs/guides/middleware_guide.md

@@ -286,7 +286,7 @@ client.use(middleware)
 ```python
 # 测试未登录场景（接口需要验证"未登录时返回 401"）
 def test_get_current_user_without_login(api):
-    with pytest.raises((BusinessError, HTTPStatusError)):
+    with pytest.raises((BusinessError, HttpError)):
         api.get_current_user(skip_auth=True)  # 不添加 Token
 ```
 
@@ -307,7 +307,7 @@ def test_full_auth_flow(api):
     api.logout(token=token)
 
     # 4. 继续用同一个 Token，验证已失效
-    with pytest.raises((BusinessError, HTTPStatusError)):
+    with pytest.raises((BusinessError, HttpError)):
         api.get_current_user(token=token)
 ```
 

df_test_framework-4.1.2/docs/releases/v4.1.1.md

@@ -0,0 +1,143 @@
+# v4.1.1 发布说明
+
+**发布日期**: 2026-03-11
+
+统一 HTTP 响应层，所有请求方法返回框架 `Response` 对象，异常统一为 `HttpError`。新增 `AsyncBrowserPool` 和 `fetch_swagger` 增强。
+
+---
+
+## 新增功能
+
+### 统一 Response 层
+
+`HttpClient` / `AsyncHttpClient` 的所有方法（`get`/`post`/`put`/`patch`/`delete`/`head`/`options`）统一返回框架 `Response` 对象，不再返回 `httpx.Response`。
+
+```python
+from df_test_framework.capabilities.clients.http.core.response import Response
+
+# 之前：返回 httpx.Response
+# 现在：返回框架 Response（包含 status_code, headers, body, json_data, elapsed, context）
+response = client.get("/users")
+assert isinstance(response, Response)
+assert response.elapsed > 0  # 请求耗时（秒）
+```
+
+**新增 `request_raw()` 方法**：需要原始 `httpx.Response` 时使用：
+
+```python
+httpx_response = client.request_raw("GET", "/users")  # 返回 httpx.Response
+```
+
+### Response 增强
+
+```python
+response.text        # 响应文本（兼容 httpx.Response.text）
+response.json()      # 获取 JSON 数据（兼容 httpx.Response.json()）
+response.elapsed     # 请求耗时（float 秒数）
+response.raise_for_status()  # 非 2xx 时抛出 HttpError
+```
+
+### 异常统一
+
+httpx 底层异常统一包装为框架 `HttpError`，原始异常通过 `__cause__` 保留：
+
+| httpx 异常 | 框架异常 | 错误消息 |
+|------------|---------|---------|
+| `httpx.TimeoutException` | `HttpError` | `请求超时: GET /url` |
+| `httpx.ConnectError` | `HttpError` | `连接失败: GET /url` |
+| `httpx.HTTPError` | `HttpError` | `HTTP错误: GET /url` |
+
+```python
+from df_test_framework.core.exceptions import HttpError
+
+try:
+    client.get("/slow-endpoint")
+except HttpError as e:
+    print(e.message)           # "请求超时: GET /slow-endpoint"
+    print(e.__cause__)         # 原始 httpx.TimeoutException
+    print(e.details)           # {"original_error": "ReadTimeout", "url": "/slow-endpoint"}
+```
+
+### AsyncBrowserPool
+
+异步浏览器实例池，管理多个 `AsyncBrowserManager` 实例，支持并发 UI 测试：
+
+```python
+from df_test_framework import AsyncBrowserPool
+
+pool = AsyncBrowserPool(max_browsers=3, max_contexts_per_browser=10)
+await pool.start()
+
+async with pool.acquire() as manager:
+    ctx = await manager.new_context()
+    page = await ctx.new_page()
+    await page.goto("https://example.com")
+    await page.close()
+    await ctx.close()
+
+print(pool.stats)  # {"total": 3, "active": 1, "idle": 2, ...}
+await pool.shutdown()
+```
+
+特性：
+- `asyncio.Semaphore` 控制总并发数
+- 按最少 context 数分配浏览器实例
+- `_PooledManager` 代理防止单次 acquire 创建多个 context
+- `start()` 失败自动回滚已启动的实例
+
+### fetch_swagger 增强
+
+重构为 `argparse`，新增自定义请求头和输出目录支持：
+
+```bash
+# 带认证头
+python scripts/fetch_swagger.py -H 'Authorization: Bearer token' http://example.com
+
+# 指定输出目录
+python scripts/fetch_swagger.py -d output/ http://example.com
+
+# 组合使用
+python scripts/fetch_swagger.py -H 'Cookie: sid=abc' -d docs/ http://localhost:8089/doc.html
+```
+
+改进：
+- 中文文件名保留（`unicodedata.normalize` + 正则清理）
+- JSON 解析容错（不再依赖 content-type 判断）
+- 输出目录自动创建
+
+---
+
+## 迁移指南
+
+### 异常捕获更新
+
+```python
+# ❌ 之前
+from httpx import HTTPStatusError
+with pytest.raises((BusinessError, HTTPStatusError)):
+    api.get_current_user(skip_auth=True)
+
+# ✅ 现在
+from df_test_framework.core.exceptions import HttpError
+with pytest.raises((BusinessError, HttpError)):
+    api.get_current_user(skip_auth=True)
+```
+
+### BaseAPI 用户（无需改动）
+
+`BaseAPI` 的 `get`/`post` 等方法内部已自动使用框架 `Response`，返回 Pydantic 模型或 `dict` 的用法不变。
+
+### 直接使用 HttpClient 的用户
+
+```python
+# ❌ 之前：返回 httpx.Response
+response = client.request("GET", "/users")
+response.raise_for_status()  # httpx 方法
+
+# ✅ 现在：返回框架 Response
+response = client.request("GET", "/users")
+response.raise_for_status()  # 框架方法（行为一致）
+
+# 如需原始 httpx.Response
+response = client.request_raw("GET", "/users")
+```