From 1bae2f0e9f1c0a22ef80102f54179c2e048b28b4 Mon Sep 17 00:00:00 2001
From: longpeng <longpeng@wq.io>
Date: Fri, 27 Jun 2025 18:07:34 +0800
Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9EUI=E8=87=AA=E5=8A=A8=E5=8C=96?=
 =?UTF-8?q?=E9=93=BE=E8=B7=AF=E4=BD=BF=E7=94=A8=E8=AF=B4=E6=98=8E=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=EF=BC=8C=E8=AF=A6=E7=BB=86=E6=8F=8F=E8=BF=B0=E5=8A=9F?=
 =?UTF-8?q?=E8=83=BD=E3=80=81=E5=8F=82=E6=95=B0=E5=8F=8A=E5=A4=8D=E7=94=A8?=
 =?UTF-8?q?=E6=B5=8F=E8=A7=88=E5=99=A8=E7=9A=84=E7=94=A8=E6=B3=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/ui_test_usage.md | 64 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
 create mode 100644 docs/ui_test_usage.md

diff --git a/docs/ui_test_usage.md b/docs/ui_test_usage.md
new file mode 100644
index 0000000..e437367
--- /dev/null
+++ b/docs/ui_test_usage.md
@@ -0,0 +1,64 @@
+# UI自动化链路使用说明
+
+## 1. 功能简介
+本系统支持通过 Playwright 驱动浏览器，实现 UI 自动化测试。支持两种模式：
+- 每个 UI 步骤新开浏览器（默认）
+- 多个 UI 步骤复用同一个浏览器（如：第一个步骤登录，后续步骤基于已登录状态继续操作）
+
+## 2. 主要参数说明
+| 参数名              | 类型    | 说明                                   |
+|---------------------|---------|----------------------------------------|
+| browser_type        | string  | 浏览器类型（chromium/firefox/webkit）  |
+| headless            | bool    | 是否无头模式                           |
+| user_data           | map     | 登录等用户信息（如有需要）             |
+| browser_session_id  | string  | 浏览器会话ID（用于复用，系统自动传递） |
+| test_case_id        | string  | 用例ID                                 |
+| url_path            | string  | 页面路径                               |
+
+## 3. 复用浏览器的典型用法
+假设有两个步骤：
+- 步骤1：登录
+- 步骤2：添加新条目
+
+只需在用例配置中将两个步骤都设为 `RunUiTest`，系统会自动在步骤间传递 `browser_session_id`，实现浏览器复用。无需手动干预。
+
+**示例参数（JSON）**：
+```json
+{
+  "test_case_id": "login",
+  "url_path": "/login",
+  "browser_type": "chromium",
+  "headless": true,
+  "user_data": {"user": "test", "pass": "test"}
+}
+```
+
+第二步：
+```json
+{
+  "test_case_id": "add_item",
+  "url_path": "/dashboard",
+  "browser_type": "chromium",
+  "headless": true,
+  "user_data": {}
+}
+```
+
+## 4. 工作流结束后
+系统会自动关闭最后一个 UI 测试用到的浏览器，无需手动清理。
+
+## 5. 结果变量
+- `${step.步骤ID.screenshot_url}`：获取某步骤的截图URL
+- `${step.步骤ID.html_report_url}`：获取某步骤的HTML报告URL
+
+## 6. 常见问题
+- **Q: 如何确保多个步骤复用同一个浏览器？**
+  A: 只要步骤类型为 `RunUiTest`，系统会自动传递 browser_session_id。
+- **Q: 需要手动关闭浏览器吗？**
+  A: 不需要，系统会在工作流结束时自动关闭。
+- **Q: 可以并发多个浏览器会话吗？**
+  A: 支持，每个工作流独立管理自己的 browser_session_id。
+
+## 7. 参考
+- 详细参数传递机制见 `docs/activity_parameter_passing.md`
+- UI 测试用例开发可参考 `workers/python/ui_tests.py` 
\ No newline at end of file