browser-qa

浏览器 QA

你即将操控真实浏览器来验证一项功能。请使用 Playwright MCP。 这是唯一一种在实际使用中真正有用的浏览器技术栈——速度快、可脚本化、能感知快照，而且失败会在提示词层面显现，因此你可以通过更聪明的重试来恢复，而不必重启运行时。

首次设置 — 请务必在做任何事之前完成

如果等到需要权限时才申请，你就会在任务中途受阻。请在 QA 阶段的第一条消息中说明任何缺失项：

1. 确认 Playwright MCP 可用：调用一次 mcp__playwright__browser_close。如果没有打开的标签页，它不会执行任何操作；如果浏览器已被占用，也会尽早提示锁定错误，这样你就能在任务中途遇到问题之前运行 pkill -f "mcp-chrome-"。
2. 确认开发服务器正在运行。 快速运行 curl -s -o /dev/null -w "%{http_code}\n" http://localhost:<port>/，即可避免往返等待后只得到“Page Title: ECONNREFUSED”。

如果缺少任何条件，请立即说明——不要在毫无准备的情况下开始 QA。

为什么选择 Playwright？ 它速度快、可脚本化、能感知快照，而且失败会在提示词层面显现，因此你可以通过更聪明的重试来恢复，而不必重启运行时。无头模式的截图内容密集、风格简洁，这正是审核人员想要的效果。坚持使用一种技术栈，并熟悉它的特点。

Playwright MCP 故障模式——都可以由你自行修复

• 上一次会话遗留的浏览器锁。 执行 pkill -f "mcp-chrome-"，然后重试。
• 猜测 URL 路径导致 404。 导航前先查看项目的路由配置（Next.js pages//app/、Vite routes.tsx、React Router、基于文件的路由器等）。不要根据功能名称猜测 URL 模式。
• browser_take_screenshot 报错 “outside allowed roots”。 截图工具只能在其沙箱内写入文件——通常是 <cwd> 和 <cwd>/.playwright-mcp。你无法直接保存到 ~/Projects/pr-screenshots 或 /tmp。传入一个不带目录的文件名（例如 drawer-light.png），文件就会保存到工作树根目录；之后再从那里复制到 pr-screenshots 克隆目录。不要浪费时间搜索截图保存在哪里——它就在 <cwd>（如果使用了带斜杠的相对路径，则在其 .playwright-mcp 子目录中）。
• wait_for 对基于 portal 的组件等待文本不充分（Radix、Headless UI、Chakra v3、MUI Modal）。等待 portal 的内容（字段标签、对话框内的标题），而不是打开它的触发元素。
• 通过 evaluate 点击可见文本，通常不会触发正确的处理程序。 许多组件库（Chakra、Radix、shadcn/ui、MUI）会将点击处理程序绑定到内部元素（如 <button> 或图标触发器），而不是用户实际看到的行或列表项。沿 DOM 向上或向下查找实际的交互元素——通常是 <button> 或 [role="button"]——然后点击它。
• 通过 evaluate 设置的 Cookie 可能会在页面导航时丢失。 如果应用会重定向未认证的请求，请先导航到一个不会触发重定向的端点（静态资源、JSON API 路由，或任何返回 200 且不会跳转的端点），在那里设置 Cookie，然后再导航到目标页面。
• 无法通过写入 localStorage 并切换 class 来切换颜色模式（主题）。 主题提供程序（next-themes、Chakra ColorModeProvider 等）会在挂载时通过 React 读取状态——页面完成水合后直接切换 DOM，不会影响渲染树。你可以：
  • 通过 browser_click 点击主题切换按钮（最可靠），或
  • 在导航前设置存储键，然后重新加载——提供程序会在挂载时从存储中重新水合。 先截屏确认模式确实已更改，再作判断。
• 模态框／抽屉遮挡了切换按钮。 如果抽屉／对话框打开时你尝试点击 Chrome 控件，对话框背景层会拦截点击。操作全局 UI 前，先关闭对话框（按 Esc、点击 X，或调用 store 层级的关闭方法）。
• 不要轮询文件系统查找截图路径。 Playwright 的响应会确认 path: './<filename>.png'——这就是实际路径。如果你看不到该文件，说明当前工作目录不是你以为的位置（执行一次 pwd，不要搜索）。

