alan-test-feature

任务：测试功能并生成演示报告

分析当前分支的变更，与用户商定测试覆盖级别，制定明确的测试策略，启动应用的开发服务器，使用 agent-browser 在真实浏览器中测试功能、截取屏幕截图并录制视频（始终执行，无一例外），将所有内容上传到 S3，并生成结构化测试报告（始终执行，绝不跳过）。

---

阶段 0：环境设置

1. 获取制品上下文 ID

如果提示中包含当前任务上下文，请使用该上下文。否则：

• 任务 ID 可从 ALAN_TASK_ID 环境变量中获取。
• 会话 ID 可从 ALAN_SESSION_ID 环境变量中获取。
• 创建报告前，使用 Alan MCP 上下文/工具解析 teamId。

调用 create_test_report 时，始终显式传入 taskId、conversationId 和 teamId。不要用一个 ID 替代另一个。

2. 确认 agent-browser 可用

agent-browser 是 Vercel Labs 提供的 CLI 工具（npm: agent-browser），不是技能或 MCP 工具。它通过 bash 命令（打开、点击、填写、截图、录制）提供无头浏览器自动化。在沙盒中，runtime-bootstrap.ts 会预先安装它。

command -v agent-browser >/dev/null 2>&1 && echo "agent-browser: OK" || echo "agent-browser: MISSING"

如果未安装，请安装：

npm install -g agent-browser && agent-browser install

如果安装失败（例如没有网络或 npm），请停止并告知用户：

“agent-browser 不可用且无法安装。请手动安装：npm install -g agent-browser && agent-browser install”

没有可用的 agent-browser 时，不要继续到阶段 2——所有浏览器测试都依赖它。

3. 创建工作区

所有截取的内容（屏幕截图、视频）必须写入 /tmp/alan-captures/。

mkdir -p /tmp/alan-captures

关键——文件路径规则：

• 只能将截取的文件写入 /tmp/alan-captures/。绝不要写入其他位置。
• 绝不要写入 .claude/、项目目录、reports/ 或仓库中的任何路径。
• .claude/ 是敏感系统目录——写入该目录会被阻止，并导致测试运行中止。
• 如果你想在 /tmp/ 以外的任何位置创建 reports/ 或 screenshots/ 文件夹，请停下并改用 /tmp/alan-captures/。

---

阶段 0.5：确定覆盖范围并收集上下文（必做——必须先于其他操作）

绝不要跳过此阶段。 在编写任何测试步骤之前，必须先了解用户的需求。

1. 询问覆盖级别

使用 AskUserQuestion 询问用户：

What level of test coverage do you want for this feature?

- light       — Happy path only. Quick smoke test to verify the main flow works.
- standard    — Happy path + key edge cases + basic error states. (Default)
- comprehensive — Full coverage: happy path, all edge cases, error states, non-happy paths, boundary values, accessibility, responsiveness.

Also: are there any specific flows, known bugs, or risky areas you want me to focus on?

等待用户回复后再继续。

2. 提出有针对性的后续问题

根据功能内容（你可能还不了解——先快速运行 git diff --stat 以获取线索），使用 AskUserQuestion 提出 1–3 个有针对性的后续问题。示例：

• “是否有需要测试的已认证状态？如果有，我应该使用哪些测试凭据？”
• “此功能是否存在已知边缘情况或过去出现过的错误？”
• “此功能‘正常工作’的标准是什么——我应该看到什么？”
• “你是否特别关注某些非正常路径（例如无效输入、网络错误、空状态）？”
• “有哪些页面或用户角色需要特别纳入或排除？”

如果上下文不清楚，不要跳过提问。请提出问题。范围明确的测试比盲目测试有价值得多。

3. 确认计划

收集答案后，向用户简要总结（无需调用工具，直接发送一条简短消息即可）：

• 选择的覆盖级别
• 要重点测试的具体区域/流程
• 要针对的已知风险或边缘情况
• 预计测试场景的大致数量

只有在确认计划后，才能继续到阶段 1。

---

阶段 1：确定测试内容

1. 分析分支

运行以下命令，了解变更内容：

git log main..HEAD --oneline 2>/dev/null || git log HEAD~5..HEAD --oneline
git diff main...HEAD --stat 2>/dev/null || git diff HEAD~1 --stat

阅读实际差异，了解功能或错误修复。确定：

