expect

Expect

在声称代码更改有效之前，请先在真实浏览器中验证。没有浏览器证据，就不能声称已完成。

所有浏览器交互都使用 expect MCP 工具（open、playwright、screenshot 等）。除非用户明确要求，否则不要使用原始浏览器工具（Playwright MCP、chrome 工具等）。

子 Agent 使用

最好在子 Agent（Task 工具）或后台 shell 中运行浏览器验证，以便主线程继续处理代码编辑。这样可以让对话保持响应，同时你也能并行修复代码。强烈建议启动子 Agent 执行浏览器操作，尤其是测试涉及多个步骤或耗时较长时。如果测试确实很简单（只需检查单张截图），可以在当前线程中执行。

恢复浏览器状态

打开新浏览器前，先检查是否已有浏览器在运行。使用 browser_tabs（操作 list）或 expect 的 screenshot 工具查看会话是否仍处于活动状态。如果目标 URL 已在某个标签页中打开，就复用该标签页，不要关闭后重新打开。修复代码后重新验证时，优先在现有会话中导航或刷新，而不是从头开始。

提高效率

playwright 工具接受包含 ref() 的 code 字符串，用于将快照引用解析为 Locator。一次调用即可完成整个交互流程，包括填充、点击和收集数据。

不推荐——5 次工具调用：

screenshot (snapshot)
playwright: await ref('e3').fill('Jane')
screenshot (snapshot)                        ← WHY? page didn't change
playwright: await ref('e5').fill('[email protected]')
playwright: await ref('e7').click()

推荐——2 次工具调用：

screenshot (snapshot)
playwright (snapshotAfter=true):
  await ref('e3').fill('Jane');
  await ref('e5').fill('[email protected]');
  await ref('e7').click();
  return { title: await page.title(), url: page.url(), errors: (await page.$$('.error')).length };

使用 return 收集数据。响应格式为 { result: <value>, resultFile: "<tmp path>", snapshot: { tree, refs, stats } }。resultFile 会一直保留到 close；之后可以读取或搜索它。如果没有返回值，响应会是 "OK"（或者在设置 snapshotAfter=true 时，仅返回快照）。

仅在跨越 DOM 边界时重新生成快照。填充和悬停不会改变页面结构，因此请继续使用相同的引用。导航、提交、打开或关闭对话框都会改变页面结构，请设置 snapshotAfter=true。

编写说明

不推荐： "检查 http://localhost:5173 上是否呈现登录表单" 推荐： "在 http://localhost:5173 上，分别提交空白登录表单、无效邮箱和错误密码，并使用有效凭据登录。验证错误消息、成功后的重定向以及控制台错误"

声称完成前

1. 使用对抗性指令在浏览器中验证。
2. 阅读完整输出，检查失败项、无障碍性和性能。
3. 如果有任何失败：修复代码并立即重新验证。不要询问，也不要等待。
4. 重复上述流程，直到失败数为 0；然后提供通过的证据并声称已完成。

常见借口

• “浏览器测试很快，我直接在当前线程中运行。”——可能没那么快。启动子 Agent，这样你就能并行编辑代码。只有只需检查单张截图时，才跳过子 Agent。
• “我会打开一个新浏览器重新测试。”——先检查是否已有会话。如果标签页仍处于打开状态，就刷新或导航，不要浪费时间从头开始。
• “每个操作都要单独调用一次 playwright。”——不要这样做。一次调用完成整个流程。
• “填充之间需要生成快照。”——不需要。填充不会改变 DOM。将这些操作批量处理。
• “我先生成快照，看看有什么变化。”——页面导航或提交了吗？如果没有，就在执行操作时设置 snapshotAfter=true。