QA Testing (Playwright)

High-signal, cost-aware E2E testing for web applications.

Core docs:

• https://playwright.dev/docs/best-practices

• https://playwright.dev/docs/locators

• https://playwright.dev/docs/test-retries

• https://playwright.dev/docs/trace-viewer

• https://playwright.dev/docs/test-sharding

• https://playwright.dev/docs/ci

Defaults (2026)

• Keep E2E thin: protect critical user journeys only; push coverage down (unit/integration/contract).

• Locator priority: getByRole → getByLabel/getByText → getByTestId (fallback).

• Waiting: rely on Playwright auto-wait + web-first assertions; no sleeps/time-based waits.

• Isolation: tests must run alone, in parallel, and in any order; eliminate shared mutable state.

• Flake posture: retries are a debugging tool; treat rerun-pass as a failure signal and fix root cause.

• CI posture: smoke gate on PRs; shard/parallelize regression on schedule; always keep artifacts (trace/video/screenshot).

Quick Start

Command

Purpose

npm init playwright@latest

Initialize Playwright

npx playwright test

Run all tests

npx playwright test --grep @smoke

Run smoke tests

npx playwright test --project=chromium

Run a single project

npx playwright test --ui

Debug with UI mode

npx playwright test --debug

Step through a test

npx playwright show-trace trace.zip

Inspect trace artifacts

npx playwright show-report

Inspect HTML report

When to Use

• E2E tests for web applications

• Test user authentication flows

• Verify form submissions

• Test responsive designs

• Automate browser interactions

• Set up Playwright in CI/CD

When NOT to Use

Scenario

Use Instead

Unit testing

Jest, Vitest, pytest

API contracts

qa-api-testing-contracts

Load testing

k6, Locust, Artillery

Mobile native

Appium

Authoring Rules

Locator Strategy

// 1. Role locators (preferred)

await page.getByRole('button', { name: 'Sign in' }).click();

// 2. Label/text locators

await page.getByLabel('Email').fill('user@example.com');

// 3. Test IDs (fallback)

await page.getByTestId('user-avatar').click();

Flake Control

• Avoid sleeps; use Playwright auto-wait

• Use retries as signal, not a crutch

• Capture trace/screenshot/video on failure

• Prefer user-like interactions; avoid force: true

Workflow

• Write the smallest test that proves the user outcome (intent + oracle).

• Stabilize locators and assertions before adding more steps.

• Make state explicit: seed per test/worker, clean up deterministically, mock third-party boundaries.

• In CI: shard/parallelize, capture artifacts, and fail fast on rerun-pass flakes.

Debugging Checklist

If something is flaky:

• Open trace first; identify whether it is selector ambiguity, missing wait, or state leakage.

• Replace brittle selectors with semantic locators; replace sleeps with expect(...) or a targeted wait.

• Reduce global timeouts; add scoped timeouts only when the product truly needs it.

• If it only fails in CI, look for concurrency, cold-start, CPU starvation, and environment differences.

Do / Avoid

-

Make tests independent and deterministic

-

Use network mocking for third-party deps

-

Run smoke E2E on PRs; full regression on schedule

-

"Test everything E2E" as default

-

Weakening assertions to "fix" flakes

-

Auto-healing that weakens assertions

Execution Preflight (High ROI)

Run this preflight before expensive E2E runs to prevent avoidable failures.

Preflight Checklist

• Repository shape:

• Confirm working directory and expected app root exist.

• Verify spec paths before execution (rg --files tests/e2e | rg <target>).

• Port/process hygiene:

• Check and clear stale dev server port before run (example: lsof -i :3001).

• Avoid parallel local servers colliding with Playwright webServer.

• Command validity:

• Validate CLI flags for current tool versions before batch runs.

• Prefer exact spec paths or --grep over broad globs during triage.

• Artifact expectations:

• Confirm result artifact paths exist before reading (test -f <error-context.md>).

• If artifact path missing, inspect latest test-results index first.

Mandatory Sandbox/Port Decisions

Before running Playwright in constrained environments (sandboxed terminals, CI containers, shared dev hosts), decide and document:

• Bind host/port: confirm whether app server must use 127.0.0.1 or 0.0.0.0, and verify selected port is free.

• Escalation path: if bind attempts fail with EPERM/EACCES, escalate immediately instead of retry loops.

• Long-flow timeout budget: set explicit per-test timeout for API-heavy flows (generation/checkout/report) instead of inflating global timeout.

• Build lock hygiene: clear stale .next/lock and terminate stale build/dev PIDs before rerun.

Triage Sequence (Fastest Signal)

• Reproduce one failing test with --workers=1.

• Capture trace/video/screenshot for that single failure.

• Fix determinism root cause.

• Re-run targeted suite.

• Only then run broad regression.

Failure Patterns to Treat as Environment, Not Product Bugs

• EADDRINUSE on Playwright web server port

• Missing spec/result paths from stale assumptions

• Shell glob expansion failures for bracketed route segments

Resources

Resource

Purpose

references/playwright-mcp.md

MCP & AI testing

references/playwright-patterns.md

Advanced patterns

references/playwright-ci.md

CI configurations

references/playwright-authentication.md

Auth patterns and session management

references/visual-regression-testing.md

Visual regression strategies

references/api-testing-playwright.md

API testing with APIRequestContext

references/playwright-preflight-sandbox.md

Sandbox/port preflight and escalation decisions

data/sources.json

Documentation links

Templates

Template

Purpose

assets/template-playwright-e2e-review-checklist.md

E2E review checklist

assets/template-playwright-fail-on-flaky-reporter.js

Fail CI on rerun-pass flakes

assets/template-playwright-preflight-checklist.md

Preflight checklist for port/sandbox/timeouts

Related Skills

Skill

Purpose

qa-testing-strategy

Overall test strategy

software-frontend

Frontend development

ops-devops-platform

CI/CD integration

Fact-Checking

• Use web search/web fetch to verify current external facts, versions, pricing, deadlines, regulations, or platform behavior before final answers.

• Prefer primary sources; report source links and dates for volatile information.

• If web access is unavailable, state the limitation and mark guidance as unverified.