前言¶
寫端到端（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
