What are the most important Playwright best practices?

Good Playwright tests are short, deterministic and written in the language of the user. Most maintenance problems come from brittle selectors, manual sleeps, shared data and tests that assert implementation details instead of outcomes.

The practices that matter most

• Prefer role, label and text locators over CSS paths and test IDs
• Never use fixed sleeps; use web-first assertions and auto-waiting
• Keep tests independent with fresh contexts and unique data
• Assert on user-visible outcomes, not internal state or hook calls
• Use fixtures for setup and teardown instead of repeated beforeEach blocks
• Keep page objects thin and leave assertions in the test
• Record a trace on first retry and review failures instead of retrying blindly
• Run the fast suite on every commit and the full browser matrix on a schedule

test("filters active invoices", async ({ page }) => {
  await page.goto("/invoices");

  await page.getByRole("button", { name: "Active" }).click();

  await expect(page.getByRole("row")).toHaveCount(3);
  await expect(page.getByRole("row").first()).toContainText("Active");
});

Structure matters as the suite grows. Group tests by feature, share domain-specific fixtures, and keep one clear reason to fail per test. A test that checks five unrelated things produces a vague failure and slows down diagnosis.