Preface

When writing end-to-end (E2E) tests, the most time-consuming part is often not the assertions themselves, but accurately translating “what the user clicked or typed on the page” into stable selectors. Many people first walk through the workflow manually, then copy CSS selectors from DevTools; after a while, even a minor DOM change will break the tests. Playwright has a built-in Codegen tool that records actions, but the generated selectors vary in quality and still require manual cleanup later.

recording-browser-flow-as-test hands this work over to an Agent Skill: it walks through the user workflow step-by-step in Cursor’s built-in browser, records roles and names using the accessibility tree at each step, and finally outputs a replayable Playwright test file. It comes from the awesome-cursor-skills repository maintained by spencerpauly, and the official documentation can be found in resources/recording-browser-flow-as-test/SKILL.md under this repository.

What it is

In one sentence: use Cursor’s browser MCP as a “recorder” — navigation, clicks, fills, and key presses are all recorded as structured steps, then translated into Playwright scripts using stable locators based on getByRole / getByLabel and similar APIs.

The official frontmatter is as follows:
- name: recording-browser-flow-as-test
- description: Execute user workflows step-by-step in Cursor’s built-in browser and record each step, then generate Playwright tests that use stable selectors derived from the accessibility tree to replay the same workflow
- user-invocable: true (can be manually invoked with / in chat)

The original Skill documentation emphasizes that this is a native Cursor workflow that relies on browser_snapshot (refs + roles + names) and structured operations, rather than a separate browser recording extension.

Core Features and Highlights

According to the official SKILL.md, the capabilities can be summarized as follows.

  1. Record while walking through the workflow
    The Agent first runs browser_snapshot to get the accessibility tree and element refs for each step, then performs minimal interactions (browser_click / browser_fill / browser_type / browser_select_option / browser_navigate), and adds the steps to a structured list.

  2. Prioritize stable locators over coordinates or fragile CSS
    The priority order of locator strategies for Playwright is:
    - getByRole('button', { name: '...' })
    - getByLabel('...')
    - getByPlaceholder('...')
    - Use getByTestId('...') only when test IDs are already in use
    Official note: Roles and accessible names are usually more stable than CSS selectors copied from DevTools; if the name is ambiguous, you can add data-testid attributes in the application.

  3. Re-snapshot after DOM changes
    After navigation or operations that modify the DOM, request another browser_snapshot before proceeding; for asynchronous content, use browser_wait_for or follow the cursor-ide-browser guide for short waits before taking a snapshot.

  4. Generate and harden production-ready test files
    The default output is a file similar to tests/recorded/<flow-name>.spec.ts, containing test.describe / test(...), with steps written as page.goto, getByRole(...).click() and other standard Playwright APIs. Raw snapshot refs must not be left in the final file (they are temporary per session). After generation, it is recommended to:

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

Hardening suggestions include: using expect(locator).toBeVisible() before clicks; retrying asynchronous lists with toPass(); and avoiding arbitrary waitForTimeout calls whenever possible.

  1. Assertion baseline
    At minimum, include: URL-related assertions (toHaveURL or URL fragments), and a visible result check (text, role, or test ID).

Installation and Activation

This Skill is included in the spencerpauly/awesome-cursor-skills repository. You can install it by name using the skills CLI:

npx skills add spencerpauly/awesome-cursor-skills --skill recording-browser-flow-as-test

If you only want to install it for a specific agent, add the -a flag, for example for Claude Code:

npx skills add spencerpauly/awesome-cursor-skills --skill recording-browser-flow-as-test --agent claude-code

You can also install the entire repository (which will install multiple Skills in the collection):

npx skills add spencerpauly/awesome-cursor-skills

According to Cursor’s official documentation, project-level Skills are automatically discovered from directories like .agents/skills/, .cursor/skills/; user-level Skills correspond to ~/.agents/skills/, ~/.cursor/skills/. The manual method is to place the official SKILL.md file in, for example:

