Skip to content

project rulesTestingtypescript

Playwright E2E Rules

Project rules for Playwright suites: role-based locators, fixtures, test isolation, web-first assertions, traces and CI sharding.

npx workspacetemplates add playwright-e2e-rules --tool claude-code

Writes 1 file to your project root

CLAUDE.mdadd to your file16 lines · 1.2 KBFile
# Project rules: Playwright E2E

## Locators and assertions
- Locate by role, label, text or test id: `getByRole`, `getByLabel`, `getByTestId`. Avoid XPath and deep CSS chains. Add `data-testid` in the app when no accessible name exists.
- Use web-first assertions (`await expect(locator).toBeVisible()`, `toHaveText`, `toHaveURL`), which retry. Never use `waitForTimeout` or fixed sleeps; wait on a condition or a network response.
- No `if` branches in tests; one behavior per test, named like a sentence.

## Isolation and setup
- Each test runs alone and in any order. Create data through the API or a fixture, not through earlier tests.
- Log in once in a setup project and reuse `storageState`. Put page objects and custom fixtures in `tests/fixtures`, using `test.extend`.
- Mock only third-party services with `page.route`; keep your own backend real.

## Config and CI
- Set `baseURL`, `retries: 2` only in CI, `trace: 'on-first-retry'`, `screenshot: 'only-on-failure'`, and `forbidOnly` in CI.
- Shard with `--shard=1/4` across jobs, merge blob reports and upload the HTML report and traces.
- Run `npx tsc --noEmit` and `npx playwright test` locally before finishing.

What it does

These rules keep end-to-end suites fast and stable. They steer an agent toward locators users would recognize, independent tests and assertions that wait for the page instead of guessing.

They also cover failure diagnosis and CI, so a red run produces a trace you can open and the suite scales across machines.

Example

you › Write a test for the checkout flow

agent › The agent adds a checkout spec that seeds a cart through the API, uses role locators, asserts the confirmation page with a retrying expect and has no sleeps.

Questions

Why retries only in CI?
Local retries hide flaky tests from the author who could still fix them.
Can I use CSS selectors at all?
Rarely. Prefer roles and test ids; use CSS only for elements with no accessible handle.
  • Jest Vitest Rules

    Project rulesjavascript

    Free
  • Contract Testing

    SkillTesting

    Free
  • E2E Test Design

    SkillTesting

    Free
  • Flaky Test Diagnosis

    SkillTesting

    Free