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

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

@@ -5,6 +5,16 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [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.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.4.3
+Version: 4.4.4
 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.4.4}/docs/guides/web-ui-testing.md

@@ -1068,6 +1068,10 @@ start reports/videos
 open reports/videos
 ```
 
+#### 多 tab / popup 场景
+
+测试中打开了多个标签页或弹窗时，失败视频取自**最后打开的页面**（`context.pages[-1]`），通常是实际发生错误的页面。
+
 ### 10.3 截图
 
 #### 自动截图配置
@@ -1079,6 +1083,12 @@ web:
   screenshot_dir: reports/screenshots
 ```
 
+#### 多 tab / popup 场景与文件名安全
+
+失败截图默认取自**最后打开的页面**（`context.pages[-1]`），覆盖 popup 和新标签页场景。
+
+参数化测试的 `item.name` 含 `[`、`/`、`:` 等特殊字符时，框架自动将其替换为 `_`，截图文件名在 Windows/Linux 下均合法，无需手动处理。
+
 #### 手动截图
 
 在测试代码中手动截图：

df_test_framework-4.4.4/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 之前的遗留写法），建议移除，框架已完整覆盖。

{df_test_framework-4.4.3 → df_test_framework-4.4.4}/pyproject.toml

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

{df_test_framework-4.4.3 → df_test_framework-4.4.4}/src/df_test_framework/__init__.py

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

{df_test_framework-4.4.3 → df_test_framework-4.4.4}/src/df_test_framework/cli/templates/project/ui_conftest.py

@@ -6,7 +6,7 @@ v3.45.0: 支持 @actions_class 装饰器 + load_actions_fixtures 自动发现
 v3.37.0: 更新为 pytest11 Entry Points 自动加载
 """
 
-UI_CONFTEST_TEMPLATE = '''"""Pytest全局配置 - UI测试 (v4.0.4)
+UI_CONFTEST_TEMPLATE = '''"""Pytest全局配置 - UI测试 (v4.4.4)
 
 UI测试专用的pytest配置和fixtures。