Production-grade Playwright testing skill for E2E suites, flaky test diagnosis, browser automation, migration from Cypress/Selenium, CI integration, visual checks, and regression validation.
Production-grade Playwright testing skill for E2E suites, flaky test diagnosis, browser automation, migration from Cypress/Selenium, CI integration, visual checks, and regression validation.
Use this skill to design, generate, review, debug, and stabilize production-grade Playwright test suites. It is the higher-discipline complement to a basic browser automation skill: focus on reliable assertions, maintainable fixtures, CI behavior, coverage strategy, and regression confidence.
When to Use
Creating a new Playwright suite for a web app.
Generating E2E tests from user stories, acceptance criteria, URLs, or existing manual QA steps.
Fixing flaky Playwright tests in local runs or CI.
Migrating Cypress, Selenium, Puppeteer, or manual smoke tests to Playwright.
Adding visual, accessibility, API-assisted, or cross-browser checks.
Integrating Playwright into GitHub Actions, CircleCI, Buildkite, Azure Pipelines, or other CI systems.
Skip When
The task only needs quick page inspection or a one-off screenshot.
Unit tests or integration tests would verify the behavior more cheaply and reliably.
There is no runnable app or stable target environment and the user does not want setup work.
The user explicitly asks to avoid browser automation.
Core Capabilities
Bootstrap a maintainable Playwright configuration.
Generate tests with resilient locators and web-first assertions.
Design fixtures for auth, test data, API setup, and cleanup.
Diagnose flakiness by timing, isolation, network, data, and selector stability.
Review tests for anti-patterns and weak assertions.
Migrate legacy suites while preserving behavior coverage.
Integrate reports, traces, screenshots, and videos into CI.
Build regression strategy around user-critical flows.
Recommended Workflow
1. Init: inspect framework, routes, auth, package manager, and test conventions.
2. Generate: write the smallest high-value tests for critical user paths.
3. Review: check locators, assertions, isolation, data setup, and failure diagnostics.
4. Run: execute locally in headless mode first, then headed for debugging if needed.
5. Stabilize: remove sleeps, isolate state, and add deterministic waits.
6. CI: shard, report, upload traces, and set retry policy.
7. Maintain: add regression tests for every escaped bug.
Project Setup Checklist
Install @playwright/test with the repo's package manager.
Keep Playwright config in the established test directory style.
Use one base URL per environment.
Store credentials and test secrets in environment variables.
Use webServer for local app startup when appropriate.
Enable traces on first retry.
Capture screenshots and videos only on failure unless visual review needs more.
Add HTML or blob report artifacts in CI.
Define projects for Chromium, Firefox, WebKit, mobile, or branded browsers only when they provide real coverage.
import { test, expect } from'@playwright/test';
test('user can sign in and reach the dashboard', async ({ page }) => {
await page.goto('/login');
await page.getByLabel('Email').fill('demo@example.com');
await page.getByLabel('Password').fill(process.env.E2E_DEMO_PASSWORD!);
await page.getByRole('button', { name: 'Sign in' }).click();
awaitexpect(page).toHaveURL(/dashboard/);
awaitexpect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
});
Prefer getByRole, getByLabel, getByText, and getByTestId over brittle CSS selectors. Add test IDs only where accessible locators are not stable or meaningful.
Locator Rules
Use user-facing locators first.
Prefer role plus accessible name for controls.
Avoid long CSS chains and nth-child selectors.
Avoid text locators for dynamic copy unless copy is the behavior under test.
Use data-testid for non-semantic UI, repeated rows, charts, or canvas-adjacent controls.
Keep locators close to assertions so failures are readable.
Do not locate hidden elements unless testing hidden state explicitly.
Assertion Rules
Use web-first assertions: toBeVisible, toHaveText, toHaveURL, toBeEnabled, toHaveCount.
Assert the user-visible outcome, not just that a button was clicked.
For API effects, assert through UI or a controlled API check.
Avoid arbitrary sleeps.
Avoid snapshots for highly dynamic content unless normalized.
Make negative assertions bounded and intentional.
Test one user behavior per test where practical.
Flaky Test Diagnosis
Classify the failure before fixing:
Timing: missing web-first assertion, racing navigation, animation, delayed API.
In larger suites, shard by CI node and keep trace artifacts for failures.
Review Checklist
Tests map to real user requirements.
Locators are accessible and resilient.
No arbitrary sleeps.
Each test has deterministic setup and cleanup.
Auth state is safe and isolated.
Assertions verify visible outcomes or durable side effects.
CI artifacts make failures diagnosable.
Retries are not hiding persistent bugs.
The suite can run locally without undocumented steps.
Visual tests have stable baselines and masking for dynamic regions.
Anti-Patterns
Testing implementation classes instead of user behavior.
Sharing one mutable test account across the whole suite.
Using page.locator('button').nth(3).
Waiting for network idle as a universal solution in apps with polling.
Overusing end-to-end tests for logic better covered by unit tests.
Ignoring failed trace artifacts.
Making the suite serial because data isolation is missing.
Testing third-party services live in every CI run.
Output Format
## Test Plan- Critical flows:
- Fixtures/data:
- Browser matrix:
- CI artifacts:
## Generated or Changed Tests- ...
## Flake Risks- ...
## Commands Run- ...
Boundaries
Do not store real credentials in tests. Do not hit production systems unless the user explicitly confirms the target and safety controls. Prefer local, staging, or mocked services for repeatable automation.
