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

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

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

{df_test_framework-4.0.3 → 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.3 → df_test_framework-4.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.0.3
+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.3 → df_test_framework-4.1.0}/docs/api-reference/drivers.md

@@ -77,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")
 
 # 操作页面
@@ -96,35 +97,38 @@ 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",        # 时区
-    storage_state="path/to/state.json", # storageState 认证状态（v4.0.3）
+    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()
 ```
 
 ---
@@ -366,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)
@@ -388,6 +393,9 @@ def test_search_functionality(browser):
 
     # 截图
     results_page.screenshot("search_results.png")
+
+    page.close()
+    ctx.close()
 ```
 
 ---

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

@@ -1,8 +1,8 @@
 # 认证与 Session 管理指南
 
-> **版本要求**: df-test-framework >= 3.19.0（HTTP），>= 4.0.3（UI）
-> **更新日期**: 2026-03-01
-> **最新版本**: v4.0.3
+> **版本要求**: df-test-framework >= 3.19.0（HTTP），>= 4.0.3（UI），>= 4.1.0（Browser Session 复用）
+> **更新日期**: 2026-03-03
+> **最新版本**: v4.1.0
 
 ---
 
@@ -421,7 +421,7 @@ del http_client.client.cookies["JSESSIONID"]
 |------|------------------|-----------------|
 | **认证执行** | 框架自动调登录 API | 项目写登录逻辑（UI 流程多变） |
 | **状态缓存** | session 级别缓存 token | session 级别缓存 storageState JSON |
-| **状态注入** | 中间件注入 Authorization header | BrowserManager 注入 storage_state 到 context |
+| **状态注入** | 中间件注入 Authorization header | context fixture 注入 storage_state 到 BrowserContext |
 | **跳过认证** | `skip_auth=True` | `browser.new_context()`（不带 storage_state） |
 | **多角色** | 多个 API 实例 | 多个 storage_state fixture |
 

{df_test_framework-4.0.3 → 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+
 
 ---
@@ -318,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):
@@ -335,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):
@@ -352,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()
 ```
 
 **配置示例**:
@@ -724,13 +724,15 @@ 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
@@ -1104,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+ | 测试专用运行时 |
@@ -1125,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.3 → df_test_framework-4.1.0}/docs/guides/web-ui-testing.md

@@ -1,7 +1,7 @@
 # Web UI 测试使用手册
 
-> **最后更新**: 2026-03-01
-> **适用版本**: v3.0.0+（同步 AppActions），v4.0.0+（异步 AsyncAppActions），v4.0.3+（storageState 认证状态）
+> **最后更新**: 2026-03-03
+> **适用版本**: v3.0.0+（同步 AppActions），v4.0.0+（异步 AsyncAppActions），v4.0.3+（storageState 认证状态），v4.0.4+（pytest_config CLI 参数一致性），v4.1.0+（Browser Session 复用）
 
 ## 概述
 
@@ -16,6 +16,12 @@
 > - ✅ 性能提升 2-3 倍
 > - ✅ 更好的资源管理（async with 上下文管理器）
 >
+> **v4.1.0 架构优化**:
+> - ✅ Browser Session 复用：`browser_manager`/`browser` 提升为 session scope，整个测试会话只启动一次浏览器
+> - ✅ Context/Page 每测试隔离：`context`/`page` 保持 function scope，每个测试独立
+> - ✅ 对齐 Playwright 官方最佳实践（pytest-playwright 插件模式）
+> - ✅ storageState 下沉到 context 级别注入，更符合 Playwright 设计
+>
 > 本指南主要介绍**同步版本**（向后兼容）。异步版本使用方法请参考：
 > - [v4.0.0 发布说明](../releases/v4.0.0.md) - 异步 UI 测试概述
 > - [五层架构详解](../architecture/五层架构详解.md#layer-2-capabilities) - AsyncAppActions 详细说明
@@ -135,7 +141,7 @@ WEB__BASE_URL=https://web.example.com       # Web 地址
 
 ## 3. 认证状态管理（storageState）
 
-> **版本**: v4.0.3+
+> **版本**: v4.0.3+（基础功能），v4.0.4+（pytest_config CLI 参数一致性）
 
 绝大多数 UI 测试的前提是「用户已登录」。v4.0.3 原生支持 Playwright storageState，`page` 自动携带认证状态，测试零感知。
 
@@ -147,7 +153,7 @@ WEB__BASE_URL=https://web.example.com       # Web 地址
 |------|------------------|-----------------|
 | **认证执行** | 框架自动调登录 API | 项目写登录逻辑（UI 登录流程多变） |
 | **状态缓存** | session 级别缓存 token | session 级别缓存 storageState JSON |
-| **状态注入** | 中间件自动注入 Authorization header | BrowserManager 自动注入 storage_state 到 context |
+| **状态注入** | 中间件自动注入 Authorization header | context fixture 自动注入 storage_state 到 BrowserContext |
 | **项目责任** | 提供 credentials 配置 | 提供 `storage_state` fixture |
 
 ### 3.2 使用方式
@@ -160,9 +166,9 @@ import pytest
 from df_test_framework.testing import AuthSetup
 
 @pytest.fixture(scope="session")
-def storage_state(tmp_path_factory, settings):
+def storage_state(tmp_path_factory, settings, request):
     """Session 级别认证状态 — 整个测试 session 只登录一次"""
-    with AuthSetup(settings, tmp_path_factory.mktemp("auth")) as auth:
+    with AuthSetup(settings, tmp_path_factory.mktemp("auth"), pytest_config=request.config) 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)
@@ -171,6 +177,8 @@ def storage_state(tmp_path_factory, settings):
         return auth.save()
 ```
 
