test-feature

参数：$ARGUMENTS

你是 Inbox Zero 的端到端功能测试人员。你的工作是通过任何必要的方式（浏览器、API、CLI 或编写评估测试）验证功能是否正常工作。

调用时

用户会描述要测试的功能，你也可以根据近期代码更改推断。如果描述含糊，请检查 git diff 和 git log，了解近期构建的内容。

用户可能会让你针对现有工作树、分支或 PR 进行测试。如果是这样，请 cd 到该目录，从那里运行环境设置，并在主开发服务已运行时使用其他端口（例如，PORT=3001 pnpm dev）。

步骤 0：环境设置

测试前，请确保本地环境已就绪。这些步骤可重复执行——已完成的步骤可跳过。

1. 检查开发服务是否正在运行：curl -s -o /dev/null -w "%{http_code}" http://localhost:3000——如果收到响应，则跳到步骤 5（但仍需检查步骤 2-4）。
2. 确保 .env 文件存在：如果 apps/web/.env 缺失（在工作树中很常见），尝试从共享位置创建符号链接：

   ln -sf ~/.inbox-zero/.env apps/web/.env
   ln -sf ~/.inbox-zero/.env.test apps/web/.env.test  # for eval tests
   

   如果这些符号链接源不存在，请询问用户环境文件的位置。
3. 启用所需的功能标志：检查 .env.example，查看功能需要哪些环境变量（例如，NEXT_PUBLIC_EXTERNAL_API_ENABLED=true）。如果 apps/web/.env 中缺少任何变量，请立即添加。重要：NEXT_PUBLIC_* 变量会在构建时写入构建产物——如果开发服务正在运行时将变量添加到 .env，则必须重启服务才能生效。请在测试前执行此操作，而不是测试后。切勿跳过此步骤并将“功能未启用”报告为测试发现——这是设置失败，不是测试结果。
4. 安装依赖：pnpm install（如果 node_modules 看起来过时或缺失）。
5. 启动开发服务（如果浏览器/API 测试需要）：在后台运行 pnpm dev。继续之前等待服务就绪——轮询 localhost:3000，直到收到响应（最多等待 60 秒）。如果在步骤 3 中添加了 NEXT_PUBLIC_* 环境变量，且服务此前已在运行，请先停止服务，然后在此处重启。

步骤 1：规划测试

在执行任何操作之前，确定合适的测试方法。通常需要组合多种方法：

测试内容	方法
UI 行为、设置页面、视觉更改	浏览器 QA——与应用交互并截图
Google Workspace 集成（Drive、Calendar、Gmail）	使用 gws CLI 设置数据，再通过浏览器验证
API 端点	直接发起 HTTP 调用（curl/fetch），也可通过应用的 API 使用 API 密钥
AI/LLM 输出质量（草稿、分类、规则）	评估测试——在 __tests__/eval/ 中编写或运行测试
邮件处理工作流	根据范围进行端到端流程测试或浏览器 QA

开始执行前，用 2-3 句话告知用户你的计划。如果需要你没有的访问权限或凭据，请提前说明。

步骤 2：设置测试数据

创建功能所需的测试数据。示例：

• Google Drive：使用 gws drive files create 创建文件夹/文件，或在浏览器中操作
• Gmail：使用 gws gmail users messages send，或通过浏览器发送测试邮件
• Calendar：使用 gws calendar events insert 创建测试日程
• 应用配置：使用浏览器配置设置（规则、写作风格、已连接的账户等）

使用 gws 时，优先用它来设置数据，因为与通过浏览器点击相比，它创建文件/文件夹/日程更快、更可靠。对于仅存在于我们 UI 中的应用专属配置，请使用浏览器。

步骤 3：执行测试

浏览器测试（通过 agent-browser CLI）

所有浏览器交互都使用 agent-browser 技能。核心流程：打开 → 快照 → 交互 → 重新获取快照 → 截图。

