Building a Playwright Framework Your Team Won't Abandon in 6 Months

An Automation framework survives when a green run is trusted enough to gate a release, and that trust is an architecture outcome, not a discipline outcome. These are the decisions we make in every Playwright build so the suite is still alive in a year.

Selector strategy is a contract, not a habit

Standardize on data-testid attributes agreed with the frontend team, enforce them in code review, and ban text/CSS-position selectors in the framework lint rules. Flake starts where selectors depend on layout.

Design for parallel from day one

• Every test creates its own data, no shared users, no shared carts
• API-based setup and teardown; the UI is for the behavior under test, not for arranging state
• Storage-state login once per worker, never a UI login per test

Treat flake as a defect class

Quarantine flaky tests automatically, track a flake-rate metric per suite, and fix or delete, a suite with 2% random failure is a suite nobody trusts at 2 a.m. on release night.

Hand over the framework, not a dependency

Documentation, naming conventions, and a 'write your first test' guide are deliverables. Our definition of done: the client team merges their own new test without asking us anything.