playwright-cookbook

Use when testing a localized UI built with i18next and react-i18next, when deciding how to select a control whose text is translated, or when making the i18next setup type-safe so a bad t() key fails the build instead of shipping an empty string. Pairs the locator priority of playwright-locators with the test-id judgment of playwright-testid-strategy for the localized case.

Use when testing shadcn/ui components built on base (`@base-ui/react`) with Playwright, or when a review treats "we use shadcn, so accessibility is handled" as settled. Covers what the primitives give you (real roles, keyboard, focus traps) versus what stays application code (the accessible name), the portal scoping every overlay needs, and the surfaces where a test id hides a missing name.

Use when deciding whether a `data-testid` is justified, reviewing a PR that reaches for test ids, asserting that a conditional element is present or gone, or judging whether an aria-label is a real label or a test hook in disguise. Settles the "default or fallback" question that playwright-locators raises, with the cases where a test id is genuinely the only solution and the anti-patterns that hide accessibility bugs.

Use when building a new UI component or feature with its tests, hardening an existing component for testability, or adding component/e2e coverage. Co-designs accessible markup with role-first selectors so the query that finds an element also proves a real user can reach it, then drives a two-tier test matrix (jsdom component tests + Playwright/axe journeys). Triggers on "build a component", "add tests for X", "write tests", "make this testable", "cover this component".

Use when modelling reusable UI fragments (sidebars, headers, modals, table rows, cards) in Playwright tests, when the same locators appear on multiple pages, or when one feature renders differently across themes/frameworks/A-B variants. The container-rooted component pattern that composes anywhere without ceremony.

Use when a Playwright test fails and you need fast root-cause diagnosis using trace viewer, inspector, console/network evidence, and repeatable repro commands. Focuses on shortest path from failure to permanent fix.

Use when designing the fixtures.ts file for a Playwright suite, deciding between test-scoped and worker-scoped fixtures, composing fixtures together, providing options with defaults, or wiring page objects, components, and flows into specs. The DI layer that lets specs read like user stories.

Use when diagnosing flaky Playwright tests, deciding whether a flake is a real bug, configuring retries, working with the trace viewer, or auditing a suite for reliability. The diagnostic and the playbook for permanent fixes, and the answer to "our E2E tests are flaky."

Use when starting a new Playwright suite, restructuring an existing one, deciding where new test code should live, or onboarding a team to a maintainable convention. The spine of the playwright-skills pack. It defines the folder layout, the five non-negotiable rules, and how locators, components, pages, flows, and fixtures compose. Read this first.

Use when writing Playwright assertions, fixing tests that have `waitForTimeout` or sleeps, debugging timing-related flakes, polling for non-UI conditions, or asserting on URLs/network/state. Establishes the web-first assertion model that eliminates the entire class of timing flakes.

Use when setting up authentication for a Playwright suite, replacing per-test UI logins with a faster pattern, supporting multiple user roles in one suite, or handling OAuth/SSO. The storage-state pattern turns 30-second test setups into 10-millisecond ones and removes auth-related flakes.

Use when setting up Playwright in CI, sharding tests, caching browsers/deps, publishing artifacts, and enforcing quality gates for large suites. Covers deterministic, fast, debuggable CI execution.

Use when creating or refactoring playwright.config.ts, defining projects and dependencies, splitting smoke vs integration runs, setting retries/workers/timeouts, or hardening config for CI. Opinionated defaults and decision rules for config that scales.

Make Playwright tests fail on unexpected browser runtime errors, console errors, and critical failed responses. Use when adding console/pageerror guards, auditing false-green tests, or deciding which error signals should be asserted versus allowlisted.

Use when adding executable-stories-playwright to a Playwright suite, configuring its reporter, converting existing specs into BDD-style stories, generating user-story docs from tests, or embedding screenshots and recorded video into a test report. Turns ordinary `test()` blocks into living Markdown/HTML documentation with no `.feature` files and no step-definition glue.

Use when modelling user journeys that span multiple pages (login, signup, checkout, onboarding), when the same multi-step sequence is needed in many specs, or when deciding whether a sequence belongs in a page object vs a flow. Plain async functions with one job: orchestrate the journey and leave the assertions to the spec.

Use when choosing how to find elements in Playwright, refactoring CSS selectors to semantic ones, fixing locator-related flakes, deciding when a `data-testid` is appropriate, or working with iframes/shadow DOM. Defines the locator priority that makes tests resilient to markup changes.

Use when controlling network responses in Playwright tests, mocking external APIs (payments, email, third-party SDKs), removing flakes caused by upstream services, recording HAR files for replay, or deciding whether to mock vs. hit a real backend. Make test outcomes depend only on your code, not on the internet.

Use when deciding whether to create a page object, designing the API of one, refactoring page objects that have grown unwieldy, or removing page objects that aren't earning their keep. The Page Object pattern done with restraint: abstract when the page earns it, never before.

Design Playwright project matrices and tag taxonomy for selective local, PR, and nightly runs. Use when splitting smoke/integration/visual tests, adding setup dependencies, avoiding duplicated project coverage, or deciding how tests should be filtered in CI.

Use when creating, seeding, and cleaning test data for Playwright suites, especially under parallel execution. Defines deterministic factories, per-worker namespacing, and teardown discipline.

Use when designing for parallel test execution, debugging tests that fail only when run with others, isolating per-worker test data, deciding between `beforeAll` and fixtures, or making sure tests pass in any order. The discipline that keeps a parallel suite stable.

Add Playwright screenshot regression tests with deterministic rendering, scoped baselines, and CI-safe review policy. Use when adding `toHaveScreenshot`, debugging visual diffs, stabilizing snapshots, or deciding which UI regions should have visual coverage.