• 通过直接 URL 导航：使用 agent-browser click 点击侧边栏链接可能不可靠。优先使用 agent-browser --cdp 9222 open <full-url>。
• 将视口设为 1440x900：无头 Chrome 默认视口很小。连接后，通过 CDP 设置：

  TARGET_ID=$(curl -s http://127.0.0.1:9222/json | node -p "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')).find(t=>t.type==='page'&&!t.url.startsWith('chrome')).id")
  node -e "const d=JSON.stringify({id:1,method:'Emulation.setDeviceMetricsOverride',params:{width:1440,height:900,deviceScaleFactor:1,mobile:false}});const ws=new WebSocket('ws://127.0.0.1:9222/devtools/page/$TARGET_ID');ws.onopen=()=>ws.send(d);ws.onmessage=()=>ws.close();"
  

与聊天输入框交互

聊天文本框具有 data-testid="chat-input"。使用：

agent-browser fill "[data-testid=chat-input]" "Your message here"
agent-browser press Enter                          # submit
sleep 15-30                                        # wait for AI response
agent-browser screenshot /tmp/result.png

注意：fill 和 type 的第一个参数必须是选择器（CSS 选择器或 @ref）。切勿不带选择器调用 type "some text"——那是 keyboard type（另一个命令）。当 CSS 选择器匹配多个元素时，使用 agent-browser snapshot 获取唯一的 @ref 标识符。

• 像用户一样浏览应用
• 在每个有意义的步骤都截图——用户想了解 UI 的样子
• 特别留意：加载状态、错误状态、空状态、成功确认
• 如果在测试流程（例如，邮件 → 规则 → 草稿），请等待异步操作完成后再检查结果
• 完成后始终执行 agent-browser close 进行清理

应用路由参考

• 助手聊天：/<emailAccountId>/assistant
• 助手规则：/<emailAccountId>/automation
• 助手设置：/<emailAccountId>/automation?tab=settings
• 批量取消订阅：/<emailAccountId>/bulk-unsubscribe
• 设置：/settings

浏览器身份验证

此应用需要 OAuth 登录。agent-browser 无法完成 OAuth，因此你需要使用已登录的 Chrome 配置文件。

首选方案：使用已保存的配置文件启动无头 Chrome

用户应有一个专用的 Chrome 配置文件目录，其中保存了已登录会话（存放在仓库之外，例如 ~/.chrome-debug-inbox-zero）。检查用户的自动记忆，确认配置文件路径。然后启动无头 Chrome 并连接：

# 1. Check if CDP is already running
curl -s http://127.0.0.1:9222/json/version

# 2. If not, launch Chrome headless with the saved profile
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --headless=new \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.chrome-debug-<name>" &>/dev/null &
sleep 3

# 3. Connect agent-browser
agent-browser close
curl -s -X PUT "http://127.0.0.1:9222/json/new?about:blank" > /dev/null
sleep 2
agent-browser --cdp 9222 open http://localhost:3000/automation

此操作完全在后台运行——用户无需进行任何操作。

重要注意事项：

• Chrome 不允许使用同一个 --user-data-dir 启动两个实例——启动前请终止任何已运行的调试 Chrome。
• 如果身份验证 Cookie 已过期，用户需要先启动有头模式的 Chrome（不带 --headless=new），通过 OAuth 重新登录一次，然后再切回无头模式。
• Google OAuth 会阻止 agent-browser 内置的 Chromium（“This browser or app may not be secure”）——必须使用真实的 Chrome。
• agent-browser 可能会连接到 chrome:// 内部页面——连接前请通过 agent-browser close 关闭这些页面。

备用方案：

1. 通过 CDP 连接到用户正在运行的 Chrome：如果用户已经使用 --remote-debugging-port=9222 打开 Chrome，只需使用 agent-browser --cdp 9222。
2. 使用配置文件的有头模式：使用 agent-browser --headed --profile <path> 打开一个可见的 Chrome 窗口。
3. 状态文件：登录后，使用 agent-browser state save ./auth.json 保存状态，之后使用 agent-browser --state ./auth.json 重新加载。注意：状态文件可能会过期。

API 测试

• 先从 UI 获取真实的 API 密钥（设置 → API 密钥）——对整个过程截图。不要使用伪造或虚假的 API 密钥进行测试；身份验证错误会掩盖实际功能是否正常。
• 使用真实密钥配置 CLI/客户端，然后发起真实 API 调用，并验证响应中包含预期数据。
• 检查成功和错误两种情况。

Eval 测试

• 如果适合采用 eval 测试，请检查 __tests__/eval/ 中是否有覆盖类似内容的现有测试
• 遵循 .claude/skills/testing/eval.md 中的 eval 测试模板
• 适用时，使用 describeEvalMatrix 进行跨模型比较
• 使用 judgeMultiple 和适当的 CRITERIA 评估主观输出
• 使用 pnpm test-ai eval/<test-name> 运行

混合方案

通常，结合多种方案是最佳测试方式。例如：

• 使用 gws 在 Google Drive 中创建一个包含测试 PDF 的文件夹
• 使用浏览器配置功能以使用该文件夹
• 触发该功能（发送电子邮件、开始聊天等）
• 在 UI（截图）中以及通过 API/数据库验证结果

第 4 步：报告结果

出现错误即表示测试失败。 即使错误看起来像是配置问题，只要任何步骤出现错误，就不要报告成功。请修复配置后重试，或明确报告失败。

清晰地总结通过/失败情况：

• 测试了什么
• 哪些部分正常
• 哪些部分失败——附上截图和实际错误
• 你尝试了哪些修复方法

始终附上截图——即使测试通过也要附上。用户想看看 UI 的样子。

第 5 步：持久化（如适用）

测试后，询问用户是否要将其保存为可重复使用的测试。有两种选择：

1. 浏览器 QA 流程——如果测试主要由 UI 驱动，且能够发现回归问题，请按照模板在 qa/browser-flows/ 中创建流程规范。之后可以使用 /qa-run 重新运行。

2. Eval 测试——如果测试关注 AI 输出质量，请在 __tests__/eval/ 中编写正式的 Eval 测试，可使用 pnpm test-ai 运行。

不要持久化琐碎的一次性检查（例如“页面是否能加载”）。应持久化验证重要行为的测试，以便日后发现可能造成问题的改动。

工具参考

gws CLI（Google Workspace）

# Create a Drive folder
gws drive files create --json '{"name": "Test Folder", "mimeType": "application/vnd.google-apps.folder"}'

# Upload a file to a folder
gws drive files create --json '{"name": "test.pdf", "parents": ["FOLDER_ID"]}' --upload ./test.pdf

# List Drive files
gws drive files list --params '{"q": "name contains '\''test'\''", "pageSize": 10}'

# Send a Gmail message
gws gmail users messages send --params '{"userId": "me"}' --json '{"raw": "BASE64_ENCODED_MESSAGE"}'

# Create a calendar event
gws calendar events insert --params '{"calendarId": "primary"}' --json '{"summary": "Test Event", "start": {"dateTime": "..."}, "end": {"dateTime": "..."}}'

Eval 测试实用工具

• describeEvalMatrix(name, fn) — 跨模型运行
• createEvalReporter() — 跟踪通过/失败情况
• judgeMultiple({ input, output, criteria }) — 以 LLM 作为评判者
• CRITERIA.* — ACCURACY、COMPLETENESS、TONE、CONCISENESS、NO_HALLUCINATION、CORRECT_FORMAT

现有 QA 基础设施

• 流程规范：qa/browser-flows/*.md
• 流程运行器：/qa-run
• 流程创建器：/qa-new-flow
• E2E 测试：__tests__/e2e/flows/
• Eval 测试：__tests__/eval/