ui-automation

name: ui-automation description: WHartTest UI 自动化管理工具。用于创建、编辑、删除 UI 测试模块、页面、元素、页面步骤和测试用例。支持执行记录查询和错误分析。当需要将浏览器技能获取到的页面元素保存到平台、创建 UI 自动化用例、执行测试或分析执行结果时使用。元素采集默认优先 agent-browser-skill，无法覆盖时再用 playwright-skill 兜底。

WHartTest UI 自动化管理

生命周期概览

┌─────────────────────────────────────────────────────────────────┐
│                    UI 自动化完整生命周期                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. 设计阶段          2. 构建阶段           3. 执行阶段          │
│  ┌──────────┐        ┌──────────┐         ┌──────────┐         │
│  │ 查询模块  │        │ 查询页面  │         │ 执行用例  │         │
│  │ (是否存在)│        │ (是否存在)│         │ (运行)   │         │
│  └────┬─────┘        └────┬─────┘         └──────────┘         │
│       │ 不存在则创建        │ 不存在则创建        │               │
│       ↓                   ↓                    ↓               │
│  ┌──────────┐        ┌──────────┐         ┌──────────┐         │
│  │ 创建/复用 │        │ 添加元素  │         │ 查看记录  │         │
│  │ 模块/环境 │        │ (定位器) │         │ (状态)   │         │
│  └──────────┘        └──────────┘         └──────────┘         │
│                           │                    │               │
│                           ↓                    ↓               │
│                      ┌──────────┐         ┌──────────┐         │
│                      │ 创建步骤  │         │ 分析错误  │         │
│                      │ (操作)   │         │ (定位)   │         │
│                      └──────────┘         └──────────┘         │
│                           │                    │               │
│                           ↓                    ↓               │
│                      ┌──────────┐         ┌──────────┐         │
│                      │ 组装用例  │←────────│ 修复重试  │         │
│                      │ (P0-P3) │         │ (迭代)   │         │
│                      └──────────┘         └──────────┘         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

阶段说明

重要原则：先查后建

• 创建任何资源前，必须先使用对应的 get_* 操作查询是否已存在
• 如果已存在合适的资源，直接使用其 ID，避免重复创建

快速开始

# 执行操作
python ui_automation_tools.py --action <action_name> [--参数名 参数值]

元素采集策略（强制）

技术路线优先级

1. 默认使用 agent-browser-skill 进行页面访问、元素抓取与识别（Snapshot + Ref）。
2. 仅当 agent-browser-skill 无法稳定获取目标元素时，才使用 playwright-skill 兜底。
3. ui-automation-skill 负责将已确认的元素表达式入库并组装步骤/用例。

元素表达式质量标准（必须满足）

1. 唯一性：元素表达式在当前目标页面必须唯一匹配（期望匹配数为 1）。
2. 客观性：优先依赖页面客观稳定属性，不依赖主观描述和截图猜测。
3. 可维护性：优先选择改版后仍相对稳定的属性组合，避免脆弱路径。
4. 简约性：在满足唯一性的前提下，表达式尽量短且语义清晰。

推荐的定位优先级

1. test_id / data-testid / 业务稳定 id
2. role + name（可访问性语义）
3. name / label / placeholder（稳定时）
4. css（稳定属性组合）
5. xpath（仅在上面都不适用时）

反模式（避免）

1. 纯索引路径：如 :nth-child() 深层链、绝对 XPath（/html/body/...）
2. 易变 class：构建产物 hash class、运行时动态 class
3. 易变文本：时间戳、数量、用户名、随机文案

与 agent-browser-skill / playwright-skill 协作流程

agent-browser-skill            playwright-skill                 ui-automation-skill
       │                             │                                  │
       │ 1. 默认：snapshot/ref 抓取元素 │                                  │
       ├─────────────────────────────┼─────────────────────────────────→│ 2. 保存元素 (create_element)
       │                             │                                  │ 3. 创建步骤 (create_page_step)
       │ 1.1 若无法稳定获取元素       │ 1.2 兜底：获取选择器/结构信息        │ 4. 组装用例 (create_testcase)
       └─────────────失败时切换──────→├─────────────────────────────────→│
                                     │                                  │ 5. 执行并查看记录 (get_execution_records)
                                     │                                  │ 6. 分析错误并修复
                                     │                                  │ 7. 重新执行
                                     ↓                                  ↓

AI 错误分析流程

当执行失败时，AI 应按以下流程定位问题：

# 1. 获取最近失败的执行记录
python ui_automation_tools.py --action get_execution_records --status 3 --limit 1

# 2. 从 step_results 中定位失败步骤
#    - status: "failed" 的步骤
#    - message: 包含具体错误信息（超时、元素未找到等）
#    - element_found: false 表示定位器失效

