Playwright Core Testing

Opinionated, production-tested Playwright guidance — every pattern includes when (and when not) to use it.

Golden Rules

1. getByRole()

   over CSS/XPath — resilient to markup changes, mirrors how users see the page
2. Never

   page.waitForTimeout()

   — use

   expect(locator).toBeVisible()

   or

   page.waitForURL()

3. Web-first assertions —

   expect(locator)

   auto-retries;

   expect(await locator.textContent())

   does not
4. Isolate every test — no shared state, no execution-order dependencies

5. baseURL

   in config — zero hardcoded URLs in tests
6. Retries:

   2

   in CI,

   0

   locally — surface flakiness where it matters
7. Traces:

   'on-first-retry'

   — rich debugging artifacts without CI slowdown
8. Fixtures over globals — share state via

   test.extend()

   , not module-level variables
9. One behavior per test — multiple related

   expect()

   calls are fine
10. Mock external services only — never mock your own app; mock third-party APIs, payment gateways, email

Guide Index

Writing Tests

Debugging & Fixing

Framework Recipes

Specialized Topics

Architecture Decisions