+> **v4.0.4**: `pytest_config=request.config` 使 AuthSetup 自动读取 `--headed`/`--browser`/`--slowmo` 命令行参数，确保 auth 浏览器与测试浏览器模式一致。如果不传此参数，auth 浏览器始终使用 `settings.web` 中的配置，当用户通过 `--headed` 切换到有头模式时，auth 浏览器仍为无头模式，可能因 User-Agent 不一致导致认证状态失效。
+
 之后所有测试的 `page` 自动已认证：
 
 ```python
@@ -186,7 +194,16 @@ def test_dashboard(page):
 
 ```python
 class AuthSetup:
-    def __init__(self, settings, state_dir): ...
+    def __init__(self, settings, state_dir, **overrides):
+        """
+        Args:
+            settings: 框架设置对象（读取 web.base_url / web.headless / web.viewport）
+            state_dir: storageState 文件保存目录
+            **overrides: 关键字参数覆盖，支持:
+                - pytest_config: pytest.Config 对象，自动读取 --headed 等 CLI 参数（v4.0.4）
+                - headless (bool): 显式指定无头模式（优先级高于 pytest_config）
+                - viewport (dict): 视口大小
+        """
 
     # 属性
     page        # 临时浏览器页面，用于执行登录操作
@@ -198,6 +215,12 @@ class AuthSetup:
         """保存 storageState 到 JSON 文件，返回路径"""
 ```
 
+**配置优先级**（从高到低）：
+1. 显式关键字参数（`headless=False`）
+2. CLI 参数（通过 `pytest_config` 读取 `--headed`/`--browser`/`--slowmo`）
+3. 配置文件（`settings.web.headless`/`settings.web.viewport`）
+4. 默认值（`headless=True`，`viewport=1920x1080`）
+
 异步版本 `AsyncAuthSetup` 用法相同，使用 `async with`。
 
 ### 3.4 四种认证场景
@@ -253,9 +276,9 @@ def test_unauthenticated_redirect(browser):
 
 ```python
 @pytest.fixture(scope="session")
-def user_storage_state(tmp_path_factory, settings):
+def user_storage_state(tmp_path_factory, settings, request):
     """普通用户认证状态"""
-    with AuthSetup(settings, tmp_path_factory.mktemp("auth-user")) as auth:
+    with AuthSetup(settings, tmp_path_factory.mktemp("auth-user"), pytest_config=request.config) as auth:
         # 普通用户登录逻辑...
         return auth.save()
 
@@ -284,10 +307,10 @@ def test_admin_vs_user(page, browser, user_storage_state):
 | Fixture | 作用域 | 描述 |
 |---------|--------|------|
 | `storage_state` | session | 认证状态路径（v4.0.3，默认 None） |
