df-test-framework 4.4.4__tar.gz → 4.7.0__tar.gz

{df_test_framework-4.4.4 → df_test_framework-4.7.0}/CHANGELOG.md

@@ -5,6 +5,60 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [4.7.0] - 2026-05-19
+
+### ✨ 新增
+
+- **`RuntimeContext.metadata` 字段**：`dict[str, Any]` 类型，默认空字典；用于携带跨进程/跨插件的平台业务上下文（`tenant_id`、`execution_id` 等），避免将业务键值编码到 scope 字符串中
+- **`RuntimeContext.with_metadata(**kwargs)`**：返回 metadata 已合并的新 RuntimeContext（不可变，新键覆盖同名旧键）；`with_scope()` / `with_overrides()` 自动传播 metadata
+- **`RuntimeContext.register_async_database(name, connection_string, **kwargs)`**：按名称注册多个 AsyncDatabase 连接池（`SingletonProvider` 延迟创建），支持多数据库场景（如 OMS DbStepExecutor 按 URL 缓存）；同名重复注册自动 shutdown 旧实例
+- **`RuntimeContext.get_async_database(name=None)`**：按名称获取已注册的 AsyncDatabase 实例；`name=None` 时返回由 `settings.db` 配置的默认实例
+- **`RuntimeBuilder.with_metadata(metadata)`**：构建时注入初始 metadata
+
+## [4.6.1] - 2026-05-18
+
+### ✨ 新增
+
+- **`CaseContext.skip` / `.xfail`**：YAML stage 元数据支持 `skip: "原因"` / `xfail: "原因"`（或 `true`），自动转换为对应 pytest mark，无需在 conftest 手写
+- **`CaseContext.seed`（YAML 级别）**：`tests.{stage}.seed: 42` 设置 case 级别随机种子；CLI `--seed` 全局覆盖优先级更高
+- **`--case-file` CLI 选项**：按数据文件路径过滤（部分匹配），多数据集项目可精准指定只跑某个文件的 case
+- **pytest 插件自动 Allure**：`pytest_runtest_setup` 钩子自动调用 `CaseReporter.attach_to_allure()`，写标题/标签/附件，测试函数无需手动调用
+- **pytest 插件自动 seed**：有 seed 的 case 自动 `random.seed()` + `Faker.seed()`（Faker 不可用时静默跳过）
+- **`pytest_collection_modifyitems`**：自动清除因空参数过滤产生的 `NotSetType` 占位用例，避免空壳测试出现在报告
+- **复现命令补充 `--seed`**：失败用例有 seed 时复现命令自动附带 `--seed=N`
+- **`DataAssetResolver` 路径安全**：`resolve()` / `resolve_file()` 禁止绝对路径和 `../` 路径逃逸，违规时 `raise ValueError`
+- **脚手架 `models/cases/`**：`df-test init` 自动创建 `src/{project}/models/cases/__init__.py`，作为场景领域模型的标准目录
+
+## [4.6.0] - 2026-05-18
+
+### ✨ 新增
+
+- **测试数据管线**：从 YAML/JSON 到 pytest 参数化的完整基础设施（`testing/data/pipeline/`）
+  - `case_dataset(path, model, root_key, id_field)` — 工厂函数，延迟加载 case 文件，支持 dict-of-dicts（key=case_id）和 list-of-dicts 两种 YAML 格式
+  - `CaseContext[T]` — 泛型 case 上下文冻结 dataclass，承载 domain data + stage/title/tags/marks/timeout/seed/source_path/raw
+  - `CaseDataset[T].parametrize(metafunc, fixture_name, stage)` — pytest_generate_tests 一行注入，读取 CLI 过滤选项
+  - `CaseDataset[T].all(stage)` — 不经参数化直接返回 CaseContext 列表，适合脚本/单元测试场景
+  - `DataAssetResolver` — 自动发现项目根（pyproject.toml + tests/），统一解析 `tests/data/fixtures/` 与 `tests/data/files/`
+  - `CaseReporter.attach_to_allure(ctx)` — 写 Allure 动态标题、case_id/stage 标签、tags，附 case 元信息 JSON 附件
+- **pytest 插件 `df_test_framework_data_pipeline`**：全局注册 `--case`、`--case-stage`、`--case-tag`、`--seed` CLI 过滤选项；测试失败时自动在报告 section 输出最小复现命令
+
+## [4.5.0] - 2026-05-12
+
+### ✨ 新增
+
+- **`ui_client()` — 命名多前端客户端系统**：通过 `ui_client(name, base_url_config=..., storage_state=..., default=True)` 声明独立 UI Client（B 端后台、H5、WebView 等），每套 Client 拥有独立 `base_url`、`storage_state`、`viewport` 和完整 `page/context/browser_manager` fixture 组。`load_ui_client_fixtures(globals())` 自动生成全套命名 fixture 及默认别名
+- **`service_client(default=True)` — 默认 HTTP Client 注册**：`@service_client` 新增 `default=True` 参数，注册的客户端自动提供 `http_client` alias fixture，`@api_class()` 可无感绑定默认客户端
+- **`@api_class(http_client=...)` — 显式绑定 HTTP Client**：多服务项目通过 `@api_class(http_client="payment_http_client")` 指定非默认客户端，彻底消除多后端并行测试的 fixture 混淆
+- **`@actions_class(ui_client=...)` — 显式绑定 UI Client**：多前端项目通过 `@actions_class(ui_client="h5_ui")` 将 Actions 绑定到具体前端，page/browser_manager 等依赖从绑定 Client 解析，不再静默回退全局 `page`
+
+### ♻️ 重构
+
+- **脚手架客户端目录统一**：`df-test init` 生成的默认 HTTP Client（`default_http_client.py`）和 UI Client（`ui_clients.py`）统一放入 `clients/` 目录；conftest 从 `{project}.clients` 加载服务客户端
+
+### 🐛 修复
+
+- **多 UI Client 同步混跑**：同步 `BrowserManager` 和 `AuthSetup` 共用进程内 Playwright 实例（引用计数管理），多 UI Client 场景下不再各自独立启动 Playwright，避免进程内多实例冲突
+
 ## [4.4.4] - 2026-04-23
 
 ### 🐛 修复

