Playwright best practices

Condensed, opinionated guidance for writing Playwright tests that are readable, isolated, and resilient — built for coding agents, around Playwright's agent CLI (playwright-cli) and its no-GUI debugging flows. Maintained by Checkly — the same practices apply whether you run these tests in CI or as production monitors.

Load a reference file from references/ only when the task needs it (see routing table). Each reference ends with links to the full /learn articles for depth.

Scope: all guidance assumes the @playwright/test test runner with TypeScript — its test, fixtures, projects, config, and web-first expect. Examples are TypeScript (.spec.ts); the same APIs work in JavaScript. It does not target the standalone playwright automation library (which has no test runner, fixtures, or auto-retrying assertions). Imports are import { test, expect } from '@playwright/test'.

The agent CLI is what makes this skill shine. Playwright's agent CLI — playwright-cli, package @playwright/cli — is a separate, token-efficient, no-GUI browser you drive command by command to discover locators and step through failing tests. It's distinct from the standard npx playwright CLI, and the Agentic workflow below leans on it throughout. → references/debugging.md

Core rules (always apply)

1. Locator priority: prefer user-facing locators — getByRole > getByLabel / getByPlaceholder / getByText > getByTestId > CSS/XPath. CSS/XPath tie tests to implementation and break easily. → references/locators.md
2. Web-first assertions: use auto-retrying expect(locator).toBeVisible() / toHaveText() etc. Never assert on a one-shot value you pulled out manually (innerText() then toBe). → references/assertions.md
3. No hard waits: never waitForTimeout(). Trust auto-waiting actions and web-first assertions; for explicit waits use waitForURL / waitForLoadState / waitForResponse. Avoid networkidle. → references/waiting.md
4. Isolated & independent: each test sets up its own state and can run in any order, in parallel. No test depends on another. Provision state via API in setup, not through the UI. → references/test-structure.md, references/flakiness.md
5. One feature per test: if a test's assertions span more than one feature, split it. Keep tests short and focused.
6. Reuse auth, don't re-login: sign in once, persist storageState, reuse it across tests via a setup project. → references/auth.md