Cursor Playwright Skill: A SKILL.md for Sign-up, Checkout and Dashboard E2E Tests

By Rakshit Yadav (@yadavrakshit60)•Oct 2026•6 min read

Short answer: a Cursor Playwright skill is a SKILL.md in .cursor/skills/playwright-saas-e2e/ that tells the agent how to write and stabilise end-to-end tests for sign-up, checkout and the dashboard: which selectors to use, which fixtures to share, and a checklist to run before it calls a flaky test fixed. Below is a complete copy-paste version, where it goes, and what a run looks like.

AgenticKit already ships a general Playwright end-to-end skill and the /e2e-suite command. This post is the narrower, SaaS-specific playbook you can drop in yourself, and why each section of it exists.

What the skill does and when the agent triggers it

The skill does three jobs:

  1. Writes Playwright specs for the three flows a SaaS lives or dies on: sign-up, checkout and the first dashboard screen.
  2. Stabilises tests that pass locally and fail in CI, by walking a fixed flake checklist instead of adding waitForTimeout.
  3. Refuses shortcuts: no CSS-class selectors, no sleeps, no tests that depend on another test's data.

Cursor loads a skill when your request matches its description, so the description is the trigger. Phrases that should match: "write an e2e test for sign-up", "this Playwright test is flaky", "add a checkout test", "CI fails but it passes locally". If the skill never loads, the description is too vague. See Best Cursor Skills in 2026 for how loading works and how skills differ from rules and commands.

SKILL.md contents

Create .cursor/skills/playwright-saas-e2e/SKILL.md:

---
name: playwright-saas-e2e
description: Write and stabilise Playwright end-to-end tests for a SaaS app: sign-up, checkout and the dashboard. Use when the user asks for an e2e test, a Playwright test, or when a Playwright test is flaky or fails only in CI.
---

# Playwright SaaS E2E

## Scope
Cover three flows, one spec file each, in tests/e2e/:
- signup.spec.ts: new user reaches the dashboard
- checkout.spec.ts: free user starts an upgrade and lands on the success state
- dashboard.spec.ts: signed-in user sees their own data, and only theirs

## Selectors (in this order)
1. page.getByRole(name) for buttons, links, headings, inputs
2. page.getByLabel() for form fields
3. page.getByTestId() only when no role or label exists; add data-testid to the component
Never select by CSS class, nth-child, or visible copy that marketing may change.

## Fixtures
- Put shared setup in tests/e2e/fixtures.ts using test.extend.
- signedInPage: logs in once per worker via the API or a seeded user, saves storageState, reuses it. Do not click through the login form in every test.
- newUser: creates a unique email per test (e2e+<timestamp>-<workerIndex>@example.test).
- Each test creates and cleans up its own data. No test may rely on another test having run.

## Network and third parties
- Do not drive Stripe's hosted Checkout page. Assert that the app creates the session and redirects to it, then stub the return with page.route() or hit the success URL directly.
- Stub email and webhooks. Read the confirmation link from the test database or a dev-only endpoint.

## Waiting
- Use web-first assertions: await expect(locator).toBeVisible(). They retry on their own.
- For non-UI state use expect.poll().
- Banned: page.waitForTimeout, arbitrary sleeps, networkidle as a crutch.

## Flake checklist (run before saying "fixed")
1. Does the test depend on data from another test or on clock time?
2. Is there a sleep, or an assertion that does not auto-retry?
3. Is the selector ambiguous (strict mode violation) or tied to copy?
4. Does a click race hydration or navigation? Assert the next state, not the click.
5. Are animations or toasts overlapping the target?
6. Does it only fail in parallel? Look for shared users, emails or rows.
7. Reproduce first: npx playwright test <file> --repeat-each=20. Fix. Run the same command again and require 20/20.
8. Open the trace for the failing run before guessing.

## Config defaults
fullyParallel: true, retries: 2 in CI and 0 locally, trace: 'on-first-retry', screenshot: 'only-on-failure'. Retries hide flakes: report any test that passed only on retry.

## Output
List files written, flows covered, and any flake cause found, with the evidence (trace step or error line).

Why it is built this way:

  • The scope block stops the agent writing thirty shallow tests. Three flows protect revenue and first impressions, which is what a solo founder can afford to maintain.
  • Selector order follows Playwright's preference for user-facing locators. Role and label selectors survive a redesign; class names do not.
  • Stripe is not driven in the browser. Hosted checkout pages are not yours to automate and can change without notice. Test your side of the boundary.
  • Reproduce with --repeat-each before and after. An agent that edits a test and says "fixed" after one green run has proved nothing. Running the same N-run command twice gives a pass/fail you can see.
  • Retries are reported. retries: 2 keeps CI green but also hides flakes, so the skill makes the agent surface them.

Install path (.cursor/skills)

Put the file at:

.cursor/skills/playwright-saas-e2e/SKILL.md

For Claude Code the same file works from .claude/skills/playwright-saas-e2e/SKILL.md, since both use the SKILL.md format. You also need Playwright itself in the repo:

npm init playwright@latest

AgenticKit installs its own Playwright skill into the same folders with one command (npx agentickit-cursor init --target cursor), alongside the agents and commands that load it.

Example run

Prompt in a fresh agent chat:

checkout.spec.ts fails about one run in five in CI. Fix it.

What the skill makes the agent do, in order:

  1. Runs npx playwright test tests/e2e/checkout.spec.ts --repeat-each=20 and records how many runs fail, instead of trusting a single run.
  2. Opens the trace of a failing run and finds the step that broke, for example a click on "Upgrade" that fires before the pricing buttons are enabled.
  3. Walks the checklist and finds a waitForTimeout(1000) (item 2) and a selector on .btn-primary (item 3).
  4. Replaces them with getByRole('button', { name: 'Upgrade' }) plus an expect(...).toBeEnabled() assertion, and moves user setup into the newUser fixture.
  5. Re-runs the same 20-run command and reports the result, with a note if it only passed because of retries.

This is an illustration of the flow, not a benchmark. The point is that the agent reproduces, finds a cause with evidence, fixes it and re-measures, rather than guessing.

Related skills

FAQ

Where does a Cursor Playwright skill go? In .cursor/skills/<name>/SKILL.md, for example .cursor/skills/playwright-saas-e2e/SKILL.md.

Is this different from a Cursor rule? Yes. A rule applies always or by file glob. A skill loads when your task matches its description, so a long Playwright playbook only costs context when you are working on tests.

How do I stop Playwright tests being flaky? Use role and label selectors, web-first assertions that auto-retry, a unique user per test, and reproduce failures with --repeat-each before and after the fix. The checklist in the skill covers these.

Should the skill test Stripe Checkout in the browser? No. Test that your app creates the session and handles the return and webhook. Stripe's hosted page is outside your control.

Does it work in Claude Code? Yes, put the same file in .claude/skills/playwright-saas-e2e/SKILL.md.

Get the full set

AgenticKit installs 34 agents, 61 skills and 47 commands, including the Playwright skill and /e2e-suite, with one command. See all Cursor skills or pricing.

Related Tools & Agents

🛠️ Free Tool: rules-grader🤖 Agent: test-automator⚡ Command: /e2e-suiteSkill: playwright-e2eSkill: testing-vitest

Install the Playwright skill and 60 more

34 agents, 61 skills and 47 commands land in .cursor/ and .claude/.

Get the kit →