• 受影响的应用部分（涉及哪些页面、组件、API 路由）
• 预期的行为变化
• 测试时要导航到的 URL 路径

2. 发现并启动开发服务器

查看项目，了解如何运行：

1. 阅读 package.json——检查 scripts.dev、scripts.start、scripts.serve
2. 检查是否存在 docker-compose.yml / docker-compose.yaml / compose.yml
3. 检查是否存在 Makefile（查找 dev 或 serve 目标）
4. 检查是否存在 Procfile、.env、Pipfile、requirements.txt、Gemfile
5. 检查特定框架的文件：next.config.*、vite.config.*、nuxt.config.*、angular.json、manage.py、config/routes.rb

在后台启动开发服务器。常见模式：

# Node.js
npm run dev &
# or: pnpm dev &, yarn dev &, npx next dev &, npx vite &

# Python
python manage.py runserver &
# or: flask run &, uvicorn main:app &

# Ruby
bundle exec rails server &

# Docker
docker compose up -d

3. 等待服务器

轮询，直到服务器开始响应：

# Replace PORT with the discovered port
for i in $(seq 1 30); do
  curl -sf http://localhost:PORT >/dev/null 2>&1 && break
  sleep 2
done

如果不确定，请检查常见端口：3000、5173、8080、4200、8000、4000、3001、8888。

4. 确定应用 URL

• 解析开发服务器的 stdout/stderr，查找包含 URL 的 "Local:" 或 "ready on" 消息
• 检查 .env 或 .env.local 中的 PORT、VITE_PORT 或类似变量
• 使用 curl -sf http://localhost:PORT >/dev/null 测试常见端口
• 如果无法确定，请通过 AskUserQuestion 询问用户

5. 继续之前先总结

告知用户：

• 你在 diff 中发现了什么（功能/修复摘要）
• 你将测试哪个 URL
• 你计划覆盖哪些测试场景

---

第 1.5 阶段：制定测试策略并创建待办事项（必须）

打开浏览器之前，必须制定明确的计划。不要临时即兴安排测试步骤。

1. 起草测试策略

依据：

• 用户在第 0.5 阶段选择的覆盖级别
• 第 1 阶段的 diff 分析
• 从用户处收集的上下文

将完整测试计划写成结构化列表。对于每个场景，注明：

• 场景名称——简短标签（例如“正常流程：创建项目”）
• 类型——正常流程 / 异常流程 / 边界情况 / 错误状态 / 视觉 / 导航
• 步骤——要执行的操作
• 预期结果——通过时应呈现的结果
• 是否需要截图——是/否

各覆盖级别的要求：

• light：仅正常流程（1–3 个场景）
• standard：正常流程 + 2–4 个异常流程 + 1–2 个错误状态
• comprehensive：正常流程 + 所有异常流程 + 所有错误状态 + 边界值 + 空状态 + 响应式布局 + 导航

可考虑的异常流程示例：

• 无效/缺少必填输入
• 不输入数据就提交/空状态
• 重复条目（如适用）
• 权限被拒绝/未授权访问
• 网络错误/API 故障模拟（如可测试）
• 快速重复操作（双击、连续提交）
• 长输入字符串/特殊字符
• 流程进行中点击返回按钮/浏览器导航

2. 为每个场景创建待办事项

使用 TodoWrite 为每个测试场景创建一条待办事项，以跟踪进度。每条待办事项应使用场景名称。

3. 呈现策略

继续之前，以编号列表的形式输出完整测试策略。用户应能在第 2 阶段开始前准确看到将要测试的内容。

---

第 2 阶段：使用 agent-browser 进行测试

agent-browser 是一个 CLI 工具——通过 bash 调用，不要将其作为 MCP 工具或技能使用。 文档：https://github.com/vercel-labs/agent-browser 主要命令：open、snapshot、click、fill、screenshot、record、wait、find、close

1. 打开应用

agent-browser --session test-feature open http://localhost:PORT
agent-browser --session test-feature wait --load networkidle

2. 开始录制视频——必须

任何交互之前都必须先开始录制视频。不得例外。

agent-browser --session test-feature record start /tmp/alan-captures/happy-path.webm

如果视频录制因技术原因失败，请注明失败情况，但仍需继续——截图仍然必不可少。

3. 截取初始页面截图——必须

任何交互之前都必须先捕获页面的初始状态。