性能预期

在实际的“设置 → 打开抽屉 → 截图”QA 流程中：

技术栈	顺利完成	观察到的最慢情况	故障模式
Playwright	~12 s	~60 s（调试）	提示词层，可重试

单次截图流程通常会进行 8–9 次工具调用。多状态截图（浅色 + 深色、窄屏 + 宽屏）很适合批量处理——调整视口、截图，然后重复。

QA 流程本身

1. 选择一个不会与其他 Agent 或硬编码的身份验证回调冲突的开发服务器端口。 如果项目使用外部身份验证提供商（Auth0、Clerk、搭配 OAuth 的 NextAuth、Supabase、Cognito 等），请选择一个已加入回调许可名单的端口——随意编一个端口会导致重定向静默失败。否则，选个不常用的端口（例如较高的四位数），避免与用户正在运行的其他服务冲突。
2. 通过脚本而不是 UI 填充测试数据。 编写一个简短的设置脚本，直接通过项目的 DB 客户端、ORM 或种子机制创建所需的行（用户、会话令牌、示例记录）。这比点击完成引导流程更快，可在多次运行中重复使用，而且任务中途会话过期也不受影响。
3. 导航 → wait_for 实际内容 → 点击 → wait_for 后续内容 → 截图。 始终等待用户实际能看到的内容，而不只是 document.readyState。
4. 在评审者关心的时刻截图——初始状态、流程中途、最终状态。对于 UI 改版：截取两种配色模式（浅色 + 深色）和两种布局断点（例如窄屏与宽屏）。通常 3 到 6 张就够了；十张就太多了。
5. 验证功能，然后验证异常路径。“正常流程可用”，并且“明显的错误情况会显示清晰的消息”，并且“表单验证会拒绝错误输入”。Bug 几乎总是出现在你没有做 QA 的路径上。
6. 在浏览器截图中亲眼看到功能正常前，不要声称功能可用。 测试通过是必要条件，但并非充分条件。

截图处理——强制要求

截图不是可选项。 每次 QA 都必须生成截图并上传到 PR。没有嵌入截图却标记为“已就绪”的 PR 并不完整——请返回补上截图。在 QA 期间就完成这项工作，不要事后补做。

• 不要将截图提交到工作仓库，除非它们明确属于面向用户的文档素材。将截图放在 .claude/、bench/ 或其他被 git 忽略的位置。（如果不小心执行了 git add -A，把截图纳入了提交，请在推送前 amend 掉。）
• 通过 langwatch/pr-screenshots 发布（克隆在 ~/Projects/pr-screenshots）：

  cd ~/Projects/pr-screenshots && git pull --rebase
  cp /path/to/shot.png pr-<PR#>/<section>/<name>.png
  git add . && git commit -m "pr-<PR#>: <what>" && git push origin main
  

  原始 URL 为 https://raw.githubusercontent.com/langwatch/pr-screenshots/main/pr-<PR#>/<section>/<name>.png。
• 在报告 PR 已就绪之前，将原始 URL 嵌入 PR 描述中。 不要作为已提交文件，也不要放在评论中——必须放在 PR 正文中。

结束 QA 阶段

如果以下各项都能回答“是”，浏览器 QA 就完成了：

• 我像用户一样完整走过了该功能，而不只是进入能证明代码路径运行的页面。
• 我尝试了异常路径（缺失配置、错误输入，以及相关时的网络故障模拟）。
• 我有正常流程和最重要边缘情况的截图。
• 对于 UI 工作：截图涵盖两种配色模式，以及（布局会自适应时）两种断点。
• 截图已推送到 langwatch/pr-screenshots 并嵌入 PR 正文中（不只是本地截图——现在就确实出现在 PR 描述中）。
• 我在 QA 期间至少发现了一个 UX 瑕疵，并已修复或登记。

如果不能对以上各项都回答“是”，说明你还没有完成 QA，只是做了冒烟测试。回去实际使用这个功能。

严格门槛： PR 中没有截图，就不要报告“所有 CI 均已通过，PR 已就绪”。先截图，再报告状态。