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

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

@@ -5,6 +5,66 @@
 格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/),
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [4.1.0] - 2026-03-03
+
+### ✨ 新增功能
+
+- 🚀 **Browser Session 复用**: `browser_manager`/`browser` 提升为 session scope，整个测试会话只启动一次浏览器，启动时间减少 90%+
+- 🔒 **Context/Page 每测试隔离**: `context`/`page` 保持 function scope，每个测试独立的 BrowserContext，对齐 Playwright 官方最佳实践
+- 🆕 **BrowserManager.new_context()**: 新增方法，创建带配置的隔离 BrowserContext（viewport、storageState、video 等）
+- ⚡ **per-fixture loop_scope**: 异步 session fixtures 使用 `@pytest_asyncio.fixture(loop_scope="session")` 精确控制事件循环
+
+### 🔄 架构变更
+
+- 📦 **BrowserManager 精简**: `start()` 只创建 playwright + browser，不再创建 context/page；移除 `_context`、`_page` 属性
+- 📦 **storageState 下沉**: 认证状态注入从 BrowserManager 移至 context fixture，更符合 Playwright 设计（auth 是 context 级别关注点）
+- 📦 **actions_class test_runtime**: `@actions_class()` 生成的 fixture 新增 `test_runtime` 参数，实现事件隔离
+- 🗑️ **移除 ui_manager**: `ui_manager`/`async_ui_manager` fixture alias 已移除（browser_manager 不再持有 context/page）
+
+### 📚 文档
+
+- 📝 **Web UI 测试手册**: 更新 fixture scope 表、storageState 注入流程
+- 📝 **Fixtures 使用指南**: 更新 browser/browser_manager scope 说明和速查表
+- 📝 **Drivers API 参考**: 更新 BrowserManager API（new_context、start/stop）
+- 📝 **认证指南**: 更新 storageState 注入描述
+
+**详细内容**: 查看完整发布说明 [v4.1.0.md](docs/releases/v4.1.0.md)
+
+---
+
+## [4.0.4] - 2026-03-02
+
+### ✨ 新增功能
+
+- 🔧 **AuthSetup pytest_config 支持**: `AuthSetup` / `AsyncAuthSetup` 新增 `pytest_config` 参数，自动读取 `--headed`/`--browser`/`--slowmo` CLI 参数
+- 🔒 **User-Agent 一致性**: 确保 auth 浏览器与测试浏览器模式一致，避免认证状态因 User-Agent 不匹配而失效
+
+### 📚 文档
+
+- 📝 **Web UI 测试手册**: 更新认证状态管理章节，新增 `pytest_config` 说明和配置优先级
+- 📝 **脚手架模板**: 更新 ui/full 项目模板的 storage_state 示例
+
+**详细内容**: 查看完整发布说明 [v4.0.4.md](docs/releases/v4.0.4.md)
+
+---
+
+## [4.0.3] - 2026-03-01
+
+### ✨ 新增功能
+
+- 🔐 **UI 认证状态管理**: 新增 `AuthSetup` / `AsyncAuthSetup`，原生支持 Playwright storageState
+- 🔑 **storage_state Fixture**: 项目覆盖即启用，`page` 自动携带登录状态
+- ⚙️ **WebConfig.storage_state**: 新增配置字段，BrowserManager 自动注入到 context
+
+### 📚 文档
+
+- 📝 **Web UI 测试手册**: 新增「认证状态管理」章节
+- 📝 **认证指南**: 新增 UI 认证与 HTTP 认证对比
+
+**详细内容**: 查看完整发布说明 [v4.0.3.md](docs/releases/v4.0.3.md)
+
+---
+
 ## [4.0.2] - 2026-02-09
 
 ### ✨ 新增功能

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

@@ -122,11 +122,33 @@ def test_login(self): ...
 
 ## 版本发布
 
-**每次发布必须更新**:
-1. `pyproject.toml` + `__init__.py` 版本号
+发布新版本时，严格按以下顺序执行：
+
+### Step 1: 更新文件
+
+1. `pyproject.toml` + `src/df_test_framework/__init__.py` 版本号
 2. `CHANGELOG.md` - 简洁摘要
 3. `docs/releases/vX.X.X.md` - 详细发布说明
 4. `docs/guides/xxx.md` - 功能使用指南（如有新功能）