# 3. 常见错误及解决方案：
#    - "Timeout exceeded": 元素定位器失效，需更新 locator_value
#    - "element not found": 页面结构变化，需重新获取元素（先 agent-browser，再 playwright 兜底）
#    - "Target page closed": 前序步骤导致页面关闭

# 4. 更新元素定位器
python ui_automation_tools.py --action update_element --element_id <id> --locator_value "<新选择器>"

可用操作

模块管理

页面管理

元素管理

定位类型（locator_type）可选值：

• css - CSS 选择器
• xpath - XPath
• text - 文本
• role - Role
• label - Label
• placeholder - Placeholder
• test_id - Test ID
• id - ID
• name - Name

页面步骤管理

步骤类型（step_type）可选值：

• 0 - 元素操作
• 1 - 断言操作
• 2 - SQL 操作
• 3 - 自定义变量
• 4 - 条件判断
• 5 - Python 代码

测试用例管理

用例等级（level）可选值： P0, P1, P2, P3

注意： get_testcases 返回精简数据（id, name, level, status 等），详情请使用 get_testcase

公共数据管理

执行记录管理

执行状态（status）可选值：

• 0 - 未执行
• 1 - 执行中
• 2 - 成功
• 3 - 失败
• 4 - 取消

批量执行记录管理

环境配置管理

浏览器类型（browser）可选值： chromium, firefox, webkit

执行器管理

执行数据获取

执行用例

执行参数说明：

• --config_id - 环境配置 ID（不传使用默认配置）
• --actuator_id - 执行器 ID（不传自动选择可用执行器）
• --wait_result - 是否等待执行结果（默认否，传此参数则等待）
• --exec_timeout - 等待超时时间（秒，默认 120）

注意： 执行前需确保有执行器在线（通过 get_actuators 查询）

使用示例

获取模块树

python ui_automation_tools.py --action get_ui_modules --project_id 1

创建页面

python ui_automation_tools.py --action create_ui_page \
  --project_id 1 \
  --module_id 5 \
  --name "登录页面" \
  --url "http://example.com/login" \
  --description "用户登录页面"

创建元素（优先基于 agent-browser-skill，失败时使用 playwright-skill）

# 单个元素
python ui_automation_tools.py --action create_element \
  --page_id 10 \
  --name "用户名输入框" \
  --locator_type css \
  --locator_value "#username" \
  --locator_type_2 xpath \
  --locator_value_2 "//input[@placeholder='请输入用户名']" \
  --description "登录页用户名输入框"

# 批量创建元素
python ui_automation_tools.py --action batch_create_elements \
  --page_id 10 \
  --elements '[
    {"name": "用户名输入框", "locator_type": "css", "locator_value": "#username"},
    {"name": "密码输入框", "locator_type": "css", "locator_value": "#password"},
    {"name": "登录按钮", "locator_type": "css", "locator_value": "button[type=submit]"}
  ]'

创建页面步骤

# 创建步骤
python ui_automation_tools.py --action create_page_step \
  --project_id 1 \
  --page_id 10 \
  --module_id 5 \
  --name "输入登录信息" \
  --description "输入用户名和密码"

# 设置步骤详情
python ui_automation_tools.py --action set_step_details \
  --step_id 20 \
  --steps '[
    {"step_type": 0, "element": 101, "ope_key": "fill", "ope_value": {"value": "admin"}},
    {"step_type": 0, "element": 102, "ope_key": "fill", "ope_value": {"value": "password123"}},
    {"step_type": 0, "element": 103, "ope_key": "click", "ope_value": {}}
  ]'

创建测试用例

# 创建用例
python ui_automation_tools.py --action create_testcase \
  --project_id 1 \
  --module_id 5 \
  --name "登录功能测试" \
  --description "验证用户登录功能" \
  --level P0

# 设置用例步骤（引用已创建的页面步骤）
python ui_automation_tools.py --action set_case_steps \
  --testcase_id 50 \
  --page_step_ids "20,21,22"

常用操作方法（ope_key）

输出格式

成功返回：

{"status": "success", "data": {...}}

失败返回：

{"status": "error", "message": "错误信息"}

完整生命周期示例

以下是 AI 使用 ui-automation-skill 的完整工作流程：

Phase 1: 设计阶段

# 1.1 先查询现有模块（检查是否已存在）
python ui_automation_tools.py --action get_ui_modules --project_id 1
# 如果已有合适的模块，直接使用其 id，无需创建

# 1.2 如果需要，创建新模块
python ui_automation_tools.py --action create_ui_module \
  --project_id 1 --name "用户模块"

# 1.3 查询现有环境配置（检查是否已存在）
python ui_automation_tools.py --action get_env_configs --project_id 1
# 如果已有合适的环境，直接使用，无需创建

