Advanced

Playwright Best Practices

Playwright best practices for stable locators, meaningful assertions, independent tests, clean data, useful reports, and CI-ready automation frameworks.

Reliability Rules

A reliable Playwright test checks one clear behavior, interacts with the page like a user, waits for real application state, and gives useful evidence when it fails.

  • Prefer role, label, text, and test id locators over fragile CSS paths.
  • Replace fixed waits with assertions or specific event waits.
  • Keep tests independent so they can run in any order and in parallel.
  • Assert the result that matters to the user or system.

Locator Best Practices

Locators decide how stable your test will be. A good locator describes intent, not page layout.

Good locator style

await page.getByRole('button', { name: 'Save' }).click();
await expect(page.getByText('Saved')).toBeVisible();

Explanation: The test targets the Save button by accessible role and verifies the result after the action.

  • Use getByRole for buttons, links, headings, checkboxes, and dialogs.
  • Use getByLabel for form fields.
  • Use test ids when the UI text is unstable or not user-facing.
  • Use CSS or XPath only when better locator options are not available.

Assertion Best Practices

Assertions should prove the behavior, not only prove that code executed.

Wait through assertion

await page.getByRole('button', { name: 'Load orders' }).click();
await expect(page.getByRole('table', { name: 'Orders' })).toBeVisible();

Explanation: The assertion waits for the table that proves orders loaded.

  • Use retrying expect assertions.
  • Assert visible UI, URL, response, count, or persisted state.
  • Do not assert too many unrelated things in one test.

Test Data and Isolation

Good test data keeps tests repeatable. Each test should be able to run alone, in parallel, and multiple times without corrupting another test.

  • Create data through API setup when possible.
  • Use unique names or IDs for generated data.
  • Avoid sharing one mutable account across parallel tests.
  • Clean up only when cleanup itself is reliable.

CI and Debugging Practices

CI failures must be easy to understand. Reports, traces, screenshots, and videos should help you see what happened without guessing.

  • Enable trace on retry or failure.
  • Save HTML reports as CI artifacts.
  • Use retries carefully and investigate repeated flakes.
  • Run a smaller smoke suite before the full regression suite when needed.

Anti-Patterns to Avoid

  • Fixed waits such as waitForTimeout in normal tests.
  • Force clicks used to hide real UI or locator problems.
  • Very long tests covering many features together.
  • Page objects that hide assertions and make failures hard to read.
  • Over-mocking so the UI no longer tests real integration behavior.

Practice Checklist

  • Can this test fail for only one clear reason?
  • Are the locators readable and stable?
  • Is there a meaningful assertion after every important action?
  • Can this test run safely in parallel?
  • Will the failure report tell me what went wrong?
☰