Cursor Rules for Playwright: Stable Browser Tests

Cursor rules for Playwright tell the assistant which locators to reach for, where shared setup code lives, and what to run before marking a task done. Without them, an assistant writes tests with brittle CSS selectors, invents fixture code that duplicates existing setup, and skips the final run that would catch a simple failure.

The rules handle the style decisions. fenbs keeps the lessons from failures and the acceptance criteria for each test task, so the next session starts knowing what the previous one learned. Together they give the assistant both the how and the why.

What to put in Playwright rules

Playwright gives assistants too much choice by default. They can pick locators from five or six different strategies, add explicit sleeps instead of proper waits, and create page objects in ways that conflict with yours. A rule file narrows those choices to the patterns your team already uses.

• Locator strategy: which methods to prefer (getByRole, getByLabel, getByTestId) and which to avoid (CSS selectors, XPath).
• Fixture location: the single file all tests should import from, and how to extend it.
• Assertion style: prefer toBeVisible, toHaveText, toHaveValue; forbid waitForTimeout.
• Completion check: the exact command to run before the task is done.
• Data attribute: the agreed name for test IDs on elements with no accessible role.

Stable locators

The most common source of brittle tests is a locator that breaks when a designer changes a class name or restructures a layout. Playwright's built-in locators based on accessible role and label survive those changes because they describe what an element does, not how it is styled.

When an element has no meaningful accessible role, use a data-testid attribute. Agree on the attribute name across your codebase and add it to your rule. The assistant then has a stable target without reading other spec files to reverse-engineer what the team uses.

---
description: Playwright browser test rules
globs: "**/*.spec.ts,**/e2e/**/*.ts,**/tests/**/*.ts"
alwaysApply: false
---

## Locators
- Use `getByRole`, `getByLabel`, `getByText`, `getByTestId` in that order.
- Never use CSS selectors or XPath unless a role locator is impossible and you explain why.
- Use `data-testid` for elements with no accessible role.

## Fixtures
- Import all shared setup from `tests/fixtures/index.ts`.
- Extend the base test there if you need new shared state — do not define fixtures inline.

## Assertions
- Use `expect(locator).toBeVisible()` instead of checking `.count()`.
- Use `toHaveText` and `toHaveValue` instead of `page.evaluate` comparisons.
- Never add `page.waitForTimeout`; fix the underlying timing issue instead.

## Completion
- Run `npx playwright test --reporter=list` before marking a task done.
- If a test fails, run `npx playwright test --ui` to confirm visual state.

Fixtures and shared setup

Playwright fixtures let you share browser state, authenticated sessions, and test data across spec files. An assistant without guidance tends to inline all setup inside test() blocks or create a separate fixture file for each spec. A rule that names one fixture file keeps setup consistent and lets the assistant build on what already exists.

If your project uses an authenticated user fixture, name it explicitly in the rule. The assistant then knows to use test.extend and import from the right file rather than creating a conflicting parallel setup. A small pointer in the rule saves time that would otherwise go to reconciling two fixture patterns.

Assertions and waits

Playwright's expect matchers include built-in auto-waiting: they retry until the condition is true or the timeout expires. An assistant that falls back to waitForSelector or waitForTimeout adds fragility and hides what the test is actually verifying.

Requiring specific matchers in the rule also makes reviews easier. When a new spec uses waitForTimeout, anyone reading the code knows immediately that it bypasses the intended style. That visibility makes the review conversation concrete: "the rule says not to use this; what is the actual timing dependency?"

Scoping the rule to test files

A glob pattern like **/*.spec.ts activates the rule only for spec files, keeping it out of application code. If your tests live under e2e/ or tests/, adjust the glob to match your layout. A well-scoped rule reduces noise in the assistant's context for non-test work in the same project.

The glob also signals to the assistant which files it should focus on for a test task and which belong to application code. An assistant working on a spec file should not reach into application source to refactor code that makes a test pass more easily. The scope separation in the glob, combined with a rule that says "fix the test, not the application code, unless the application code is clearly wrong", keeps those concerns from blurring.

See cursor rules examples for more patterns you can adapt, and cursor rules for AI projects for how to organize multiple rule files. For managing a set of rule files across projects, see cursor rules hierarchy and cursor rules library. For comparison with a different testing tool, see Selenium vs Playwright.

How to set up Playwright rules with fenbs

1. Create a free account and add your application as a project.
2. Add a task for each area of test coverage you want to build. Include the acceptance criteria in the task's plan: what the test must verify, the fixtures it needs, and known edge cases.
3. Place the .cursor/rules/playwright.mdc file at the root of your repo and adjust the globs to match your test folder layout.
4. Connect Cursor to fenbs through Integrations using MCP, then ask it to read the project context before starting test work.
5. When a test reveals a timing issue or a locator gap, record a Lesson learned in fenbs. Save progress on each task before ending the session so the next assistant picks up from the last verified state.

For running Playwright as an MCP tool in your AI assistant, see Playwright MCP. fenbs does not run tests or produce test reports; it keeps the acceptance criteria and the lessons around them.