Playwright E2E Skills

What a finished spec looks like

import { test, expect } from '{{#if HAS_CUSTOM_FIXTURE}}{{FIXTURE_IMPORT_PATH}}{{else}}../fixtures{{/if}}' // the project fixtures, never '@playwright/test'

test.describe('Checkout', { tag: ['@smoke'] }, () => {           // one selection tag, in the options object
  test('a signed-in shopper places an order for one item', async ({ checkoutPage }) => {
    await checkoutPage.goto()
    await expect(checkoutPage.placeOrderButton).toBeEnabled()    // web-first: retries until true

    await checkoutPage.placeOrder()                              // page-object action, wrapped in test.step()

    await expect(checkoutPage.confirmation).toHaveText(/Order #\d+ placed/) // the outcome, not "the page loaded"
    await expect(checkoutPage.headerBasketCount).toHaveText('0') // every place the change shows up
    await expect(checkoutPage.placeOrderButton).toBeHidden()     // absence, anchored: it matched above
  })
})

Locators live on the page object as readonly properties, each one resolved against the real page. No page.waitForTimeout(), no { force: true }, no XPath, no retry that turns a failure green. The rules behind each line are in references/conventions.md; the test is verified by watching it fail once, not only by watching it pass.

Operating Procedure

Work in phases and say which one you are in. Detail is in references/workflow.md.

Classify the job → route to the reference → explore the real page, endpoint or failure → plan with a confidence score → stop before applying and wait for approval → apply → verify by running it more than once → report, unknowns included.

Four rules that hold everywhere:

• Explore before generate. A locator never resolved against a real page is a guess with good syntax.
• Below 5, emit no plan. A low confidence score means you are still exploring, not that you should attach a caveat to a proposal. Ask the question that would raise it.
• A skeleton counts as a placeholder. TODO, empty page object methods, a commented-out assertion — all defer the same failure. Placeholders are not deliverables.
• No substitute exploration. If playwright-cli is unavailable, stop and say so. Never infer selectors from application source.

Decision Tree

What do you need to do?
│
├─ Write a NEW test
{{#if HAS_TEMPLATES}}│  ├─ Plan first        → references/test-planning.md
│  ├─ Generate code     → references/test-generation.md
{{/if}}│  ├─ Locators/asserts  → references/locators-and-assertions.md
│  └─ Review when done  → references/test-review.md
│
├─ Debug a FAILING test
{{#if HAS_TEMPLATES}}│  ├─ Diagnose & fix    → references/test-debugging.md
{{/if}}│  ├─ Agent debugging   → references/agent-debugging.md
│  └─ Flaky on CI       → references/ci-and-flake-triage.md
│
├─ Test an API (no browser)
│  └─ Request context   → references/api-testing-patterns.md
│
├─ Prove DETERMINISM
│  └─ Run it N times    → references/pass-rate-and-flake-analysis.md
│
├─ Understand PATTERNS
│  ├─ Playwright APIs   → references/playwright-patterns.md
│  ├─ Fixtures & auth   → references/fixtures-and-auth.md
{{#if HAS_TEMPLATES}}│  ├─ Page objects      → references/page-object-conventions.md
{{/if}}│  └─ Test data         → references/data-strategy.md
│
├─ Follow CONVENTIONS
│  ├─ MUST/SHOULD/WON'T → references/conventions.md
{{#if HAS_TEMPLATES}}│  └─ This project's rules → references/project-conventions.md
{{/if}}│
├─ Automate a BROWSER   → official `playwright-cli` skill (see below)
│
└─ UNCLEAR what to do   → references/workflow.md

Skill Reference

{{#if HAS_WORKFLOWS}}## Procedures

Six procedures ship with this skill. On Claude Code, Cursor and GitHub Copilot each is also a command you can invoke directly. Anywhere else — Codex, Gemini CLI, any agent reading .agents/skills/ — ask for one by name and read its file; the content is identical.

Bodies are in workflows/. Delegation limits are in references/delegation-rules.md.

{{/if}}## Browser automation and agent debugging

Playwright ships its own agent skills; this skill does not duplicate them.

• playwright-cli drives a browser from the terminal (open, snapshot, click, fill, find, eval, generate-locator, attach). Install into this project with npx playwright cli install --skills (Playwright 1.62+) or npm i -g @playwright/cli@latest && playwright-cli install --skills.
• playwright-trace inspects trace.zip files from the terminal (npx playwright trace ...). Install with npx playwright trace install-skill.
• The workflow that ties them together (npx playwright test --debug=cli, playwright-cli attach, trace triage) is in references/agent-debugging.md.

Quick Reference

• Before writing tests: {{#if HAS_TEMPLATES}}read references/test-planning.md, explore the page (playwright-cli if installed), then write using references/test-generation.md{{else}}explore the page (playwright-cli if installed), then write using the patterns in references/locators-and-assertions.md and references/fixtures-and-auth.md{{/if}}
• Before submitting PRs: run the references/test-review.md checklist
• When tests fail: {{#if HAS_TEMPLATES}}follow references/test-debugging.md, {{/if}}{{#if HAS_PLAYWRIGHT_159}}attach with --debug=cli (references/agent-debugging.md), {{/if}}classify the root cause, then fix the test or report the app bug
• For patterns: check references/playwright-patterns.md for waitForResponse, toPass, expect.poll
• Before calling a suite stable: run it N times and report the distribution (references/pass-rate-and-flake-analysis.md), never a single green run