agent-browser --session test-feature screenshot /tmp/alan-captures/step-00-initial-state.png

4. 执行测试策略中的每个场景

逐一执行 Phase 1.5 中定义的所有场景。对于每个场景：

• 将对应的待办标记为进行中
• 使用 agent-browser snapshot -i 查找可交互元素
• 使用 agent-browser click @eN、agent-browser fill @eN "text" 等命令进行交互
• 在操作之间使用 agent-browser wait --load networkidle 或 agent-browser wait 1500
• 每次重要状态变化后都要截图——重要操作最多不能超过 2 次才截图：

  agent-browser --session test-feature screenshot /tmp/alan-captures/step-NN-description.png
  

  为截图使用描述性名称：step-02-form-filled.png、step-03-submit-clicked.png、step-04-success-state.png
• 导航或 DOM 发生变化后重新执行快照（引用会失效）
• 如果难以通过引用找到元素，请使用语义定位器：

  agent-browser --session test-feature find text "Submit" click
  agent-browser --session test-feature find role button click --name "Save"
  

• 根据执行结果，将每项待办标记为已完成或失败

强制覆盖检查清单（执行所选覆盖级别适用的所有项目）：

正常路径（始终必需）：

• 主要功能流程按预期端到端运行
• 成功状态／确认信息清晰可见
• 操作后数据已正确持久化／反映

异常路径（标准和全面覆盖均必需）：

• 必填输入为空／缺失——触发表单验证，并显示错误消息
• 输入值无效——正确拒绝，且不发生崩溃
• 边界值——最小和最大可接受值
• 重复／冲突数据（如适用）
• 未授权／权限被拒绝状态（如适用）
• 空列表／零状态视图（如适用）
• 快速重复操作（双击提交、连续点击按钮）
• 文本输入中的长字符串／特殊字符

错误状态（标准和全面覆盖均必需）：

• API／网络故障时的行为（如可模拟）
• 部分失败——仅部分操作成功时会发生什么
• 优雅降级——应用不会崩溃，用户能看到有意义的提示

视觉和导航（全面覆盖必需）：

• 布局正确，没有溢出或界面损坏
• 在较窄的视口下响应正常（如可调整大小）
• 链接和导航正常；返回按钮不会破坏状态
• 异步操作进行期间显示加载状态／旋转指示器

5. 停止录制并清理

agent-browser --session test-feature record stop
agent-browser --session test-feature screenshot /tmp/alan-captures/final-state.png
agent-browser --session test-feature close

录制时长保持在 2 分钟以内。 如果该功能需要进一步探索，请拆分为多个录制文件（例如 happy-path.webm、error-states.webm）。

6. 修复 WebM 时长元数据（如果 ffmpeg 可用则必须执行）

agent-browser 录制的 WebM 文件通常在容器头部将 duration 设为 Infinity——视频播放器随后会显示 0:00。通过 ffmpeg 重新封装每个 .webm 文件即可修复；ffmpeg 会读取整个文件、计算实际时长，并将其写入输出文件头部：