+5. `cli/templates/` - 脚手架模板（如有影响）
+
+### Step 2: 代码质量检查（必须全部通过）
+
+```bash
+uv run ruff check --fix src/ tests/                 # lint 检查
+uv run ruff format src/ tests/                       # 格式化
+uv run pytest -v --ignore=tests/test_messengers/     # 测试（排除 MQ）
+```
+
+如果有格式化改动，合并到发布 commit 中。
+
+### Step 3: 提交发布
+
+```bash
+git add <相关文件>
+git commit -m "chore(release): 发布 vX.X.X 版本"
+git push origin master
+```
 
 **Commit Message**: `<type>(<scope>): <subject>`
 - Type: feat/fix/docs/test/refactor/chore

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.0.2
+Version: 4.1.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.0.2 → df_test_framework-4.1.0}/README.md

@@ -176,6 +176,10 @@ uv run pytest -v      # 运行测试
 # 方式2: 传统方式
 uv pip install -e ".[all,dev]"  # 安装所有依赖
 pytest -v                        # 运行测试
+
+# 测试项目中更新本地框架
+cd /path/to/your-test-project
+uv sync --reinstall-package df-test-framework  # 强制重新安装框架
 ```
 
 ---

{df_test_framework-4.0.2 → df_test_framework-4.1.0}/docs/api-reference/drivers.md

@@ -69,6 +69,7 @@ from df_test_framework.drivers.web.playwright import (
 - ✅ 上下文管理
 - ✅ 页面管理
 - ✅ 截图和录制
+- ✅ storageState 认证状态注入（v4.0.3）
 
 ### 快速开始
 
@@ -76,16 +77,17 @@ from df_test_framework.drivers.web.playwright import (
 from df_test_framework import BrowserManager, BrowserType
 
 # 创建浏览器管理器
-browser_mgr = BrowserManager(
+manager = BrowserManager(
     browser_type=BrowserType.CHROMIUM,
     headless=False
 )
 
-# 启动浏览器
-browser_mgr.start()
+# 启动浏览器（v4.1.0: 只创建 playwright + browser）
+manager.start()
 
-# 创建页面
-page = browser_mgr.new_page()
+# 创建隔离的上下文和页面
+ctx = manager.new_context()
+page = ctx.new_page()
 page.goto("https://example.com")
 
 # 操作页面
@@ -95,38 +97,90 @@ page.click("button[type='submit']")
 # 截图
 page.screenshot(path="screenshot.png")
 
-# 关闭浏览器
-browser_mgr.close()
+# 关闭资源
+page.close()
+ctx.close()
+manager.stop()
 ```
 
 ### 核心方法
 
 #### 生命周期管理
-- `start()` - 启动浏览器
-- `close()` - 关闭浏览器
-- `new_page()` - 创建新页面
-- `new_context(**kwargs)` - 创建新上下文
+- `start()` - 启动 Playwright 进程和浏览器实例，返回 `Browser`
+- `stop()` - 关闭浏览器并清理 Playwright 进程
+- `new_context(storage_state=None, **extra_options)` - 创建隔离的浏览器上下文（v4.1.0）
 
-#### 页面管理
-- `get_page(index=0)` - 获取页面
-- `get_pages()` - 获取所有页面
-- `close_page(page)` - 关闭页面
+#### 属性
+- `browser` - 获取浏览器实例（只读，未启动时抛出 RuntimeError）
 
 ### 配置选项
 
 ```python
-browser_mgr = BrowserManager(
+manager = BrowserManager(
     browser_type=BrowserType.CHROMIUM,  # 浏览器类型
     headless=False,                      # 是否无头模式
     slow_mo=0,                          # 操作延迟（ms）
     viewport={"width": 1920, "height": 1080},  # 视口大小
-    locale="zh-CN",                     # 语言
-    timezone_id="Asia/Shanghai",        # 时区
+    timeout=30000,                      # 默认超时时间（ms）
+    record_video="off",                 # 视频录制（off/on/on-failure）
+    video_dir="reports/videos",         # 视频保存目录
 )
+
+# v4.1.0: 创建带认证状态的上下文
+ctx = manager.new_context(storage_state="path/to/state.json")
+page = ctx.new_page()
 ```
 
 ---
 