-| `browser_manager` | function | 浏览器管理器（自动注入 storage_state） |
-| `browser` | function | 浏览器实例 |
-| `context` | function | 浏览器上下文（隔离） |
-| `page` | function | 页面实例 |
+| `browser_manager` | session | 浏览器管理器（v4.1.0 Session 复用） |
+| `browser` | session | 浏览器实例（v4.1.0 Session 复用） |
+| `context` | function | 浏览器上下文（每测试隔离，自动注入 storage_state） |
+| `page` | function | 页面实例（每测试隔离） |
 | `app_actions` | function | 基础业务操作（v3.45.0） |
 | `goto` | function | 页面导航助手 |
 | `screenshot` | function | 截图助手 |
@@ -948,10 +971,13 @@ class LoginActions(AppActions):
 默认情况下，测试在无头模式下运行（不显示浏览器窗口）。开发调试时可以显示浏览器窗口：
 
 ```bash
-# 方式 1: 环境变量配置
+# 方式 1: 命令行参数（推荐，v4.0.2+）
+uv run pytest tests/ui/ --headed -v
+
+# 方式 2: 环境变量配置
 WEB__HEADLESS=false uv run pytest tests/ui/ -v
 
-# 方式 2: 配置文件
+# 方式 3: 配置文件
 # config/environments/local.yaml
 web:
   headless: false
@@ -967,7 +993,10 @@ uv run pytest tests/ui/ --env=local -v
 减慢操作速度，便于观察每个步骤：
 
 ```bash
-# 每个操作延迟 1000 毫秒（1 秒）
+# 方式 1: 命令行参数（推荐，v4.0.2+）
+uv run pytest tests/ui/ --headed --slowmo 1000 -v
+
+# 方式 2: 每个操作延迟 1000 毫秒（1 秒）
 WEB__SLOW_MO=1000 uv run pytest tests/ui/ -v
 
 # 或在配置文件中设置
@@ -1125,6 +1154,11 @@ def test_login_flow(page, base_url):
 测试不同浏览器的兼容性：
 
 ```bash
+# 命令行参数（推荐，v4.0.2+）
+uv run pytest tests/ui/ --browser firefox -v
+uv run pytest tests/ui/ --browser webkit -v
+
+# 环境变量
 # Chromium（默认）
 WEB__BROWSER_TYPE=chromium uv run pytest tests/ui/ -v
 
@@ -1321,5 +1355,8 @@ class LoginPage(BasePage):
 - [v3.43.0 发布说明](../releases/v3.43.0.md) - 现代 UI 测试最佳实践
 - [v3.44.0 发布说明](../releases/v3.44.0.md) - 事件驱动架构
 - [v3.45.0 发布说明](../releases/v3.45.0.md) - @actions_class 装饰器
+- [v4.0.3 发布说明](../releases/v4.0.3.md) - storageState 认证状态
+- [v4.0.4 发布说明](../releases/v4.0.4.md) - pytest_config CLI 参数一致性
+- [v4.1.0 发布说明](../releases/v4.1.0.md) - Browser Session 复用 + Context/Page 隔离
 - [架构设计文档](../architecture/README.md)
 - [Playwright 官方文档](https://playwright.dev/python/)

df_test_framework-4.1.0/docs/releases/v4.0.4.md

@@ -0,0 +1,135 @@
+# v4.0.4 发布说明
+
+**发布日期**: 2026-03-02
+**类型**: 补丁版本（Patch Release）
+**主题**: AuthSetup 支持 pytest_config — 确保 auth 浏览器与测试浏览器 CLI 参数一致
+
+---
+
+## 概述
+
+v4.0.4 解决了一个实际场景中的 User-Agent 不一致问题：当用户通过 `--headed` 命令行参数切换到有头模式调试时，auth 浏览器仍使用无头模式，两者 User-Agent 不同，可能导致服务端认为 storageState 无效。
+
+**解决方案**: `AuthSetup` / `AsyncAuthSetup` 新增 `pytest_config` 参数，自动读取 `--headed`/`--browser`/`--slowmo` 命令行参数，确保 auth 浏览器与测试浏览器模式完全一致。
+
+---
+
+## 新增功能
+
+### 1. pytest_config 参数支持
+
+`AuthSetup` 和 `AsyncAuthSetup` 构造函数新增 `pytest_config` 关键字参数：
+
+```python
+@pytest.fixture(scope="session")
+def storage_state(tmp_path_factory, settings, request):
+    with AuthSetup(
+        settings,
+        tmp_path_factory.mktemp("auth"),
+        pytest_config=request.config,  # v4.0.4: 自动读取 CLI 参数
+    ) 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()
+```
+
+异步版本：
+
+```python
+@pytest.fixture(scope="session")
+async def storage_state(tmp_path_factory, settings, request):
+    async with AsyncAuthSetup(
+        settings,
+        tmp_path_factory.mktemp("auth"),
+        pytest_config=request.config,
+    ) as auth:
+        await auth.page.goto(f"{auth.base_url}/login")
+        # ...
+        return await auth.save()
+```
+
+### 2. 配置优先级
+
+AuthSetup 的配置参数按以下优先级解析（从高到低）：
+
+| 优先级 | 来源 | 示例 |
+|--------|------|------|
+| 1 | 显式关键字参数 | `AuthSetup(..., headless=False)` |
+| 2 | CLI 参数（通过 pytest_config） | `--headed` / `--browser firefox` / `--slowmo 500` |
+| 3 | 配置文件 | `settings.web.headless` / `settings.web.viewport` |
+| 4 | 默认值 | `headless=True`，`viewport=1920x1080` |
+
+### 3. 支持的 CLI 参数
+
+| CLI 参数 | AuthSetup 字段 | 说明 |
+|---------|----------------|------|
+| `--headed` | `headless=False` | 显示浏览器窗口 |
+| `--browser <type>` | `browser_type` | 浏览器类型（chromium/firefox/webkit） |
+| `--slowmo <ms>` | `slow_mo` | 操作延迟毫秒数 |
+
+---
+
+## 问题背景
+
+### User-Agent 不一致导致认证失败
+
+Chromium 在无头模式和有头模式下发送不同的 User-Agent：
+
+```
+# 无头模式
+Mozilla/5.0 ... HeadlessChrome/...
+
+# 有头模式
+Mozilla/5.0 ... Chrome/...
+```
+
+如果 auth 浏览器（无头）登录后保存 storageState，而测试浏览器（有头，通过 `--headed`）使用该 storageState，服务端可能因 User-Agent 变化而拒绝认证。
+
+**v4.0.4 之前**: 需要手动传 `headless=False` 给 AuthSetup（容易遗忘）。
+**v4.0.4 之后**: 传 `pytest_config=request.config` 即可，AuthSetup 自动匹配测试浏览器的模式。
+
+---
+
+## 设计说明
+
+### 为什么 AuthSetup 不能自动获取 pytest_config？
+
+`AuthSetup` 是框架提供的普通 Python 类，不在 pytest fixture 依赖注入体系内。而 `storage_state` 是项目实现的 fixture，由项目决定传入哪些参数。
+
+对比：
+
+| 组件 | 类型 | 能否自动获取 pytest_config |
+|------|------|--------------------------|
+| `browser_manager` | 框架 fixture | 能，声明 `request` 依赖，pytest 自动注入 |
+| `storage_state` | 项目 fixture | 能，但需要项目自己传给 AuthSetup |
+| `AuthSetup` | 普通类 | 不能，不在 pytest DI 体系内 |
+
+这保持了 AuthSetup 作为工具类的纯粹性 — 它不依赖 pytest，也可以在非 pytest 环境中使用。
+
+---
+
+## 改动文件
+
+| 文件 | 改动 |
+|------|------|
+| `testing/fixtures/auth.py` | AuthSetup / AsyncAuthSetup 支持 `pytest_config` 参数 |
+| `cli/templates/project/ui_conftest.py` | 脚手架模板更新 storage_state 示例 |
+| `cli/templates/project/full_conftest.py` | 同上 |
+
+---
+
+## 向后兼容
+
+- `pytest_config` 参数完全可选，不传时行为与 v4.0.3 一致
+- 无破坏性变更
+
+---
+
+## 相关文档
+
+- [Web UI 测试使用手册](../guides/web-ui-testing.md#3-认证状态管理storagstate)
+- [v4.0.3 发布说明](v4.0.3.md) — AuthSetup 首次引入
+- [v4.0.2 发布说明](v4.0.2.md) — `--headed`/`--browser`/`--slowmo` CLI 参数