{df_test_framework-4.4.4 → df_test_framework-4.7.0}/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.2.2
-- **更新时间**: 2026-04-15
+- **版本**: v4.7.0
+- **更新时间**: 2026-05-19
 - **Python**: 3.12+
 - **核心技术栈**: pytest + httpx + Playwright + Pydantic v2 + SQLAlchemy 2.0 + Pluggy
 - **架构**: 五层架构 + 横切关注点（能力层驱动设计）

{df_test_framework-4.4.4 → df_test_framework-4.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.4.4
+Version: 4.7.0
 Summary: 基于交互模式的现代化测试自动化框架，支持多种测试场景
 Project-URL: Homepage, https://github.com/yourorg/df-test-framework
 Project-URL: Repository, https://github.com/yourorg/df-test-framework
@@ -22,7 +22,7 @@ Requires-Python: >=3.12
 Requires-Dist: allure-pytest>=2.13.0
 Requires-Dist: assertpy>=1.1
 Requires-Dist: faker>=38.2.0
-Requires-Dist: filelock>=3.20.1
+Requires-Dist: filelock>=3.29.0
 Requires-Dist: freezegun>=1.5.0
 Requires-Dist: h2>=4.3.0
 Requires-Dist: hpack>=4.1.0
@@ -40,15 +40,15 @@ Requires-Dist: pymysql>=1.1.0
 Requires-Dist: pypinyin>=0.53.0
 Requires-Dist: pytest-asyncio>=1.3.0
 Requires-Dist: pytest-timeout>=2.2.0
-Requires-Dist: pytest==9.0.3
+Requires-Dist: pytest>=9.0.3
 Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: questionary>=2.0.0
 Requires-Dist: redis>=5.0.0
-Requires-Dist: requests>=2.32.4
+Requires-Dist: requests>=2.34.2
 Requires-Dist: sqlalchemy>=2.0.0
 Requires-Dist: structlog>=25.4.0
-Requires-Dist: urllib3>=2.6.0
+Requires-Dist: urllib3>=2.7.0
 Provides-Extra: all
 Requires-Dist: aiomysql>=0.2.0; extra == 'all'
 Requires-Dist: aiosqlite>=0.20.0; extra == 'all'

{df_test_framework-4.4.4 → df_test_framework-4.7.0}/docs/api-reference/testing.md

@@ -26,9 +26,11 @@ from df_test_framework.testing.decorators import (
     api_class,
     actions_class,
     service_client,         # v4.2.0 新增
+    ui_client,              # UI Client 声明
     load_api_fixtures,
     load_actions_fixtures,
     load_service_fixtures,  # v4.2.0 新增
+    load_ui_client_fixtures,
     get_service_registry,   # v4.2.0 新增
 )
 
@@ -1144,6 +1146,7 @@ def test_create_card(
     name: str | None = None,           # fixture 名称（默认从类名生成）
     scope: str = "session",            # pytest fixture scope
     base_url_config: str | None = None, # settings 配置路径（dot notation）
+    default: bool = False,              # 是否额外注册默认 http_client
     **dependencies: Any,               # 额外依赖映射
 )
 ```

{df_test_framework-4.4.4 → df_test_framework-4.7.0}/docs/guides/decorators_guide.md

@@ -14,9 +14,11 @@ DF Test Framework 提供了两类装饰器，帮助简化测试代码和增强
 - **@api_class**: 自动将 BaseAPI 子类注册为 pytest fixture
 - **@actions_class**: 自动将 AppActions 子类注册为 pytest fixture
 - **@service_client**: 自动将独立服务客户端注册为 pytest fixture（v4.2.0）
+- **ui_client()**: 声明命名 UI Client，支持默认前端与多前端绑定
 - **load_api_fixtures()**: 自动加载所有 API fixtures
 - **load_actions_fixtures()**: 自动加载所有 Actions fixtures
 - **load_service_fixtures()**: 自动加载所有服务客户端 fixtures（v4.2.0）
+- **load_ui_client_fixtures()**: 自动加载所有 UI Client fixtures
 
 ### 通用装饰器（Core Decorators）
 
@@ -140,6 +142,15 @@ class CustomAPI(BaseAPI):
         self.settings = settings
 ```
 
+多服务项目可以直接绑定非默认 HTTP Client：
+
+```python
+@api_class("h5_order_api", http_client="h5_auth_client")
+class H5OrderAPI(BaseAPI):
+    def __init__(self, http_client):
+        super().__init__(http_client)
+```
+
 ### 自动加载 API Fixtures
 
 在 `conftest.py` 中使用 `load_api_fixtures()` 自动加载所有 API：
@@ -189,6 +200,8 @@ def test_multiple_apis(user_api, order_api):
 ### 基本用法
 
 `@actions_class` 装饰器自动将 AppActions 子类注册为 pytest fixture，用于 UI 测试。
+项目必须先通过 `ui_client(..., default=True)` 声明默认 UI Client；多前端 Actions
+通过 `@actions_class(ui_client="h5_ui")` 显式绑定。
 
 ```python
 from df_test_framework import AppActions
@@ -237,13 +250,16 @@ class SharedActions(AppActions):
 
 ### 自动加载 Actions Fixtures
 
-在 `conftest.py` 中使用 `load_actions_fixtures()` 自动加载所有 Actions：
+在 `conftest.py` 中先加载 UI Client，再使用 `load_actions_fixtures()` 自动加载所有 Actions：
 
 ```python
 # conftest.py
-from df_test_framework.testing.decorators import load_actions_fixtures
+from df_test_framework.testing.decorators import load_actions_fixtures, load_ui_client_fixtures
+
+import myproject.ui_clients  # noqa: F401 触发 UI Client 注册
 
 # 方式1: 自动发现模式（推荐）
+load_ui_client_fixtures(globals())
 load_actions_fixtures(globals(), actions_package="myproject.actions")
 
 # 方式2: 手动导入模式
@@ -279,8 +295,8 @@ def test_order_flow(login_actions, order_actions):
 | 基类 | `BaseAPI` | `AppActions` | 无要求 |
 | 默认 scope | `session` | `function` | `session` |
 | 配置字段 | `test.apis_package` | `test.actions_package` | `base_url_config` |
-| 目录约定 | `apis/` | `actions/` | `apis/` 或自定义 |
-| 自动依赖 | `http_client` | `page`, `browser_manager` | 按 `__init__` 签名推断 |
+| 目录约定 | `apis/` | `actions/` | `clients/` |
+| 自动依赖 | 默认 `http_client`，可用 `http_client=` 指定 | 默认 UI Client 的 `page`，可用 `ui_client=` 指定 | 按 `__init__` 签名推断 |
 
 ---
 
@@ -321,13 +337,22 @@ class MyClient:
         self.redis = redis_client  # 自动注入 redis_client fixture
 ```
 
+多服务项目推荐声明默认 HTTP Client，`@api_class()` 会继续依赖 `http_client` 这个默认别名：
+
+```python
+@service_client("admin_http_client", base_url_config="http.base_url", default=True, runtime="runtime")
+class AdminHttpClient(HttpClient):
+    def __init__(self, base_url: str, runtime=None) -> None:
+        super().__init__(base_url=base_url, runtime=runtime)
+```
+
 ### 自动加载
 
 ```python
 # conftest.py
 from df_test_framework.testing.decorators import load_service_fixtures
 
-load_service_fixtures(globals(), services_package="my_project.apis")
+load_service_fixtures(globals(), services_package="my_project.clients")
 ```
 
 ### 在测试中使用

{df_test_framework-4.4.4 → df_test_framework-4.7.0}/docs/guides/fixture_chain_pattern.md

@@ -6,6 +6,12 @@
 
 ---
 
+本文专注“运行期前置造数链”。如果要从数据文件、Case Model、pytest 参数化一路设计到
+前置准备、清理和报告，请先阅读
+[测试数据管线设计指南](test_data_pipeline_design.md)。
+
+---
+
 ## 目录
 
 - [问题：为什么需要这个范式](#问题为什么需要这个范式)

{df_test_framework-4.4.4 → df_test_framework-4.7.0}/docs/guides/service_client_guide.md

@@ -22,6 +22,7 @@
 - 调用的服务有独立的 base_url（不同于主测试目标）
 - 使用不同的认证方式（如独立的 API Key）
 - 不需要继承 BaseAPI 的轻量客户端
+- 多服务项目需要显式声明默认 `http_client`
 
 ---
 
@@ -33,7 +34,7 @@
 携带 EventBus，是失败 section、console_debugger、Allure HTTP attachment 的工作前提。
 
 ```python
-# apis/payment_client.py
+# clients/payment_client.py
 from df_test_framework import HttpClient
 from df_test_framework.testing.decorators import service_client
 
@@ -55,6 +56,40 @@ class PaymentClient(HttpClient):
         return resp.json()
 ```
 
+### 默认 HTTP Client
+
+多服务项目应显式声明默认 HTTP Client。被标记为 `default=True` 的服务客户端会额外注册
+`http_client` fixture，`@api_class()` 默认继续依赖这个显式默认客户端。
+
+```python
+from df_test_framework import HttpClient
+from df_test_framework.testing.decorators import service_client
+
+
+@service_client(
+    "admin_http_client",
+    base_url_config="http.base_url",
+    default=True,
+    runtime="runtime",
+)
+class AdminHttpClient(HttpClient):
+    def __init__(self, base_url: str, runtime=None) -> None:
+        super().__init__(
+            base_url=base_url,
+            config=runtime.settings.http if runtime else None,
+            runtime=runtime,
+        )
+```
+
+其他系统继续声明为独立客户端：
+
+```python
+@service_client("h5_http_client", base_url_config="business.h5_base_url")
+class H5HttpClient(HttpClient):
+    def __init__(self, base_url: str, runtime=None) -> None:
+        super().__init__(base_url=base_url, runtime=runtime)
+```
+
 > **v4.4.1 强制要求**：`HttpClient`/`AsyncHttpClient` 子类必须在 `__init__` 接受
 > `runtime` 并透传给 `super().__init__`。否则 `load_service_fixtures()` 会触发
 > `ServiceClientObservabilityWarning`，且该客户端的所有 HTTP 请求 **不会** 出现在
@@ -75,7 +110,7 @@ business:
 # conftest.py
 from df_test_framework.testing.decorators import load_service_fixtures
 
-load_service_fixtures(globals(), services_package="my_project.apis")
+load_service_fixtures(globals(), services_package="my_project.clients")
 ```
 
 ### 4. 在测试中使用
@@ -330,17 +365,17 @@ class UserCenterClient: ...
 # conftest.py
 from df_test_framework.testing.decorators import load_service_fixtures
 
-load_service_fixtures(globals(), services_package="my_project.apis")
+load_service_fixtures(globals(), services_package="my_project.clients")
 ```
 
-自动导入 `my_project.apis` 包下所有模块，触发 `@service_client` 装饰器注册。
+自动导入 `my_project.clients` 包下所有模块，触发 `@service_client` 装饰器注册。
 
 ### 方式2：手动导入
 
 ```python
 # conftest.py
-from my_project.apis.payment_client import PaymentClient  # noqa: F401
-from my_project.apis.sms_client import SmsClient  # noqa: F401
+from my_project.clients.payment_client import PaymentClient  # noqa: F401
+from my_project.clients.sms_client import SmsClient  # noqa: F401
 from df_test_framework.testing.decorators import load_service_fixtures
 
 load_service_fixtures(globals())
@@ -348,7 +383,9 @@ load_service_fixtures(globals())
 
 ### 与 load_api_fixtures 共存
 
-可以同时使用 `load_api_fixtures` 和 `load_service_fixtures`：
+可以同时使用 `load_api_fixtures` 和 `load_service_fixtures`。如果项目声明了
+`@service_client(default=True)`，必须先加载服务客户端，再加载 API 类，确保
+`@api_class()` 默认依赖的 `http_client` 指向项目显式默认客户端：
 
 ```python
 # conftest.py
@@ -357,11 +394,11 @@ from df_test_framework.testing.decorators import (
     load_service_fixtures,
 )
 
-# BaseAPI 子类（共享 http_client）
-load_api_fixtures(globals(), apis_package="my_project.apis")
+# 独立服务客户端；default=True 会额外注册 http_client
+load_service_fixtures(globals(), services_package="my_project.clients")
 
-# 独立服务客户端（各自管理连接）
-load_service_fixtures(globals(), services_package="my_project.apis")
+# BaseAPI 子类（共享显式默认 http_client）
+load_api_fixtures(globals(), apis_package="my_project.apis")
 ```
 
 ---
@@ -372,7 +409,7 @@ load_service_fixtures(globals(), services_package="my_project.apis")
 from df_test_framework import get_service_registry
 
 registry = get_service_registry()
-for name, (cls, scope, config, deps) in registry.items():
+for name, (cls, scope, config, deps, is_default) in registry.items():
     print(f"{name}: {cls.__name__} (scope={scope}, config={config})")
 ```
 
@@ -383,9 +420,9 @@ for name, (cls, scope, config, deps) in registry.items():
 ### 1. 按服务拆分文件
 
 ```
-apis/
+clients/
 ├── __init__.py
-├── admin_api.py          # @api_class — 后台 API（继承 BaseAPI）
+├── admin_http_client.py  # @service_client(default=True) — 默认 HTTP Client
 ├── payment_client.py     # @service_client — 支付服务
 ├── sms_client.py         # @service_client — 短信服务
 └── user_center_client.py # @service_client — 用户中心

{df_test_framework-4.4.4 → df_test_framework-4.7.0}/docs/guides/test_data.md

@@ -6,6 +6,16 @@
 
 ---
 
+## 阅读路径
+
+如果只需要加载 JSON / CSV / YAML 或生成假数据，阅读本文即可。
+
+如果要设计完整的数据驱动测试链路，包括 case 元信息、pytest 参数化、前置造数、
+cleanup、文件资产和报告，请阅读
+[测试数据管线设计指南](test_data_pipeline_design.md)。
+
+---
+
 ## 概述
 
 测试数据工具包含三大模块：