.cursor/skills/recording-browser-flow-as-test/SKILL.md

or:

.agents/skills/recording-browser-flow-as-test/SKILL.md

After activation: you can manually invoke it by typing / in the Agent chat and searching for recording-browser-flow-as-test; the Agent may also automatically select this Skill when the description matches.

Note: The Skill file itself uses the universal SKILL.md format and can be installed in tools that support Agent Skills such as Claude Code and Codex. However, this Skill’s workflow explicitly depends on Cursor’s built-in browser / browser MCP (browser_snapshot etc.), so even if you install the file in a non-Cursor environment, the complete “record workflow → generate Playwright code” pipeline may not work, and you should refer to each tool’s actual browser capabilities.

Typical Usage Example

Prerequisites

Official requirements:
- The target application is accessible (for example, a local dev server has been started; if you need to find the port, there is also the finding-dev-server-url Skill in the same repository)
- Playwright (@playwright/test) has been or will be installed in the repository; if not, you can use the adding-e2e-tests Skill from the same repository, or set up Playwright using your project’s existing workflow

Recording the workflow (consistent with the official guide)

1. First define the scope in one sentence, for example:

Log in, open Settings, switch to dark mode, and save.

2. Execute each step in order
1. Run browser_snapshot to get the accessibility tree and refs
2. Select the minimal interaction (prefer clicking using the snapshot’s refs instead of coordinate clicks)
3. Record in the Agent-maintained list: step number, action verb (navigate / click / fill / press / select), Playwright locator strategy, fill value or URL, and optional short assertion
4. Take a snapshot again after DOM or navigation changes
5. When waiting for asynchronous content, run browser_wait_for before taking a snapshot

3. Add assertions → generate tests/recorded/...spec.ts → run tests and harden the code

You can invoke it directly in Cursor like this (the phrasing should be close to the official example):

Please follow recording-browser-flow-as-test: walk through the workflow "log in → open Settings → switch to dark mode → save" in the browser, use browser_snapshot at each step, record stable locators, finally generate the Playwright test to tests/recorded/dark-mode-settings.spec.ts, and run the test.

The generated file should follow the official required structure: test.describe, test('...', async ({ page }) => { ... }), with steps written as await page.goto(...), await page.getByRole(...).click() and other standard APIs. Here is a skeleton example (the locator strings must be based on the role/name from the current browser_snapshot, do not copy blindly):

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 from the recording log
    // Priority: 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();
  });
});

The official also emphasizes: Do not write raw snapshot refs into the final file (they are only valid for the current browser session).

Applicable Scenarios and Notes

Suitable For

  • Need to formalize a clear frontend user path into Playwright regression test cases
  • Want to use role / label / placeholder / test ID locators as much as possible to reduce fragile CSS dependencies
  • Have already verified the workflow using Cursor’s built-in browser and want to quickly create repeatable test assets

Official Explicitly Discouraged / Pausing to Ask Situations

  • Workflows depend on manual secondary verification (2FA), CAPTCHAs, or email links — you should pause and ask the user for test bypasses or mocks

Other Official Tips

  • Authentication: When login is required, use environment variables to store test credentials, or use Playwright’s storageState; never commit secrets into the repository
  • Parallel testing: Ensure test data does not conflict with other test cases
  • Related Skills in the same collection: adding-e2e-tests (set up Playwright), finding-dev-server-url (find local server addresses)

Summary

recording-browser-flow-as-test connects “walking through the workflow in Cursor’s browser” and “writing maintainable Playwright scripts” into a fixed workflow: snapshot → minimal operation → record structured steps → generate stable locators using accessibility information → run tests and harden the code. It cannot replace test design itself, but for scenarios where “the workflow already works manually and what is missing is a regression script”, it can significantly shorten the path from manual testing to automated testing.

Official address:
https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/recording-browser-flow-as-test