for f in /tmp/alan-captures/*.webm; do
  if command -v ffmpeg >/dev/null 2>&1; then
    ffmpeg -y -i "$f" -c copy "${f%.webm}-fixed.webm" 2>/dev/null \
      && mv "${f%.webm}-fixed.webm" "$f" \
      || echo "ffmpeg remux failed for $f — uploading as-is"
  fi
done

如果 ffmpeg 不可用，请跳过此步骤并继续——视频仍可播放，只是播放器不会显示正确时长。

---

第 3 阶段：将捕获内容上传到 S3

对于每个捕获的文件，使用 mcp__alan__get_upload_url MCP 工具获取预签名 S3 URL，然后通过 curl PUT 将文件直接上传到 S3。

单文件上传流程

1. 获取文件大小（MCP 工具需要此信息）：

   SIZE=$(stat -c%s "/tmp/alan-captures/step-01.png" 2>/dev/null || stat -f%z "/tmp/alan-captures/step-01.png")
   

2. 调用 MCP 工具获取预签名上传 URL：

   Tool: mcp__alan__get_upload_url
   Parameters: {
     "taskId": "<active task ID or value of ALAN_TASK_ID>",
     "filename": "step-01.png",
     "mimeType": "image/png",
     "size": <SIZE from step 1>
   }
   

   返回：{ "uploadUrl": "https://...", "s3Key": "sandbox-captures/..." }

3. 使用预签名 URL将文件上传到 S3：

   curl -sf -X PUT "<uploadUrl>" \
     -H "Content-Type: image/png" \
     --data-binary @/tmp/alan-captures/step-01.png
   

4. 保存 s3Key——你将在第 4 阶段将其传递给 create_test_report。

对每张截图和每个视频文件重复此流程。常见 MIME 类型：

• 截图：image/png
• 视频录制：video/webm

如果上传失败：仍然继续第 4 阶段——省略 screenshotUrl、videoUrl 和 screenshotUrls 字段。即使没有媒体文件，结构化报告仍然很有价值。

---

阶段 4：创建结构化测试报告（强制 — 绝不可跳过）

重要：必须调用 mcp__alan__create_test_report 才能完成此技能。这一点不容商量。

• 不要以 Markdown 文本形式输出报告
• 不要只在聊天中总结发现
• 无论任何原因都不要跳过此阶段——不能因为时间不足、上传失败或测试只完成了一部分而跳过
• 必须通过调用此 MCP 工具持久化报告，以便 UI 将其呈现为交互式产物
• 跳过此步骤意味着整个测试会话白费且未被记录

如果阶段 3 中上传失败，也要创建报告——省略媒体 URL，但包含所有步骤、问题和摘要文本。

调用 mcp__alan__create_test_report MCP 工具，并提供测试中的结构化数据。

收集前面各阶段的所有数据，然后调用此工具：

Tool: mcp__alan__create_test_report
Parameters: {
  "title": "<short description of what was tested>",
  "taskId": "<active task ID or value of ALAN_TASK_ID, if set>",
  "conversationId": "<active conversation ID or value of ALAN_SESSION_ID>",
  "teamId": "<resolved team ID>",
  "branch": "<current branch name from git>",
  "baseBranch": "main",
  "commits": [
    { "sha": "<commit sha>", "message": "<commit message>" }
  ],
  "changedFiles": [
    { "path": "src/components/Feature.tsx", "description": "Added new feature component" }
  ],
  "appUrl": "<the URL you tested>",
  "summary": "<1-2 paragraph summary of what was tested and the outcome>",
  "status": "pass | fail | mixed",
  "steps": [
    {
      "name": "Navigate to feature page",
      "status": "pass | fail | skip",
      "screenshotUrl": "<s3Key from Phase 3 — e.g. sandbox-captures/org/task/step-01.png — omit if upload failed>",
      "notes": "Page loaded correctly"
    }
  ],
  "issues": [
    {
      "title": "Button misaligned on mobile",
      "severity": "critical | high | medium | low",
      "description": "The submit button overflows on viewports < 375px",
      "screenshotUrl": "<s3Key from Phase 3 showing the issue — omit if upload failed>"
    }
  ],
  "videoUrl": "<s3Key from Phase 3 for the happy-path recording — omit if upload failed>",
  "screenshotUrls": ["<s3Key 1 from Phase 3>", "<s3Key 2 from Phase 3>"]
}

字段说明

• status：如果所有步骤都通过，则为 "pass"；如果任何关键步骤失败，则为 "fail"；如果部分通过、部分失败，则为 "mixed"
• steps：每个不同的测试操作（导航、点击、填写、验证）各占一条。如果为该步骤截取了屏幕截图，请包含其 URL。
• issues：仅包含实际发现的问题。每个问题都应包含严重程度和清晰的描述。
• screenshotUrls：阶段 3 中所有截图 s3Keys 的列表（用于图库展示）。使用 get_upload_url 返回的 s3Key 字段，不要使用 uploadUrl。如果没有成功上传，则省略此字段。
• commits 和 changedFiles：来自阶段 1 的 git 分析

输出

调用 mcp__alan__create_test_report 后，告知用户：

• 测试报告标题，方便用户在 Alan UI 中找到生成的产物
• 在上下文足以构造链接时，提供产物链接（通常为 /teams/<teamId>/docs?artifactId=<artifactId>）
• 简要总结：测试了什么、通过/失败的步骤数量，以及发现的问题
• 列出测试中发现的任何错误或值得关注的问题

不要以原始 UUID 开头。只有在没有可用标题或链接时，才将产物/报告 ID 作为次要调试信息提供。

不要以 Markdown 形式呈现完整报告。MCP 工具调用会创建结构化产物，由 UI 以交互方式展示。