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

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

@@ -5,6 +5,28 @@
 格式基于 [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
 
 ### ✨ 新增功能

{df_test_framework-4.1.1 → 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.1 → df_test_framework-4.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.1.1
+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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.2/docs/releases/v4.1.2.md

@@ -0,0 +1,120 @@
+# v4.1.2 发布说明
+
+**发布日期**: 2026-03-16
+
+AsyncHttpClient 与同步版完全对齐，支持 per-request timeout。移除 Worker 独立服务模块，框架回归"库 + CLI"定位。
+
+---
+
+## 新增功能
+
+### AsyncHttpClient 同步版对齐
+
+AsyncHttpClient 补齐以下同步版 HttpClient 已有的方法：
+
+| 方法 | 说明 |
+|------|------|
+| `head(url, **kwargs)` | HEAD 请求 |
+| `options(url, **kwargs)` | OPTIONS 请求 |
+| `request_raw(method, url, **kwargs)` | 返回原始 httpx.Response |
+| `clear_auth_cache()` | 清除 BearerTokenMiddleware 缓存 |
+| `clear_cookies()` | 清除所有 Cookies |
+| `clear_cookie(name)` | 清除指定 Cookie |
+| `get_cookies()` | 获取所有 Cookies |
+| `reset_auth_state()` | 重置认证状态（缓存+Cookies） |
+| `get_auth_info()` | 获取认证信息（调试用） |
+
+**post/put/patch 签名对齐**:
+
+```python
+# v4.1.2 之前：仅 **kwargs
+await client.post("/upload", files=files)  # 通过 kwargs 传递
+
+# v4.1.2：显式参数，IDE 提示更友好
+await client.post("/upload", json=None, data=None, files=files, content=None)
+```
+
+---
+
+### Per-request timeout
+
+单个请求可覆盖客户端级别的默认超时：
+
+```python
+# 客户端默认 30 秒
+client = HttpClient("https://api.example.com", timeout=30)
+
+# 慢接口单独设置 120 秒
+response = client.get("/reports/generate", timeout=120)
+
+# 异步客户端同样支持
+response = await async_client.post("/long-task", json=data, timeout=300)
+```
+
+实现方式：`timeout` 通过 `Request.metadata` 传递，在 `_send_request_async()` 中覆盖 httpx 参数。
+
+---
+
+## 修复
+
+### 绝对 URL 修复
+
+`_convert_to_httpx_response()` 对绝对 URL（`http://` / `https://` 开头）不再错误拼接 `base_url`：
+
+```python
+# v4.1.2 之前（错误）
+# request.url = "https://other.api.com/data"
+# 结果: "https://api.example.comhttps://other.api.com/data"
+
+# v4.1.2（正确）
+# 结果: "https://other.api.com/data"
+```
+
+---
+
+## 移除
+
+### Worker 模块
+
+移除 `worker/` 模块及相关依赖，框架回归纯粹的"库 + CLI 工具"定位。
+
+**原因**：经调研业界主流测试平台（MeterSphere、HttpRunnerManager、testhub_platform），没有测试平台使用"启动独立 HTTP 服务再转发"的方式执行测试。所有平台均采用库直接导入或 CLI subprocess 调用。
+
+**移除内容**：
+- `src/df_test_framework/worker/`（app.py, schemas.py, __init__.py）
+- `pyproject.toml` 中 `[worker]` optional dependency group（fastapi + uvicorn）
+- `pyproject.toml` 中 `df-test-worker` 入口点
+- `tests/worker/` 测试目录
+
+**推荐集成方式**：
+```python
+# OMS 测试平台直接导入框架能力
+from df_test_framework.capabilities.clients.http.rest.httpx import AsyncHttpClient
+
+client = AsyncHttpClient(base_url="", timeout=30, max_retries=0)
+response = await client.request("GET", "https://api.example.com/users")
+```
+
+---
+
+## 影响的文件
+
+### 源码
+- `src/df_test_framework/__init__.py` - 版本号
+- `src/df_test_framework/capabilities/clients/http/rest/httpx/async_client.py` - 主要变更
+- `src/df_test_framework/capabilities/clients/http/rest/httpx/client.py` - per-request timeout + 绝对 URL 修复
+- `pyproject.toml` - 版本号，移除 worker 依赖组和入口点
+
+### 移除
+- `src/df_test_framework/worker/` - 整个模块移除
+- `tests/worker/` - 相关测试移除
+
+### 测试
+- `tests/capabilities/clients/http/rest/test_async_client.py` - 新增 6 个测试类 30 个用例
+- `tests/capabilities/clients/http/rest/test_http_client.py` - 新增 2 个测试类 5 个用例
+
+### 文档
+- `CLAUDE.md`
+- `CHANGELOG.md`
+- `docs/architecture/CODE_STRUCTURE.md`
+- `docs/guides/http_client_guide.md`

{df_test_framework-4.1.1 → df_test_framework-4.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "df-test-framework"
-version = "4.1.1"
+version = "4.1.2"
 description = "基于交互模式的现代化测试自动化框架，支持多种测试场景"
 authors = [{name = "DF QA Team", email = "qa@example.com"}]
 readme = "README_PYPI.md"

{df_test_framework-4.1.1 → df_test_framework-4.1.2}/src/df_test_framework/__init__.py

@@ -144,7 +144,7 @@ v3.18.1 特性:
 - 🔄 Unit of Work 模式支持（v3.7）
 """
 
-__version__ = "4.1.1"
+__version__ = "4.1.2"
 __author__ = "DF QA Team"
 
 # ==============================================================================