recording-browser-flow-as-test

将浏览器操作流程录制为 Playwright 测试

将 browser MCP 用作录制器：每次导航、点击、填写和按键操作都会成为脚本中的一行。随后，Agent 会将这段操作轨迹转换为仓库中的 Playwright 测试文件（或可粘贴到现有 spec 中的代码片段）。

这是原生适用于 Cursor 的方式，因为它将 browser_snapshot（refs + 角色 + 名称）与结构化操作结合起来，而不是使用单独的录制器扩展。

前提条件

• 目标应用可访问（例如，开发服务器正在运行）；如有需要，请使用 finding-dev-server-url。
• 仓库已安装或将安装 Playwright（@playwright/test）。如果没有，请使用 adding-e2e-tests 或项目的标准设置进行安装。

录制工作流

1. 定义流程

用一句话说明范围，例如：“登录，打开 Settings，切换深色模式，然后保存。”

2. 按顺序执行每个步骤

1. browser_snapshot — 获取无障碍树和元素 refs。

2. 选择最小化交互：

   • 使用快照中的 ref 调用 browser_click（除非必要，否则不要使用坐标点击）。
   • 对输入框使用 browser_fill 或 browser_type。
   • 对下拉选择框使用 browser_select_option。
   • 对完整 URL 变更使用 browser_navigate。

3. 在主 Agent 维护的结构化列表中记录步骤：

   • 步骤编号
   • 操作动词（navigate、click、fill、press、select）
   • Playwright 定位器策略 — 优先使用：
     • getByRole('button', { name: '...' })
     • getByLabel('...')
     • getByPlaceholder('...')
     • 如果应用使用测试 ID，则使用 getByTestId('...')
   • 值（用于填写）、URL（用于导航）
   • 可选：简短断言（“expect URL to contain /settings”）

4. 在会更改 DOM 或触发导航的操作之后，先获取一份新的 browser_snapshot，再执行下一次交互。

5. 如果流程需要等待异步内容，请按照 cursor-ide-browser 的指南使用 browser_wait_for 或较短的递增等待时间，然后再次获取快照。

3. 添加断言

根据最终快照和 URL，至少添加以下内容：

• expect(page).toHaveURL(...) 或 URL 片段检查
• 一个可见结果：文本、角色或测试 ID

4. 生成 Playwright 输出

生成一个测试文件，例如 tests/recorded/<flow-name>.spec.ts，其中包含：

• test.describe 和 test('...', async ({ page }) => { ... })
• 使用 await page.goto(...)、await page.getByRole(...).click() 等编写步骤
• 最终文件中不要包含原始快照 refs — 它们仅适用于当前会话。

5. 运行并增强稳定性

npx playwright test tests/recorded/<flow-name>.spec.ts

修复不稳定问题：点击前优先使用 expect(locator).toBeVisible()，对异步列表使用 toPass() 重试，除非别无选择，否则避免使用任意的 waitForTimeout。

提示

• 稳定的选择器：角色和无障碍名称优于从开发者工具中复制的 CSS。如果名称不明确，请在应用代码中添加 data-testid。
• 身份验证：如果流程需要登录，请使用测试凭据环境变量或 Playwright storageState — 切勿提交机密。
• 并行运行：确保测试数据不会与其他测试冲突。

不适用场景

• 需要手动完成 2FA、验证码或邮件链接的流程 — 停止并向用户询问是否可以绕过测试限制或使用模拟数据。