Skip to content

borghei/Claude-Skills / engineering/playwright-pro

playwright-pro

Verified

End-to-end testing with Playwright: test generation, page objects, locator strategy, flaky- test diagnosis, visual regression, and CI integration. Use when writing E2E tests, fixing flaky tests, or migrating from Cypress/Selenium.

Playwright Pro

The agent writes and maintains end-to-end tests with Playwright that stay green for the right reasons. It can generate tests from user stories, implement the Page Object pattern for maintainability, apply the correct locator strategy for resilient tests, diagnose and fix flaky tests, migrate from Cypress or Selenium, integrate with CI/CD, run visual regression tests, and perform accessibility audits. The 10 golden rules in the core reference prevent most flaky and brittle tests.

Core Capabilities

  • Resilient authoring — getByRole/getByLabel/getByText locator priority, web-first auto-retrying assertions, and the 10 golden rules.
  • Page Object Model — centralize locators, expose user-intent methods, generate POM classes from HTML/selectors.
  • Test generation — produce specs from user stories with happy-path and error-path coverage.
  • Flaky-test diagnosis — trace analysis, headed/debug runs, race-condition and shared-state fixes.
  • Migration — Cypress/Selenium → Playwright command mapping and auth-setup patterns.
  • CI integration — GitHub Actions, sharding, conditional browser installs, trace/screenshot artifacts.
  • Visual regression & accessibility — toHaveScreenshot baselines and Axe WCAG AA gates.

When to Use

  • Writing or organizing E2E tests for web apps.
  • Fixing flaky tests or diagnosing CI-only failures.
  • Migrating a suite from Cypress or Selenium.
  • Adding visual regression or WCAG accessibility gates.
  • Setting up Playwright CI integration and reporting.

Clarify First

Before generating tests, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

  • Task / sub-skill: init, generate, fix-flaky, migrate, or review (routes the entire workflow).
  • User story or flow to cover: the happy + error paths the spec must assert (drives test generation).
  • Locator surface: whether the app exposes roles/labels/data-testid (sets locator strategy and POM resilience).
  • Source framework (if migrating): Cypress or Selenium (selects the command-mapping table).

Ask about the two or three inputs that matter most for this request, not the whole list. If the user wants a result straight away, produce it and state your assumptions at the top.

Sub-Skills

This skill uses compound sub-skill architecture. Each sub-skill in skills/ handles a specific workflow:

Sub-SkillFilePurpose
Initskills/init.mdBootstrap Playwright in a project -- install, configure, create first test
Generateskills/generate.mdGenerate test files from user stories or page descriptions
Fixskills/fix.mdDiagnose and fix failing or flaky tests using trace analysis
Migrateskills/migrate.mdMigrate from Cypress or Selenium to Playwright
Reviewskills/review.mdAudit test quality, coverage gaps, and flaky test indicators
Reportskills/report.mdGenerate execution reports from Playwright JSON output
Coverageskills/coverage.mdMap tests to user stories, identify coverage gaps
BrowserStackskills/browserstack.mdBrowserStack cloud integration for cross-browser testing
TestRailskills/testrail.mdTestRail integration for test case management

Sub-skill flow: Init → Generate → Review → Fix (if needed); Coverage → Generate (fill gaps); Report → BrowserStack / TestRail.

Workflow

  1. Pick the sub-skill for the task (table above) and read it.
  2. Before writing, map what exists: coverage_mapper.py against a flows file shows which user flows have no spec.
  3. Write or generate specs with role, label and text locators and web-first assertions; test_generator.py and page_object_generator.py give a starting skeleton, not finished tests.
  4. Validation checkpoint: test_analyzer.py on the spec directory must exit 0 (no high-severity findings such as waitForTimeout or force: true).
  5. After CI runs, parse reports with test_report_parser.py and track flakiness across runs with flaky_detector.py; fix flaky tests by root cause, never by adding retries or sleeps.
  6. Done when the critical flows are covered, the analyzer is clean, and the last ten CI runs show no flaky tests.

Quick Start

# from engineering/playwright-pro/
python3 scripts/test_analyzer.py assets/tests                    # exit 0: clean
python3 scripts/test_analyzer.py assets/flawed_tests             # exit 1: waitForTimeout, nth-child CSS
python3 scripts/coverage_mapper.py --tests assets/tests --flows assets/sample_flows.json   # 1 of 3 flows covered
python3 scripts/flaky_detector.py --results-dir assets/reports  # checkout spec flaky in 2 of 3 runs
python3 scripts/test_report_parser.py assets/reports/run3.json --top-slow 3
python3 scripts/page_object_generator.py --html assets/sample_login.html --name LoginPage --route /login
python3 scripts/test_generator.py --story "User can log in with email and password" --page LoginPage --route /login