+## 🔐 AuthSetup / AsyncAuthSetup - 认证状态设置器
+
+> **版本**: v4.0.3+
+
+### 功能特性
+
+- ✅ 管理临时浏览器完整生命周期
+- ✅ context manager 自动资源清理
+- ✅ 保存 Playwright storageState（cookies + localStorage）
+- ✅ 同步 / 异步双版本
+
+### 快速开始
+
+```python
+from df_test_framework.testing import AuthSetup
+
+# 同步版本
+with AuthSetup(settings, tmp_path) as auth:
+    auth.page.goto(f"{auth.base_url}/login")
+    auth.page.fill("#username", "admin")
+    auth.page.fill("#password", "pass")
+    auth.page.click("button[type=submit]")
+    state_path = auth.save()  # 返回 JSON 文件路径
+```
+
+```python
+from df_test_framework.testing import AsyncAuthSetup
+
+# 异步版本
+async with AsyncAuthSetup(settings, tmp_path) as auth:
+    await auth.page.goto(f"{auth.base_url}/login")
+    await auth.page.fill("#username", "admin")
+    await auth.page.fill("#password", "pass")
+    await auth.page.click("button[type=submit]")
+    state_path = await auth.save()
+```
+
+### API
+
+| 属性/方法 | 说明 |
+|----------|------|
+| `page` | 临时浏览器页面，用于执行登录操作 |
+| `context` | 临时浏览器上下文 |
+| `base_url` | 从 `settings.web.base_url` 读取 |
+| `save(filename="state.json")` | 保存 storageState 到 JSON 文件，返回路径 |
+
+---
+
 ## 📄 BasePage - 页面对象基类
 
 ### 功能特性
@@ -316,14 +370,15 @@ class SearchResultsPage(BasePage):
 @pytest.fixture
 def browser():
     """浏览器fixture"""
-    browser_mgr = BrowserManager(headless=True)
-    browser_mgr.start()
-    yield browser_mgr
-    browser_mgr.close()
+    manager = BrowserManager(headless=True)
+    manager.start()
+    yield manager
+    manager.stop()
 
 def test_search_functionality(browser):
     """测试搜索功能"""
-    page = browser.new_page()
+    ctx = browser.new_context()
+    page = ctx.new_page()
 
     # 访问首页
     home_page = HomePage(page)
@@ -338,6 +393,9 @@ def test_search_functionality(browser):
 
     # 截图
     results_page.screenshot("search_results.png")