# 1.4 如果需要，创建新环境配置
python ui_automation_tools.py --action create_env_config \
  --project_id 1 --name "开发环境" \
  --base_url "http://dev.example.com" \
  --browser chromium --headless false --timeout 30000

Phase 2: 构建阶段

# 2.1 查询现有页面（检查是否已存在同名页面）
python ui_automation_tools.py --action get_ui_pages --project_id 1 --module_id 10

# 2.2 如果需要，创建页面
python ui_automation_tools.py --action create_ui_page \
  --project_id 1 --module_id 10 --name "登录页面" --url "/login"

# 2.3 批量创建元素（基于元素采集策略：agent-browser 优先，playwright 兜底）
python ui_automation_tools.py --action batch_create_elements \
  --page_id 20 \
  --elements '[
    {"name": "用户名", "locator_type": "css", "locator_value": "#username"},
    {"name": "密码", "locator_type": "css", "locator_value": "#password"},
    {"name": "登录按钮", "locator_type": "css", "locator_value": "button[type=submit]"}
  ]'

# 2.3 创建页面步骤
python ui_automation_tools.py --action create_page_step \
  --project_id 1 --page_id 20 --module_id 10 --name "执行登录"

# 2.4 设置步骤详情（定义操作序列）
python ui_automation_tools.py --action set_step_details \
  --step_id 30 \
  --steps '[
    {"step_type": 0, "element": 100, "ope_key": "fill", "ope_value": {"value": "${{username}}"}},
    {"step_type": 0, "element": 101, "ope_key": "fill", "ope_value": {"value": "${{password}}"}},
    {"step_type": 0, "element": 102, "ope_key": "click", "ope_value": {}}
  ]'

# 2.5 创建测试用例
python ui_automation_tools.py --action create_testcase \
  --project_id 1 --module_id 10 --name "登录成功测试" --level P0

# 2.6 设置用例步骤（引用页面步骤）
python ui_automation_tools.py --action set_case_steps \
  --testcase_id 40 --page_step_ids "30"

# 2.7 创建公共数据（测试账号）
python ui_automation_tools.py --action create_public_data \
  --project_id 1 --key "username" --value "admin"
python ui_automation_tools.py --action create_public_data \
  --project_id 1 --key "password" --value "admin123"

Phase 3: 执行阶段

# 3.1 检查执行器是否在线
python ui_automation_tools.py --action get_actuators
# 确保至少有一个执行器 is_open: true

# 3.2 获取用例执行数据（用于调试验证）
python ui_automation_tools.py --action get_testcase_execute_data --testcase_id 40

# 3.3 执行用例（不等待结果）
python ui_automation_tools.py --action execute_testcase --testcase_id 40

# 3.4 执行用例（等待结果，最多120秒）
python ui_automation_tools.py --action execute_testcase --testcase_id 40 --wait_result --exec_timeout 120

# 3.5 查看执行记录
python ui_automation_tools.py --action get_execution_records --testcase_id 40 --limit 5

# 3.6 查看执行详情（分析结果）
python ui_automation_tools.py --action get_execution_record --record_id 100

Phase 4: 错误分析与修复

# 4.1 获取失败的执行记录
python ui_automation_tools.py --action get_execution_records --status 3 --limit 1
# 返回数据中的 step_results 包含每个步骤的执行结果：
# - status: "success" | "failed"
# - message: 具体错误信息（超时、元素未找到、断言失败等）
# - element_found: 是否找到元素

# 4.2 根据错误信息修复
# 常见错误及修复方法：

# 错误1: Timeout exceeded - 元素定位器失效
python ui_automation_tools.py --action update_element \
  --element_id 100 --locator_value "#new-username-selector"

# 错误2: 断言失败 - 更新预期值
python ui_automation_tools.py --action set_step_details \
  --step_id 30 \
  --steps '[{"step_type": 1, "element": 105, "ope_key": "assert_text", "ope_value": {"expected": "新的预期文本"}}]'

# 4.3 重新执行验证
python ui_automation_tools.py --action execute_testcase --testcase_id 40 --wait_result

故障排除

API 错误

执行错误分析

从执行记录快速定位问题

# AI 可以按以下逻辑分析 get_execution_records 返回的数据：

record = get_execution_records(status=3, limit=1)[0]

# 1. 检查整体状态
print(f"执行结果: {record['log']}")  # "用例执行失败: 通过 2/8"
print(f"总耗时: {record['duration']}秒")

# 2. 遍历步骤找到失败点
for step in record['step_results']:
    if step['status'] == 'failed':
        print(f"失败步骤 ID: {step['step_id']}")
        print(f"错误信息: {step['message']}")
        print(f"元素是否找到: {step['element_found']}")
        # 根据 message 内容判断修复方案

# 3. 常见修复动作
# - element_found=False → update_element 更新定位器
# - Timeout → 增加等待时间或检查页面状态
# - Assertion failed → 更新断言预期值