Tools Overview

ToolPurposeKey flagsExit codes
scripts/test_analyzer.pyAnti-patterns in .spec.ts / .test.ts files (fixed sleeps, brittle CSS, non-retrying assertions) with line numbers and fixespath, --severity high|medium|low, --json0 no high findings; 1 high findings; 2 missing path or no spec files
scripts/coverage_mapper.pyMatches specs to user flows by keywords, URLs and names; lists gaps by priority--tests DIR, --flows FILE, --threshold 0.3, --gaps-only, --json0 report; 2 missing dir or invalid flows file
scripts/flaky_detector.pyStability per test across several Playwright JSON reports, with duration variance--results-dir DIR, --runs 10, --threshold 0.95, --json0 report; 2 no readable reports
scripts/test_report_parser.pySummary of one Playwright JSON report: pass, fail, flaky, durations, slowest testsreport, --top-slow 5, --flaky-threshold 5, --json0 report; 2 unreadable report
scripts/page_object_generator.pyPage Object class from an HTML file or a selector list--html FILE | --selectors FILE, --name, --route, --json0 generated; 2 missing input
scripts/test_generator.pySpec skeleton (happy, validation and negative paths) from a user story--story TEXT --page NAME | --stories FILE, --route, --output DIR, --json0 generated; 2 bad input

Flows file: a JSON array of {"id", "name", "priority", "keywords", "pages", "steps"}; id and name are required (see assets/sample_flows.json). --gaps-only filters the listing; the summary always covers every flow. Reports are Playwright's JSON reporter output (--reporter=json).

Anti-Patterns

Mistake: Fixing a flaky test with waitForTimeout or more retries. Why it matters: Sleeps hide the race and slow every run; retries turn a real bug into a green build. Instead: Wait on the condition (expect(locator).toBeVisible(), waitForResponse) and isolate shared state; see skills/fix.md.

Mistake: Locating elements by CSS structure (div > input:nth-child(2)). Why it matters: Any layout change breaks the test even when the feature works. Instead: Use getByRole, getByLabel or getByText, then data-testid when nothing user-facing is stable.

Mistake: Asserting on a one-shot value (expect(await el.isVisible()).toBe(true)). Why it matters: It checks once, with no retry, so it fails on slow renders. Instead: Use web-first assertions that retry until the timeout: await expect(el).toBeVisible().

Reference Documentation

Load the reference that matches the task — keep this file lean and pull detail on demand:

  • references/core-rules-and-patterns.md — the 10 golden rules, locator priority, playwright.config.ts, Page Object Model classes, test generation from user stories, and shared-auth setup. Read when authoring tests or configuring a project.
  • references/playwright-patterns.md — locator decision tree, web-first vs non-retrying assertion patterns, custom/worker fixtures, network mocking, anti-pattern quick reference, and CI sharding patterns. Read when choosing locators, mocking APIs, or building fixtures.
  • references/diagnosis-migration-and-ci.md — flaky-test causes/fixes and diagnosis commands, Cypress→Playwright migration table, GitHub Actions CI, visual regression, accessibility testing, common pitfalls, best practices, troubleshooting table, and the success-criteria bar. Read when fixing flaky tests, migrating, wiring CI, or auditing a suite.

Files

FilePurpose
skills/*.mdNine sub-skill workflows (init, generate, fix, migrate, review, report, coverage, BrowserStack, TestRail)
scripts/*.pySix stdlib CLIs (see Tools Overview)
assets/tests/login.spec.tsClean spec; analyzer exits 0
assets/flawed_tests/profile.spec.tsFixed sleeps and brittle CSS; analyzer exits 1
assets/sample_flows.jsonThree user flows for the coverage mapper
assets/reports/run1-3.jsonThree Playwright JSON reports with one flaky and one failing test
assets/sample_login.htmlLogin form for the Page Object generator

Scope & Limitations

This skill covers:

  • End-to-end test authoring, organization, and maintenance with Playwright
  • Page Object Model architecture and locator strategy best practices
  • Flaky test diagnosis, CI integration, and trace-based debugging
  • Visual regression testing and WCAG accessibility auditing

This skill does NOT cover:

  • Unit testing or component testing in isolation (see engineering/senior-qa for test pyramid guidance)
  • API contract testing or load/performance testing (see engineering/api-test-suite-builder)
  • Test data management, database seeding, or factory patterns for test fixtures
  • Mobile native app testing (Appium, Detox); this skill targets web browsers only
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 321kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 321kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 321kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall