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

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

@@ -5,6 +5,23 @@
 格式基于 [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
 
 ### 🐛 修复

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: df-test-framework
-Version: 4.4.4
+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.4 → 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.4 → 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.4 → 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.4 → 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())
 ```
 

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

@@ -0,0 +1,235 @@
+# v4.5.0 发布说明
+
+**发布日期**: 2026-05-12
+**版本类型**: MINOR（新增显式多客户端模型，向后兼容）
+**主题**: 多前端 UI Client + 显式默认客户端绑定
+
+---
+
+## 概述
+
+v4.5.0 引入**显式多客户端模型**，解决多前端测试项目长期存在的两个痛点：
+
+1. **多前端 UI 测试**：B 端后台、H5、WebView 等无法共用同一套 `page`/`storage_state`/`base_url`，现在通过 `ui_client()` 声明独立的命名 UI Client，每套前端拥有完全隔离的 fixture 组。
+
+2. **多后端 API 测试**：项目有多个独立服务时，`@api_class` 无法明确绑定到某个服务的 HTTP Client，现在通过 `service_client(default=True)` 和 `@api_class(http_client=...)` 精确控制绑定关系。
+
+**向后兼容**：单前端/单后端项目**无需任何改动**，框架自动识别默认客户端。
+
+---
+
+## 新增功能
+
+### 1. `ui_client()` — 命名多前端 UI Client
+
+**影响文件**: `src/df_test_framework/testing/decorators/ui_client.py`
+
+在业务项目 `clients/ui_clients.py` 中声明 UI Client：
+
+```python
+# src/{project}/clients/ui_clients.py
+from df_test_framework.testing.decorators import ui_client
+
+admin_ui = ui_client(
+    "admin_ui",
+    base_url_config="web.admin_url",
+    storage_state="admin_storage_state",
+    default=True,                          # 提供 page/context/browser_manager 别名
+)
+
+h5_ui = ui_client(
+    "h5_ui",
+    base_url_config="web.h5_url",
+    storage_state="h5_storage_state",
+    viewport={"width": 375, "height": 812},
+)
+```
+
+在 conftest.py 中加载：
+
+```python
+# conftest.py
+from {project}.clients import ui_clients as _ui_clients_module  # noqa: F401
+from df_test_framework.testing.decorators import load_ui_client_fixtures
+
+load_ui_client_fixtures(globals())
+```
+
+每个 UI Client 自动生成的 fixture 组：
+
+| Fixture | Scope | 说明 |
+|---------|-------|------|
+| `{name}_browser_manager` | session | BrowserManager，整个会话共享 |
+| `{name}_browser` | session | Playwright Browser 实例 |
+| `{name}_base_url` | session | 从 settings 解析的 base_url |
+| `{name}_context` | function | 独立 BrowserContext，含 storageState |
+| `{name}_page` | function | 独立 Page |
+| `{name}_app_actions` | function | AppActions 实例 |
+| `{name}_async_*` | 同上 | 异步版本对应 fixture |
+
+当 `default=True` 时，额外生成别名 fixture（`page`、`context`、`browser_manager`、`app_actions` 等），单前端项目无感迁移。
+
+### 2. `@actions_class(ui_client=...)` — 显式绑定 UI Client
+
+**影响文件**: `src/df_test_framework/testing/decorators/actions_class.py`
+
+多前端项目中，Actions 明确绑定到目标前端：
+
+```python
+# actions/admin/dashboard_actions.py
+from df_test_framework.testing.decorators import actions_class
+from df_test_framework import AppActions
+
+@actions_class(ui_client="admin_ui")        # 绑定到 admin_ui 前端
+class DashboardActions(AppActions):
+    def open_dashboard(self):
+        self.page.goto(f"{self.base_url}/dashboard")
+
+# actions/h5/product_actions.py
+@actions_class(ui_client="h5_ui")           # 绑定到 h5_ui 前端
+class ProductActions(AppActions):
+    def browse_product(self, product_id: int):
+        self.page.goto(f"{self.base_url}/products/{product_id}")
+```
+
+`@actions_class` 解析 `page`、`base_url` 等依赖时，从绑定的 UI Client 对应 fixture（`h5_ui_page`、`h5_ui_base_url`）取值，不再静默回退全局 `page`。
+
+### 3. `service_client(default=True)` — 默认 HTTP Client 注册
+
+**影响文件**: `src/df_test_framework/testing/decorators/service_client.py`
+
+```python
+# clients/default_http_client.py
+from df_test_framework.testing.decorators import service_client
+from df_test_framework import AsyncHttpClient
+
+@service_client(base_url_config="http.base_url", default=True)
+class DefaultHttpClient(AsyncHttpClient):
+    def __init__(self, base_url: str, runtime):
+        super().__init__(base_url=base_url, runtime=runtime)
+```
+
+`default=True` 注册后自动提供 `http_client` alias fixture，`@api_class()` 不指定 `http_client` 时自动绑定到它。
+
+### 4. `@api_class(http_client=...)` — 显式绑定 HTTP Client
+
+**影响文件**: `src/df_test_framework/testing/decorators/api_class.py`
+
+多服务项目中：
+
+```python
+# apis/payment/payment_api.py
+@api_class(http_client="payment_http_client")   # 明确绑定到支付服务客户端
+class PaymentAPI(BaseAPI):
+    def create_order(self, amount: float):
+        return self.post("/orders", json={"amount": amount})
+
+# apis/user/user_api.py
+@api_class()                                    # 绑定到默认 http_client
+class UserAPI(BaseAPI):
+    def get_user(self, user_id: int):
+        return self.get(f"/users/{user_id}")
+```
+
+---
+
+## 重构变更
+
+### 脚手架客户端目录统一
+
+`df-test init` 初始化的 API 和 Full 类型项目，客户端文件统一生成在 `clients/` 目录下：
+
+```
+src/{project}/
+├── clients/
+│   ├── __init__.py
+│   ├── default_http_client.py   # @service_client(default=True)
+│   └── ui_clients.py            # ui_client(..., default=True)
+├── apis/
+└── actions/
+```
+
+conftest.py 中服务客户端包路径统一为 `{project}.clients`：
+
+```python
+load_service_fixtures(globals(), services_package="{project}.clients")
+```
+
+**影响范围**：仅影响新建项目（`df-test init` 生成的模板）。存量项目不受影响。
+
+---
+
+## Bug 修复
+
+### 多 UI Client 同步混跑
+
+**问题**：多个 `BrowserManager` 实例（`admin_ui` 和 `h5_ui` 各一个）分别调用 `sync_playwright().start()`，在同一进程内启动多个 Playwright 实例，导致运行时冲突或资源泄漏。
+
+**修复**：同步 `BrowserManager` 和 `AuthSetup` 共用进程内同一个 Playwright 实例，通过引用计数管理生命周期：
+
+- 第一个 `BrowserManager.start()` 启动 Playwright
+- 后续调用复用同一实例，引用计数 +1
+- 每次 `BrowserManager.stop()` 引用计数 -1，归零时才真正停止
+
+**影响文件**: `src/df_test_framework/capabilities/drivers/web/playwright/browser.py`
+
+---
+
+## 迁移指南
+
+### 单前端项目：无需修改
+
+现有 conftest.py 使用全局 `page`、`context`、`browser_manager` 的项目无需任何改动。框架默认行为完全兼容。
+
+### 迁移到命名 UI Client（可选优化）
+
+如果项目已有单前端，想迁移到显式 UI Client 模式：
+
+**第一步**：新建 `clients/ui_clients.py`
+
+```python
+from df_test_framework.testing.decorators import ui_client
+
+main_ui = ui_client(
+    "main_ui",
+    base_url_config="web.base_url",
+    storage_state="storage_state",    # 现有 storage_state fixture 名
+    default=True,                     # 保持 page/context 别名不变
+)
+```
+
+**第二步**：在 conftest.py 中替换 UI 相关加载
+
+```python
+# 替换前
+from df_test_framework.testing.fixtures.ui import *
+
+# 替换后
+from {project}.clients import ui_clients as _  # noqa: F401
+from df_test_framework.testing.decorators import load_ui_client_fixtures
+load_ui_client_fixtures(globals())
+```
+
+由于声明了 `default=True`，原有的 `page`、`context`、`browser_manager` fixture 名称保持不变，测试代码**无需修改**。
+
+### 多服务 API 项目：添加显式绑定
+
+如果项目有多个 HTTP Client：
+
+```python
+# 修改前：可能绑定错误
+@api_class()
+class PaymentAPI(BaseAPI): ...
+
+# 修改后：明确绑定
+@api_class(http_client="payment_http_client")
+class PaymentAPI(BaseAPI): ...
+```
+
+---
+
+## 相关文档
+
+- [Web UI 测试使用手册](../guides/web-ui-testing.md) - UI Client 多前端配置
+- [装饰器使用指南](../guides/decorators_guide.md) - ui_client / service_client 完整 API
+- [服务客户端指南](../guides/service_client_guide.md) - default=True 注册方式

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

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