ui-automation

name ui-automation description WHartTest UI 自动化管理工具。用于创建、编辑、删除 UI 测试模块、页面、元素、页面步骤和测试用例。支持执行记录查询和错误分析。当需要将浏览器技能获取到的页面元素保存到平台、创建 UI 自动化用例、执行测试或分析执行结果时使用。元素采集默认优先 browser-use，无法覆盖时再用 playwright-skill 兜底。 WHartTest UI 自动化管理 生命周期概览 ┌─────────────────────────────────────────────────────────────────┐ │ UI 自动化完整生命周期 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. 设计阶段 2. 构建阶段 3. 执行阶段 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 查询模块 │ │ 查询页面 │ │ 执行用例 │ │ │ │ (是否存在)│ │ (是否存在)│ │ (运行) │ │ │ └────┬─────┘ └────┬─────┘ └──────────┘ │ │ │ 不存在则创建 │ 不存在则创建 │ │ │ ↓ ↓ ↓ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ 创建/复用 │ │ 添加元素 │ │ 查看记录 │ │ │ │ 模块/环境 │ │ (定位器) │ │ (状态) │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ │ │ ↓ ↓ │ │ ┌──────────┐ ┌──────────┐ │ │ │ 创建步骤 │ │ 分析错误 │ │ │ │ (操作) │ │ (定位) │ │ │ └──────────┘ └──────────┘ │ │ │ │ │ │ ↓ ↓ │ │ ┌──────────┐ ┌──────────┐ │ │ │ 组装用例 │←────────│ 修复重试 │ │ │ │ (P0-P3) │ │ (迭代) │ │ │ └──────────┘ └──────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ 阶段说明 阶段 操作 说明 设计 get_ui_modules → create_ui_module (可选) → get_env_configs → create_env_config (可选) 先查询现有资源，按需创建 构建 get_ui_pages → create_ui_page → create_element → create_page_step → create_testcase 先查后建，逐层构建 执行 get_testcase_execute_data → 执行 → get_execution_records → 分析修复 执行并迭代优化 重要原则：先查后建 创建任何资源前，必须先使用对应的 get_* 操作查询是否已存在 如果已存在合适的资源，直接使用其 ID，避免重复创建 快速开始 # 执行操作 python ui_automation_tools.py --action <action_name> [--参数名 参数值] 元素采集策略（强制） 技术路线优先级 默认使用 browser-use 进行页面访问、元素抓取与识别（CDP / 可访问性树）。 仅当 browser-use 无法稳定获取目标元素时，才使用 playwright-skill 兜底。 ui-automation-skill 负责将已确认的元素表达式入库并组装步骤/用例。 元素表达式质量标准（必须满足） 唯一性：元素表达式在当前目标页面必须唯一匹配（期望匹配数为 1 ）。 客观性：优先依赖页面客观稳定属性，不依赖主观描述和截图猜测。 可维护性：优先选择改版后仍相对稳定的属性组合，避免脆弱路径。 简约性：在满足唯一性的前提下，表达式尽量短且语义清晰。 推荐的定位优先级 test_id / data-testid / 业务稳定 id role + name （可访问性语义） name / label / placeholder （稳定时） css （稳定属性组合） xpath （仅在上面都不适用时） 反模式（避免） 纯索引路径：如 :nth-child() 深层链、绝对 XPath（ /html/body/... ） 易变 class：构建产物 hash class、运行时动态 class 易变文本：时间戳、数量、用户名、随机文案 与 browser-use / playwright-skill 协作流程 browser-use playwright-skill ui-automation-skill │ │ │ │ 1. 默认：CDP/可访问性树抓取元素 │ │ ├─────────────────────────────┼─────────────────────────────────→│ 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": 页面结构变化，需重新获取元素（先 browser-use，再 playwright 兜底） # - "Target page closed": 前序步骤导致页面关闭 # 4. 更新元素定位器 python ui_automation_tools.py --action update_element --element_id < id > --locator_value "<新选择器>" 可用操作 模块管理 Action 描述 必填参数 可选参数 get_ui_modules 获取 UI 模块树 --project_id - create_ui_module 创建模块 --project_id , --name --parent_id update_ui_module 更新模块 --module_id , --name - delete_ui_module 删除模块 --module_id - 页面管理 Action 描述 必填参数 可选参数 get_ui_pages 获取页面列表 --project_id --module_id get_ui_page 获取页面详情（含元素） --page_id - create_ui_page 创建页面 --project_id , --module_id , --name --url , --description update_ui_page 更新页面 --page_id --name , --url , --description delete_ui_page 删除页面 --page_id - 元素管理 Action 描述 必填参数 可选参数 get_elements 获取页面元素列表 --page_id - create_element 创建元素 --page_id , --name , --locator_type , --locator_value --locator_type_2 , --locator_value_2 , --wait_time , --description update_element 更新元素 --element_id --name , --locator_type , --locator_value , 等 delete_element 删除元素 --element_id - batch_create_elements 批量创建元素 --page_id , --elements (JSON) - 定位类型（locator_type）可选值： css - CSS 选择器 xpath - XPath text - 文本 role - Role label - Label placeholder - Placeholder test_id - Test ID id - ID name - Name 页面步骤管理 Action 描述 必填参数 可选参数 get_page_steps 获取页面步骤列表 --project_id --page_id , --module_id get_page_step 获取页面步骤详情 --step_id - create_page_step 创建页面步骤 --project_id , --page_id , --module_id , --name --description update_page_step 更新页面步骤 --step_id --name , --description delete_page_step 删除页面步骤 --step_id - set_step_details 设置步骤详情（批量） --step_id , --steps (JSON) - 步骤类型（step_type）可选值： 0 - 元素操作 1 - 断言操作 2 - SQL 操作 3 - 自定义变量 4 - 条件判断 5 - Python 代码 测试用例管理 Action 描述 必填参数 可选参数 get_testcases 获取用例列表（精简版） --project_id --module_id , --level , --limit (默认50) get_testcase 获取用例详情 --testcase_id - create_testcase 创建测试用例 --project_id , --module_id , --name --description , --level update_testcase 更新测试用例 --testcase_id --name , --description , --level delete_testcase 删除测试用例 --testcase_id - set_case_steps 设置用例步骤（批量） --testcase_id , --page_step_ids (逗号分隔) - 用例等级（level）可选值： P0 , P1 , P2 , P3 注意： get_testcases 返回精简数据（id, name, level, status 等），详情请使用 get_testcase 公共数据管理 Action 描述 必填参数 可选参数 get_public_data 获取公共数据列表 --project_id - create_public_data 创建公共数据 --project_id , --key , --value --type , --description update_public_data 更新公共数据 --data_id --key , --value , --is_enabled delete_public_data 删除公共数据 --data_id - 执行记录管理 Action 描述 必填参数 可选参数 get_execution_records 获取执行记录列表 - --testcase_id , --status , --limit get_execution_record 获取执行记录详情 --record_id - get_execution_trace 获取 Trace 数据 --record_id --refresh delete_execution_record 删除执行记录 --record_id - 执行状态（status）可选值： 0 - 未执行 1 - 执行中 2 - 成功 3 - 失败 4 - 取消 批量执行记录管理 Action 描述 必填参数 可选参数 get_batch_records 获取批量执行记录列表 - --status , --limit get_batch_record 获取批量执行记录详情 --batch_id - delete_batch_record 删除批量执行记录 --batch_id - 环境配置管理 Action 描述 必填参数 可选参数 get_env_configs 获取环境配置列表 --project_id -