+
+    page.close()
+    ctx.close()
 ```
 
 ---

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

@@ -1,14 +1,16 @@
 # 认证与 Session 管理指南
 
-> **版本要求**: df-test-framework >= 3.19.0
-> **更新日期**: 2025-12-24
-> **最新版本**: v3.38.0
+> **版本要求**: df-test-framework >= 3.19.0（HTTP），>= 4.0.3（UI），>= 4.1.0（Browser Session 复用）
+> **更新日期**: 2026-03-03
+> **最新版本**: v4.1.0
 
 ---
 
 ## 概述
 
-本指南介绍如何正确处理 **Bearer Token 认证** 与 **HTTP Session（Cookies）** 的交互问题，特别是在测试登出流程时可能遇到的 **Token 复用** 问题。
+本指南介绍如何正确处理认证状态管理：
+- **HTTP 测试**: Bearer Token 认证与 Session（Cookies）的交互
+- **UI 测试**: Playwright storageState 认证状态复用（v4.0.3）
 
 **v3.25.0 新增**:
 - ✅ `reset_auth_state()` - 组合方法，一次调用完全清除认证状态（推荐）
@@ -411,6 +413,59 @@ del http_client.client.cookies["JSESSIONID"]
 
 ---
 
+## UI 认证状态管理（v4.0.3）
+
+### HTTP 与 UI 认证对比
+
+| 维度 | HTTP bearer_token | UI storageState |
+|------|------------------|-----------------|
+| **认证执行** | 框架自动调登录 API | 项目写登录逻辑（UI 流程多变） |
+| **状态缓存** | session 级别缓存 token | session 级别缓存 storageState JSON |
+| **状态注入** | 中间件注入 Authorization header | context fixture 注入 storage_state 到 BrowserContext |
+| **跳过认证** | `skip_auth=True` | `browser.new_context()`（不带 storage_state） |
+| **多角色** | 多个 API 实例 | 多个 storage_state fixture |
+
+### 使用 AuthSetup
+
+```python
+# conftest.py
+import pytest
+from df_test_framework.testing import AuthSetup
+
+@pytest.fixture(scope="session")
+def storage_state(tmp_path_factory, settings):
+    with AuthSetup(settings, tmp_path_factory.mktemp("auth")) as auth:
+        auth.page.goto(f"{auth.base_url}/login")
+        auth.page.fill("#username", settings.business.admin_username)
+        auth.page.fill("#password", settings.business.admin_password)
+        auth.page.click("button[type=submit]")
+        auth.page.wait_for_url("**/dashboard")
+        return auth.save()
+
+# 测试用例 — page 自动已认证
+def test_dashboard(page):
+    page.goto("/dashboard")
+    assert page.get_by_text("监控管理").is_visible()
+```
+
+### 未认证场景
+
+从 `browser` 创建不带 storage_state 的 context：
+
+```python
+def test_unauthenticated_redirect(browser):
+    context = browser.new_context()
+    page = context.new_page()
+    page.goto("https://example.com/dashboard")
+    assert "/login" in page.url
+    page.close()
+    context.close()
+```
+
+详细用法参考 [Web UI 测试使用手册](web-ui-testing.md#3-认证状态管理storagstate)。
+
+---
+
 ## 相关文档
 
 - [中间件使用指南](middleware_guide.md) - 了解 BearerTokenMiddleware

{df_test_framework-4.0.2 → df_test_framework-4.1.0}/docs/guides/fixtures_guide.md

@@ -1,6 +1,6 @@
 # Fixtures 使用指南
 
-> **最后更新**: 2026-01-17
+> **最后更新**: 2026-03-03
 > **适用版本**: v3.0.0+
 
 ---
@@ -243,6 +243,30 @@ REDIS__PASSWORD=your_password
 
 ### UI 测试 Fixtures
 
+#### `storage_state` - 认证状态路径
+
+**Scope**: `session`
+**版本**: v4.0.3+
+
+Playwright storageState JSON 文件路径，框架默认返回 `None`（未认证）。项目在 `conftest.py` 中覆盖此 fixture 以提供认证状态，`page` 将自动携带 cookies/localStorage。
+
+```python
+# conftest.py — 覆盖框架默认的 storage_state
+import pytest
+from df_test_framework.testing import AuthSetup
+
+@pytest.fixture(scope="session")
+def storage_state(tmp_path_factory, settings):
+    """整个测试 session 只登录一次，后续 page 自动已认证"""
+    with AuthSetup(settings, tmp_path_factory.mktemp("auth")) as auth:
+        auth.page.goto(f"{auth.base_url}/login")
+        auth.page.fill("#username", "admin")
+        auth.page.fill("#password", "admin123")
+        auth.page.click("button[type=submit]")
+        auth.page.wait_for_url("**/dashboard")
+        return auth.save()
+```
+
 #### `page` - 同步页面实例
 
 **Scope**: `function`
@@ -294,10 +318,10 @@ async def test_login(async_page):
 
 #### `browser` / `async_browser` - 浏览器实例
 
-**Scope**: `function`
-**版本**: v3.0.0+ / v4.0.0+
+**Scope**: `session`
+**版本**: v3.0.0+ / v4.0.0+（v4.1.0 提升为 session scope）
 
-Playwright 浏览器实例，用于获取浏览器信息或创建多个上下文。
+Playwright 浏览器实例，整个测试会话共享。用于获取浏览器信息或创建多个上下文。
 
 ```python
 def test_browser_info(browser):
@@ -311,7 +335,7 @@ def test_browser_info(browser):
 **Scope**: `function`
 **版本**: v3.0.0+ / v4.0.0+
 
