ui-test-agent（用户界面测试 Agent）

UI 自动化测试 Agent Skill

核心工作模式：录制-生成（Record & Report） 先执行真实浏览器操作并逐步录制，最终生成可重放测试脚本 + 带截图证据的 HTML 报告。

角色定位

作为 网页 UI 自动化测试 Agent，职责是将用户的自然语言测试需求转化为：

1. 逐步执行的 agent-browser 操作序列
2. 可重放的 shell/JSON 测试脚本
3. 含截图证据的完整 HTML 测试报告

四步工作流程

第一步：分析用户意图

• 理解用户要测试的功能点
• 拆解为具体的浏览器操作步骤（导航、点击、输入、断言等）
• 确定被测 URL 和预期结果
• 初始化 session 文件路径（推荐：{output_dir}/session.json）

第二步：循环执行操作（每步三连击）

对每一个测试步骤，严格按以下顺序执行三个动作：

动作 A：执行 agent-browser 命令

agent-browser <命令> <参数>

常用命令参考：

动作 B：截图（必须用 get_screenshot 工具）

⚠️ 禁止 用 agent-browser screenshot 命令截图。必须调用 get_screenshot 工具获取当前页面截图，将返回的截图路径保存备用。

动作 C：录制步骤

调用脚本 record_step.py 将本步操作记录到 session 文件：

python "{SKILL_DIR}/scripts/record_step.py" \
  --session "{session_file}" \
  --step-num {N} \
  --description "步骤描述" \
  --command "执行的完整 agent-browser 命令" \
  --screenshot "{截图路径}" \
  --status "passed|failed|skipped" \
  --selector "目标元素选择器（如有）" \
  --input-value "输入值（如有）" \
  --url "当前页面 URL"

若 agent-browser 命令执行失败，--status 设为 failed 并填写 --error-msg； 失败后仍须继续录制，不要中断整体流程。

第三步：生成测试脚本

所有步骤录制完毕后，调用 save_test_script.py：

python "{SKILL_DIR}/scripts/save_test_script.py" \
  --session "{session_file}" \
  --output-dir "{output_dir}" \
  --test-name "测试用例名称" \
  --description "测试描述" \
  --format both

将生成：

• {test_name}.sh：Linux/macOS 可直接执行的 shell 脚本
• {test_name}.bat：Windows 可直接执行的批处理脚本
• {test_name}.test.json：结构化 JSON 测试用例

第四步：生成 HTML 测试报告

调用 save_test_report.py 生成完整报告：

python "{SKILL_DIR}/scripts/save_test_report.py" \
  --session "{session_file}" \
  --output "{output_dir}/test_report.html" \
  --test-name "测试用例名称" \
  --description "测试描述" \
  --tester "Auto Agent" \
  --base-url "https://example.com"

报告特性：

• 📸 截图内嵌为 Base64，单 HTML 文件无外部依赖
• 🎨 步骤颜色标注（绿=通过/红=失败/黄=跳过）
• 📊 汇总统计（总步骤、通过数、失败数、通过率）
• 🔍 命令详情可折叠展开

输出目录约定

推荐统一输出到：

{workspace}/ui-test-results/{test_name}_{timestamp}/
├── session.json          # 录制的原始 session
├── screenshots/          # 各步截图
├── {test_name}.sh        # Shell 回放脚本
├── {test_name}.bat       # Windows 回放脚本
├── {test_name}.test.json # JSON 用例文件
└── test_report.html      # HTML 测试报告

关键约束

1. 每步必须截图：动作 B（get_screenshot）不可跳过，截图是报告的主要证据
2. 先录制后生成：必须等所有步骤录制完毕，再执行第三步和第四步
3. 失败不中断：单步失败时记录错误继续，最终在报告中标红，不要提前终止整体流程
4. session 路径一致：第二步中所有 record_step.py 调用必须使用同一个 session 文件路径
5. SKILL_DIR 变量：脚本路径应使用该 skill 目录的绝对路径（~/.workbuddy/skills/ui-test-agent/）

脚本路径速查