df-test-framework 4.4.3__tar.gz → 4.5.0__tar.gz

{df_test_framework-4.4.3 → df_test_framework-4.5.0}/CHANGELOG.md

@@ -5,6 +5,33 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [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
+
+### 🐛 修复
+
+- **(P1) `async_context` / `async_page` decorator 错误**：这两个 fixture 原先标注的是 `@pytest.fixture`，在 pytest-asyncio >= 0.21 下异步生成器必须使用 `@pytest_asyncio.fixture`，导致运行时报错。同步修复 `async_goto`、`async_screenshot`、`async_app_actions` 的装饰器一致性问题
+- **(P2) 异步截图 fire-and-forget 不可靠**：`pytest_runtest_makereport` hook 里用 `asyncio.create_task` 发起截图任务未 await，截图未完成就执行了 `page.close()`，导致异步测试失败时截图为空。截图逻辑已迁移至 `page`/`async_page` fixture teardown，在 `p.close()` 前同步/await 执行
+- **(P2) 视频路径对异步 Page 调用同步 `video.path()`**：异步 Playwright Page 的 `video.path()` 返回 coroutine，直接调用会得到 coroutine 对象而不是路径字符串。修复方案：视频路径在 `page`/`async_page` teardown 里通过 `_UI_VIDEO_PATH_KEY` stash 传递给 `context` teardown，异步路径用 `await` 调用
+- **(P3) 多 tab 截图/视频目标取 `pages[0]` 不准确**：多 tab 场景下失败通常发生在最后打开的页面（popup/新 tab），截图和视频目标统一改为 `context.pages[-1]`
+- **(P3) 截图文件名含非法字符导致 Windows 路径错误**：pytest 参数化测试的 `item.name` 含 `[`、`/`、`:`、`*` 等字符，Windows 下产生非法路径。新增 `_sanitize_filename()` 对文件名做 sanitize，将非法字符替换为 `_`
+
 ## [4.4.3] - 2026-04-23
 
 ### ♻️ 重构

{df_test_framework-4.4.3 → df_test_framework-4.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.4.3
+Version: 4.5.0
 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.4.3 → df_test_framework-4.5.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.3 → df_test_framework-4.5.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.3 → df_test_framework-4.5.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.3 → df_test_framework-4.5.0}/docs/guides/web-ui-testing.md

@@ -5,7 +5,7 @@
 
 ## 概述
 
-本指南介绍如何使用 DF Test Framework 进行 Web UI 测试，基于 Playwright 实现，采用配置驱动 + @actions_class 装饰器 + 事件驱动架构。
+本指南介绍如何使用 DF Test Framework 进行 Web UI 测试，基于 Playwright 实现，采用配置驱动 + UI Client + @actions_class 装饰器 + 事件驱动架构。
 
 **框架提供两种模式**：
 - **AppActions + BasePage**：同步模式（v3.0.0+），简单易用
@@ -22,6 +22,11 @@
 > - ✅ 对齐 Playwright 官方最佳实践（pytest-playwright 插件模式）
 > - ✅ storageState 下沉到 context 级别注入，更符合 Playwright 设计
 >
+> **vNext 多前端模型**:
+> - ✅ `ui_client()` 将 B 端后台、H5、WebView 等前端声明为独立 UI Client
+> - ✅ 每个 UI Client 拥有自己的 `base_url`、`storage_state`、`viewport`、`context/page`
+> - ✅ `@actions_class(ui_client="h5_ui")` 显式绑定业务 Actions 到指定前端
+>
 > 本指南主要介绍**同步版本**（向后兼容）。异步版本使用方法请参考：
 > - [v4.0.0 发布说明](../releases/v4.0.0.md) - 异步 UI 测试概述
 > - [五层架构详解](../architecture/五层架构详解.md#layer-2-capabilities) - AsyncAppActions 详细说明
@@ -32,7 +37,7 @@
 
 1. [快速开始](#1-快速开始)
 2. [配置驱动模式](#2-配置驱动模式)
-3. [认证状态管理（storageState）](#3-认证状态管理storagstate)
+3. [UI Client 与认证状态](#3-ui-client-与认证状态)
 4. [核心组件](#4-核心组件)
 5. [@actions_class 装饰器](#5-actions_class-装饰器)
 6. [三层架构模式](#6-三层架构模式)
@@ -139,12 +144,56 @@ WEB__BASE_URL=https://web.example.com       # Web 地址
 
 ---
 
-## 3. 认证状态管理（storageState）
+## 3. UI Client 与认证状态
 
 > **版本**: v4.0.3+（基础功能），v4.0.4+（pytest_config CLI 参数一致性）
 
 绝大多数 UI 测试的前提是「用户已登录」。v4.0.3 原生支持 Playwright storageState，`page` 自动携带认证状态，测试零感知。
 
+多前端项目应先声明 UI Client：
+
+```python
+# src/my_project/clients/ui_clients.py
+from df_test_framework import ui_client
+
+ui_client(
+    "admin_ui",
+    base_url_config="web.base_url",
+    storage_state="admin_storage_state",
+    default=True,
+)
+
+ui_client(
+    "h5_ui",
+    base_url_config="business.h5_web_base_url",
+    storage_state="h5_storage_state",
+    viewport={"width": 375, "height": 812},
+)
+```
+
+在 `conftest.py` 中加载：
+
+```python
+import my_project.clients.ui_clients  # noqa: F401
+from df_test_framework.testing.decorators import load_ui_client_fixtures
+
+load_ui_client_fixtures(globals())
+```
+
+框架会生成：
+
+```text
+admin_ui_page / admin_ui_context / admin_ui_browser_manager
+h5_ui_page / h5_ui_context / h5_ui_browser_manager
+admin_ui_async_page / h5_ui_async_page
+```
+
+`default=True` 的客户端还会注册默认别名：`page`、`context`、`browser_manager`、`app_actions`
+以及异步别名 `async_page`、`async_context`、`async_browser_manager`、`async_app_actions`。
+
+> 标准约束：使用 `@actions_class()` 时，项目必须声明一个 `default=True` 的 UI Client；
+> 多前端 Actions 使用 `@actions_class(ui_client="h5_ui")` 显式绑定。
+
 ### 3.1 设计思路
 
 与 HTTP bearer_token 中间件类比：
@@ -158,7 +207,7 @@ WEB__BASE_URL=https://web.example.com       # Web 地址
 
 ### 3.2 使用方式
 
-在项目 `conftest.py` 中覆盖框架的 `storage_state` fixture：
+在项目 `conftest.py` 中提供对应的 storage state fixture：
 
 ```python
 # conftest.py
@@ -166,7 +215,7 @@ import pytest
 from df_test_framework.testing import AuthSetup
 
 @pytest.fixture(scope="session")
-def storage_state(tmp_path_factory, settings, request):
+def admin_storage_state(tmp_path_factory, settings, request):
     """Session 级别认证状态 — 整个测试 session 只登录一次"""
     with AuthSetup(settings, tmp_path_factory.mktemp("auth"), pytest_config=request.config) as auth:
         auth.page.goto(f"{auth.base_url}/login")
@@ -188,6 +237,14 @@ def test_dashboard(page):
     assert page.get_by_text("监控管理").is_visible()
 ```
 
+Actions 可以显式绑定到非默认 UI Client：
+
+```python
+@actions_class(ui_client="h5_ui")
+class H5HomeActions(AppActions):
+    ...
+```
+
 ### 3.3 AuthSetup API
 
 `AuthSetup` 是一个 context manager，管理临时浏览器的完整生命周期：
@@ -387,7 +444,9 @@ class LoginActions(AppActions):
 
 ```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 my_project.clients.ui_clients  # noqa: F401 触发 UI Client 注册
 
 def _get_actions_package() -> str:
     """获取 Actions 包路径（优先配置，否则默认值）"""
@@ -399,7 +458,8 @@ def _get_actions_package() -> str:
     except Exception:
         return default_package
 
-# 自动加载所有 @actions_class 装饰的类
+# 先加载 UI Client，再加载所有 @actions_class 装饰的类
+load_ui_client_fixtures(globals())
 load_actions_fixtures(globals(), actions_package=_get_actions_package())
 ```
 
@@ -1068,6 +1128,10 @@ start reports/videos
 open reports/videos
 ```
 
+#### 多 tab / popup 场景
+
+测试中打开了多个标签页或弹窗时，失败视频取自**最后打开的页面**（`context.pages[-1]`），通常是实际发生错误的页面。
+
 ### 10.3 截图
 
 #### 自动截图配置
@@ -1079,6 +1143,12 @@ web:
   screenshot_dir: reports/screenshots
 ```
 
+#### 多 tab / popup 场景与文件名安全
+
+失败截图默认取自**最后打开的页面**（`context.pages[-1]`），覆盖 popup 和新标签页场景。
+
+参数化测试的 `item.name` 含 `[`、`/`、`:` 等特殊字符时，框架自动将其替换为 `_`，截图文件名在 Windows/Linux 下均合法，无需手动处理。
+
 #### 手动截图
 
 在测试代码中手动截图：

df_test_framework-4.5.0/docs/releases/v4.4.4.md

@@ -0,0 +1,82 @@
+# v4.4.4 发布说明
+
+**发布日期**: 2026-04-23
+**版本类型**: PATCH（UI 失败诊断 bug 修复，无 API 增减）
+
+---
+
+## 概述
+
+本版本修复了 `testing/fixtures/ui.py` 中 UI 失败诊断子系统（截图 + 视频）的五个问题，涵盖异步可靠性、decorator 正确性、多 tab 目标选取、Windows 路径兼容性。**用户配置和调用方式完全不变**，升级后行为更可靠。
+
+---
+
+## 变更详情
+
+### P1 — `async_context` / `async_page` decorator 错误
+
+pytest-asyncio >= 0.21 要求异步 fixture 生成器必须使用 `@pytest_asyncio.fixture`，而非 `@pytest.fixture`。
+
+受影响 fixture（已全部修复）：
+
+| Fixture | 修复前 | 修复后 |
+|---------|--------|--------|
+| `async_context` | `@pytest.fixture` | `@pytest_asyncio.fixture` |
+| `async_page` | `@pytest.fixture` | `@pytest_asyncio.fixture` |
+| `async_goto` | `@pytest.fixture` | `@pytest_asyncio.fixture` |
+| `async_screenshot` | `@pytest.fixture` | `@pytest_asyncio.fixture` |
+| `async_app_actions` | `@pytest.fixture` | `@pytest_asyncio.fixture` |
+
+### P2 — 异步截图 fire-and-forget 不可靠
+
+**修复前**：`pytest_runtest_makereport` hook 里通过 `asyncio.create_task()` 发起截图，task 未被 await，`page.close()` 可能在截图完成前执行，导致异步测试失败时截图为空或 IO 错误。
+
+**修复后**：`pytest_runtest_makereport` hook 职责缩减为只写 `item.stash[_UI_FAILED_KEY] = True`；截图逻辑迁移至 `page`/`async_page` fixture teardown，在 `p.close()` 之前执行（同步调用 / `await` 调用）。
+
+### P2 — 异步 `video.path()` 返回 coroutine
+
+**修复前**：`_get_video_path()` 对 async Page 直接调用同步 `page.video.path()`，得到 coroutine 对象而非路径字符串，视频处理逻辑静默失效。
+
+**修复后**：视频路径在 `page`/`async_page` teardown（`p.close()` 前）通过 `await target.video.path()` 获取，写入 `item.stash[_UI_VIDEO_PATH_KEY]`；`context`/`async_context` teardown 在 `ctx.close()` 后读取 stash 完成视频文件处理。
+
+### P3 — 多 tab 截图/视频目标使用 `pages[0]`
+
+**修复前**：失败截图和视频路径从 `context.pages[0]` 取，多 tab 场景（popup、`page.open_new_tab()` 等）失败通常发生在最后打开的页面，取第一个页面会得到错误截图。
+
+**修复后**：截图和视频路径目标统一使用 `context.pages[-1]`（最后打开的页面），回退为当前 `page`（如果 `context.pages` 为空）。
+
+### P3 — 截图文件名含非法字符
+
+**修复前**：pytest 参数化测试 `item.name` 形如 `test_login[admin-case1]`，含 `[`、`]`、`/`、`:` 等字符，Windows 文件系统不允许，导致截图保存失败并抛出 `OSError`。
+
+**修复后**：新增内部函数 `_sanitize_filename(name)`，将 `/ \ : * ? " < > | [ ]` 替换为 `_`，截图文件名在所有平台均合法。
+
+---
+
+## 架构说明
+
+本次修复引入了两个模块级 stash key，作为 hook 和 fixture teardown 之间的通信通道：
+
+```python
+_UI_FAILED_KEY = pytest.StashKey[bool]()    # hook → page/async_page teardown
+_UI_VIDEO_PATH_KEY = pytest.StashKey[str]() # page/async_page teardown → context/async_context teardown
+```
+
+teardown 执行顺序（pytest 反向拆解）：
+
+```
+page teardown      → 截图 + 写 _UI_VIDEO_PATH_KEY → p.close()
+context teardown   → ctx.close() → 读 _UI_VIDEO_PATH_KEY → 处理视频文件
+```
+
+---
+
+## 升级指南
+
+无需任何改动，直接升级：
+
+```bash
+pip install df-test-framework==4.4.4
+```
+
+如果你的项目 conftest.py 里有手动实现截图或视频处理逻辑（v3.46.3 之前的遗留写法），建议移除，框架已完整覆盖。