-浏览器上下文，用于管理 cookies、存储等。
+浏览器上下文，每个测试独立隔离。v4.1.0 起自动注入 `storage_state` 认证状态。
 
 ```python
 def test_with_cookies(context):
@@ -328,20 +352,20 @@ def test_with_cookies(context):
 
 #### `browser_manager` / `async_browser_manager` - 浏览器管理器
 
-**Scope**: `function`
-**版本**: v3.0.0+ / v4.0.0+
+**Scope**: `session`
+**版本**: v3.0.0+ / v4.0.0+（v4.1.0 提升为 session scope）
 
-完整的浏览器管理器，包含 browser、context、page。
+浏览器管理器，管理 Playwright 进程和浏览器实例。v4.1.0 起只管理 playwright + browser（session 级别复用），context/page 由独立 fixture 管理。
 
 ```python
 def test_with_manager(browser_manager):
     """使用浏览器管理器"""
-    page = browser_manager.page
+    # 创建隔离的 context（通常由框架 fixture 自动完成）
+    ctx = browser_manager.new_context()
+    page = ctx.new_page()
     page.goto("https://example.com")
-
-    # 访问配置
-    base_url = browser_manager.base_url
-    print(f"Base URL: {base_url}")
+    page.close()
+    ctx.close()
 ```
 
 **配置示例**:
@@ -699,13 +723,16 @@ async_database       # session
 redis_client         # session
 async_redis_client   # session
 runtime              # session
+storage_state        # session（v4.0.3，认证状态路径）
+browser_manager      # session（v4.1.0，浏览器管理器）
+browser              # session（v4.1.0，浏览器实例）
 
 # Function 级别（每个测试独立）
 test_runtime         # function
-page                 # function
+context              # function（浏览器上下文，每测试隔离）
+page                 # function（页面实例，每测试隔离）
+async_context        # function
 async_page           # function
-browser              # function
-context              # function
 uow                  # function
 cleanup              # function
 prepare_data         # function
@@ -1070,6 +1097,7 @@ def test_user_order_flow(user_api, order_api):
 
 | Fixture | Scope | 版本 | 说明 |
 |---------|-------|------|------|
+| `storage_state` | session | v4.0.3+ | storageState 认证状态路径 |
 | `http_client` | session | v2.0.0+ | 同步 HTTP 客户端 |
 | `async_http_client` | session | v4.0.0+ | 异步 HTTP 客户端 |
 | `database` | session | v2.0.0+ | 同步数据库客户端 |
@@ -1078,7 +1106,8 @@ def test_user_order_flow(user_api, order_api):
 | `async_redis_client` | session | v4.0.0+ | 异步 Redis 客户端 |
 | `page` | function | v3.0.0+ | 同步 Playwright 页面 |
 | `async_page` | function | v4.0.0+ | 异步 Playwright 页面 |
-| `browser` | function | v3.0.0+ | 同步浏览器实例 |
+| `browser` | session | v3.0.0+（v4.1.0 提升） | 同步浏览器实例 |
+| `browser_manager` | session | v3.0.0+（v4.1.0 提升） | 浏览器管理器 |
 | `context` | function | v3.0.0+ | 同步浏览器上下文 |
 | `runtime` | session | v3.37.0+ | 运行时上下文 |
 | `test_runtime` | function | v3.44.0+ | 测试专用运行时 |
@@ -1099,6 +1128,7 @@ def test_user_order_flow(user_api, order_api):
 
 ## 版本历史
 
+- **v4.1.0** (2026-03-03): Browser Session 复用，`browser_manager`/`browser` 提升为 session scope，context/page 保持 function scope 每测试隔离
 - **v4.0.0** (2026-01-16): 全面异步化，新增 `async_http_client`、`async_database`、`async_redis_client`、`async_page` 等异步 fixtures
 - **v3.45.0** (2025-12): 新增 `@api_class` 和 `@actions_class` 装饰器，API/Actions 自动加载
 - **v3.44.0** (2025-11): 新增 `test_runtime` fixture，测试专用事件作用域

{df_test_framework-4.0.2 → df_test_framework-4.1.0}/docs/guides/scaffold_cli_guide.md

@@ -137,7 +137,7 @@ my_project/
 │   └── fixtures/
 │       └── __init__.py
 ├── tests/
-│   ├── conftest.py             # UI 测试配置（含 load_actions_fixtures）
+│   ├── conftest.py             # UI 测试配置（含 load_actions_fixtures + storage_state 示例）
 │   └── ui/
 │       └── test_login.py       # UI 示例测试
 └── ...