前言¶
写端到端（E2E）测试时，最耗时间的往往不是断言本身，而是把「用户在页面上点了什么、填了什么」准确翻译成稳定的选择器。很多人会先手点一遍流程，再对着 DevTools 抄 CSS；过一阵子 DOM 一变，测试就开始飘红。Playwright 自带 Codegen 能录操作，但录出来的选择器质量参差不齐，后续仍要人工整理。
recording-browser-flow-as-test 把这件事交给 Agent Skill：在 Cursor 内置浏览器里逐步走查用户流程，每一步用无障碍树（accessibility tree）记下角色与名称，最后输出一份可回放的 Playwright 测试文件。它来自 spencerpauly 维护的 awesome-cursor-skills 仓库，官方说明见该仓库下的 resources/recording-browser-flow-as-test/SKILL.md。
这是什么¶
一句话定位：把 Cursor 的 browser MCP 当「录制器」用——导航、点击、填写、按键都会记成结构化步骤，再翻译成基于 getByRole / getByLabel 等稳定定位的 Playwright 脚本。
官方 frontmatter 描述如下：
- name：
recording-browser-flow-as-test - description：在 Cursor 内置浏览器中逐步执行用户流程并记录每一步，再生成使用无障碍树派生稳定选择器的 Playwright 测试，用于回放同一流程
- user-invocable：
true（可在对话里用/手动唤起）
Skill 原文强调：这是 Cursor 原生工作流，依赖 browser_snapshot（refs + roles + names）与结构化操作，而不是单独装一个浏览器录制扩展。
核心功能与亮点¶
根据官方 SKILL.md，能力可以概括为下面几点。
-
边走查边记录
Agent 对每一步先browser_snapshot拿到无障碍树与元素 ref，再做最小交互（browser_click/browser_fill/browser_type/browser_select_option/browser_navigate），并把步骤记进结构化列表。 -
优先稳定定位，而不是坐标或脆弱 CSS
写给 Playwright 的定位策略优先顺序是：
-getByRole('button', { name: '...' })
-getByLabel('...')
-getByPlaceholder('...')
- 应用已使用 test id 时再用getByTestId('...')
官方提示：角色与可访问名称通常比从 DevTools 抄来的 CSS 更稳；名称含糊时，可在应用里补data-testid。 -
DOM 变化后重新快照
导航或会改 DOM 的操作之后，要求再拍一次browser_snapshot再继续；异步内容可用browser_wait_for或按cursor-ide-browser指引做短等待，然后再快照。 -
生成可落地的测试文件并加固
默认输出类似tests/recorded/<flow-name>.spec.ts的文件，包含test.describe/test(...)，步骤写成page.goto、getByRole(...).click()等。最终文件里不能留下 snapshot 的 raw ref（那是会话临时的）。生成后建议：
npx playwright test tests/recorded/<flow-name>.spec.ts
加固建议包括：点击前用 expect(locator).toBeVisible()；异步列表用 toPass() 重试；尽量避免随意的 waitForTimeout。
- 断言底线
至少要有：URL 相关断言（toHaveURL或 URL 片段），以及一个可见结果（文本、角色或 test id）。
安装与启用¶
该 Skill 收录在 spencerpauly/awesome-cursor-skills 中。可用 skills CLI 按名称安装：
npx skills add spencerpauly/awesome-cursor-skills --skill recording-browser-flow-as-test
若只要装到某个 Agent，可加 -a，例如 Claude Code：
npx skills add spencerpauly/awesome-cursor-skills --skill recording-browser-flow-as-test --agent claude-code
也可以整库安装（会装上该集合里的多个 Skill）：
npx skills add spencerpauly/awesome-cursor-skills
按 Cursor 官方文档，项目级 Skill 会从 .agents/skills/、.cursor/skills/ 等目录自动发现；用户级则对应 ~/.agents/skills/、~/.cursor/skills/。手动方式就是把官方 SKILL.md 放到例如：
.cursor/skills/recording-browser-flow-as-test/SKILL.md
或：
.agents/skills/recording-browser-flow-as-test/SKILL.md
启用后：在 Agent 对话里输入 /，搜索 recording-browser-flow-as-test 即可手动调用；描述匹配时，Agent 也可能自动选用该 Skill。
说明：Skill 文件本身是通用的 SKILL.md 格式，Claude Code、Codex 等支持 Agent Skills 的工具也能装。但本 Skill 的工作流明确依赖 Cursor 内置浏览器 / browser MCP（browser_snapshot 等），在非 Cursor 环境里即使装了文件，完整「录流程 → 出 Playwright」链路也未必可用，需以各工具实际浏览器能力为准。
典型用法示例¶
前置条件¶
官方要求：
- 目标应用可访问（例如本地 dev server 已启动；需要找端口时，同仓库还有
finding-dev-server-urlSkill） - 仓库已安装或即将安装 Playwright（
@playwright/test）；没有的话可用同仓库的adding-e2e-tests，或按项目既有方式接入
录制流程（与官方一致）¶
1. 先用一句话界定范围，例如：
登录，打开 Settings，切换深色模式，保存。
2. 对每一步按顺序执行
browser_snapshot获取无障碍树与 ref- 选择最小交互（优先用 snapshot 的 ref 点击，而不是坐标点击）
- 在 Agent 维护的列表里记录：步骤号、动作动词（
navigate/click/fill/press/select）、Playwright 定位策略、填写值或 URL、可选短断言 - DOM 或导航变化后再 snapshot
- 需要等异步内容时，
browser_wait_for后再 snapshot
3. 补断言 → 生成 tests/recorded/...spec.ts → 跑测并加固
你可以在 Cursor 里直接这样唤起（表述接近官方示例即可）：
请按 recording-browser-flow-as-test：在浏览器里走查「登录 → 打开 Settings → 切换深色模式 → 保存」，
每步用 browser_snapshot，记录稳定定位，最后生成 Playwright 测试到 tests/recorded/dark-mode-settings.spec.ts，并跑一遍。
生成文件应包含官方要求的结构：test.describe、test('...', async ({ page }) => { ... })，步骤写成 await page.goto(...)、await page.getByRole(...).click() 等。示意如下（定位字符串必须以当次 browser_snapshot 的 role/name 为准，不可照抄）：
import { test, expect } from '@playwright/test';
test.describe('<flow-name>', () => {
test('<one-sentence scope>', async ({ page }) => {
await page.goto('<app-url>');
// 录制日志里的 navigate / click / fill / press / select
// 优先: getByRole / getByLabel / getByPlaceholder / getByTestId
await page.getByRole('button', { name: '<from snapshot>' }).click();
await expect(page).toHaveURL(/<expected-path>/);
await expect(page.getByRole('<role>', { name: '<from snapshot>' })).toBeVisible();
});
});
官方还强调：最终文件里不要写入 snapshot 的 raw ref（它们只在当次浏览器会话有效）。
适用场景与注意事项¶
适合
- 需要把一条清晰的前端用户路径沉淀成 Playwright 回归用例
- 希望定位器尽量走 role / label / placeholder / test id，减少脆弱 CSS
- 已在 Cursor 里用内置浏览器做验证，想顺手留下可重复执行的测试资产
官方明确不建议 / 需要停下询问的情况
- 流程依赖人工二次验证（2FA）、验证码（captcha）或邮件链接——应停下，向用户要测试旁路或 mock
其他官方 Tips
- 鉴权：需要登录时，用环境变量存测试凭据，或使用 Playwright 的
storageState；不要把密钥提交进仓库 - 并行跑测：注意测试数据不要与其他用例冲突
- 同集合里相关 Skill：
adding-e2e-tests（搭 Playwright）、finding-dev-server-url（找本地服务地址）
小结¶
recording-browser-flow-as-test 把「在 Cursor 浏览器里走查」和「写出可维护的 Playwright 脚本」连成一条固定工作流：快照 → 最小操作 → 记结构化步骤 → 用无障碍信息生成稳定定位 → 跑测加固。它不能替代测试设计本身，但对「流程已经能点通、缺的是可回归脚本」这类场景，能明显缩短从手测到自动化的路径。
官方地址：
https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/recording-browser-flow-as-test
