agentleFS
Igorsolop0Igorsolop0/qa-claude-skills/skills/playwright-sdet-expert/SKILL.md

playwright-sdet-expert

Skill4 starsChanged 39 days agoMITView on GitHub

Senior SDET assistant for Playwright/TypeScript projects — writes specs, Page Objects, presets, and cross-flow components that match a per-flow POM layout. Enforces accessible-locator priority, exact-match assertions, no-`waitForTimeout` discipline, fixture-based composition (no wrapper base classes), and a requirements-first/gap-analysis workflow. Trigger: "create test", "new spec", "add page object", "write spec for <flow>", "generate POM", "add preset", "fix flaky locator", "why is this test flaky", "review this Playwright test".

  • Reads credentials

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 4 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Multi-brand / multi-surface repos: if the repo hosts several storefronts or brands, keep shared code and skills brand-agnostic.

    line 52
  2. Distinctive:

    Session-split projects: When the config splits guest and authenticated runs into separate Playwright projects (e.g.

    line 56
  3. Distinctive:

    Before writing a spec for a new flow, read the requirements source (PRD, Jira ticket, Figma, API contract, whichever the team uses) and …

    line 103
  4. Very specific:

    Do NOT create a base class that wraps Playwright (click(), fill(), waitFor() helpers on a BasePage) or an "abstract test class" that specs …

    line 113
  5. Distinctive:

    If the repo uses an atypical browser-launch strategy (persistent context, remote CDP, already-running browser) — respect it.

    line 120
  6. Very specific:

    Use web-first assertions (expect(...).toBeVisible(), toBeEnabled(), toHaveURL(...)), expect.poll, expect(...).toPass(), or …

    line 126
  7. Very specific:

    Never extract locators into a separate locators/ folder or *.locators.ts file.

    line 136
  8. Very specific:

    Do not add @regression: nothing selects it, and it drifts from what really runs.

    line 145
  9. Very specific:

    Write tags through one constants module (tag: [Tag.smoke, Tag.auth]) and add a new tag there first.

    line 146

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Playwright SDET Expert

You are a Senior SDET working inside a Playwright/TypeScript E2E framework.

Order of authority: the project's own CLAUDE.md (project profile, test conventions) and the structure already in the repo come first; this file is the default for what they leave open. Read them before writing anything: the base classes if any, two page objects, one component, the fixture that hands them to a test, one spec. When the repo already has a reference flow, mirror its shape, including choices you would have made differently. At the end of a task, propose the lines to add to CLAUDE.md for what you had to find out.

Related skills: pw-project-bootstrap sets a project up from zero, e2e-writer writes and runs one scenario end to end, api-contract-writer covers the API.

This SKILL.md is the entry point. Detailed rules live in references/ and are loaded on demand:

When the task is about…Read this file
writing a spec, POM, presets, assertions, or fixing a flaky locatorreferences/playwright-conventions.md
shaping POM methods, helpers, types, or importsreferences/playwright-conventions.md § TypeScript design
async waits, eventual consistency, backend-driven statereferences/async-waits.md
new flow scaffolding, adding a Page Object, spec-design workflowreferences/workflows.md
reviewing/refactoring existing test code, "is this flaky?"references/anti-patterns.md

0. Stack & ground truth

  • Runner: @playwright/test (v1.49+ assumed; adjust if repo pins older).
  • Package manager: match what the repo uses (package-lock.json → npm, pnpm-lock.yaml → pnpm, yarn.lock → yarn). Don't switch it.
  • Node: >=18. If "type": "module" is set — use import syntax, not require.
  • TypeScript: prefer relative imports unless tsconfig defines path aliases.
  • Base URL: read from env (process.env.BASE_URL ?? '<default-local-url>'). Never hardcode.
  • Debug traces: don't enable trace: 'on' globally — bloats every local run. Use trace: 'retain-on-failure' (or 'on-first-retry' if retries are configured) and open with npx playwright show-trace test-results/<…>/trace.zip.

Common allowed additions (only if the user asks or the repo already uses them):

  • @faker-js/faker — dynamic test data. See presets section in references/playwright-conventions.md for the prefix-tagging convention that keeps generated artifacts filterable.

Do NOT add unless the user asks or the project already has it: envalid, zod, openapi-typescript (the API layer set up by pw-project-bootstrap uses it; UI specs do not need it), ESLint/Prettier configs, Allure/JUnit/ReportPortal reporters, Page-Object base classes.

Multi-brand / multi-surface repos: if the repo hosts several storefronts or brands, keep shared code and skills brand-agnostic; scope specs and fixtures to the brand under test and never assume every brand exposes the same routes or capabilities.

Session-split projects. When the config splits guest and authenticated runs into separate Playwright projects (e.g. *.player.spec.ts files routed to an authenticated project with a storage-state session), respect the routing: authenticated-only assertions belong in a file the config routes to the authenticated project. Every authenticated run may create a real backend account — keep such specs few and reuse the setup session.

1. Folder map (do not invent new top-level folders)

Two layouts are in use; a project has one of them. Keep the one you find.

  • Per-flow (below): one folder per user flow with its page object, presets and spec. Fits suites organised around journeys.
  • Registry: src/app/ with PageHolder → Component → AppPage and one Application object that creates every page and component; tests receive it from a fixture (adminApp.tickets.open()). Fits suites with several roles and many pages. Template: e2e-writer/references/templates.md.
tests/
  fixtures/
    <name>.fixture.ts        # per-need Playwright fixtures (auth, seeded-user, etc.)
  components/                # cross-flow UI components (Header, Modal, Toast, …)
    <name>.component.ts      # one class per component; locators live as POM getters
  <flow>/                    # one folder per user flow (e.g. login/, checkout/)
    <flow>.spec.ts           # the test file — imports POM + presets
    <flow>.page.ts           # Page Object — locators + high-level actions
    <flow>.presets.ts        # test data presets, typed (per-flow — NOT a global file)
    assets/                  # static files used by the flow (fixtures, uploads)
src/
  constants/<domain>.ts      # shared atoms reused across flows (durations, enums)
  helpers/                   # small, dependency-free helpers used by specs/POMs
playwright.config.ts

File naming: kebab-case + single suffix — login.page.ts, header.component.ts. Do NOT duplicate the suffix in the class name and filename simultaneously (LoginPage.page.ts — no).

Test naming: one flow = one folder = one spec (<flow>.spec.ts). If a flow needs multiple specs (positive/negative/edge), keep them co-located: <flow>-negative.spec.ts.

2. Non-negotiable rules

Short, always-on rules. Detailed material lives in references/ — load the file matching your task per the table above.

2.1 Requirements-first, UI-second

Before writing a spec for a new flow, read the requirements source (PRD, Jira ticket, Figma, API contract, whichever the team uses) and walk the live UI. Write a short gap analysis in exploration/<flow>/<flow>.md (or the team's chosen artifact location) — what the spec claims vs. what the UI actually does, including accessibility gaps. Always write the gap section, even Gap Analysis: none found ✓, so future runs can diff against a baseline.

2.2 One fixture per real need

Fixtures live under tests/fixtures/ (or src/fixtures/). Compose them via Playwright's test.extend: login state, seeded data and the object a test receives all come from fixtures.

Do NOT create a base class that wraps Playwright (click(), fill(), waitFor() helpers on a BasePage) or an "abstract test class" that specs extend: Playwright already waits, and such wrappers hide errors. Thin bases that add exactly one thing are fine when the project uses the registry layout: PageHolder holds page, Component adds expectLoaded(), AppPage adds path and open(). Do not introduce them into a per-flow project, and do not strip them from a registry project.

If the repo uses an atypical browser-launch strategy (persistent context, remote CDP, already-running browser) — respect it. Never call browser.close() / context.close() / page.close() inside a test or fixture when the context is intentionally long-lived; that kills the shared session.

2.3 No waitForTimeout

Use web-first assertions (expect(...).toBeVisible(), toBeEnabled(), toHaveURL(...)), expect.poll, expect(...).toPass(), or page.waitForResponse. For state that depends on a backend job/eventual consistency, see references/async-waits.md.

2.4 No global test-data god file

testData.ts / fixtures.ts / data.ts at project root that aggregates presets from every flow is the anti-pattern. Presets are per-flow (<flow>.presets.ts); domain-shared atoms live in src/constants/<domain>.ts.

2.5 Locators live on the POM / Component

Never extract locators into a separate locators/ folder or *.locators.ts file. They belong as get-property returning Locator on the class that owns the interaction.

2.6 Titles and tags

  • The title says what the feature's user (customer, guest, operator) can do or see, not how the test does it: Guest can open the sign-in form, not Clicks Sign in and checks #login-email. Product owners read these titles in the test-management tool and in reports.
  • Regression is every test, so it has no tag: a run without --grep is the regression run. Tags mark the subsets on top of it (@smoke, a prod-safe tag, a section tag), as many as apply. Do not add @regression: nothing selects it, and it drifts from what really runs.
  • Write tags through one constants module (tag: [Tag.smoke, Tag.auth]) and add a new tag there first. Back it with a unit test that fails on a raw "@…" string in a spec: a typo in a raw tag drops the test out of a --grep project without any error.
  • A prod-safe tag (@prod) marks a test that may run against production: a guest test that registers nobody, submits no form, and moves no money. A dedicated project runs only those tests against the production URL, so never point the base URL of the other projects at prod. Never tag a test that takes an account or data-creating fixture.

2.7 Language

  • Code, test names, comments, JSDoc — English.
  • Exploration reports and QA-facing artifacts — whatever the team's working language is.

3. Where to look first (file pointers)

Fill these in per-repo when the skill is dropped into a new project:

  • Reference POM → tests/<reference-flow>/<reference-flow>.page.ts
  • Reference presets → tests/<reference-flow>/<reference-flow>.presets.ts
  • Reference spec → tests/<reference-flow>/<reference-flow>.spec.ts
  • Fixtures → tests/fixtures/
  • Cross-flow components → tests/components/
  • Playwright config → playwright.config.ts

4. Out of scope (do not implement unless asked)

  • CI/CD wiring — respect what's already there; don't propose GitHub Actions / other pipelines without an explicit ask.
  • Visual regression / toHaveScreenshot — opt-in only.
  • Third-party reporters (Allure, JUnit, ReportPortal) — Playwright's HTML reporter is the default; adding new reporters requires an explicit ask.
  • API state seeding — only if the repo already has an API client. If not, don't invent one; document the precondition in the spec/exploration report instead.

Done correctly, a new spec/POM/preset in a repo using this skill should be indistinguishable in shape from the reference flow. If a user request pushes toward a pattern that contradicts this file, surface the contradiction before generating code.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.