Cutting Playwright Test Maintenance to Near Zero
Playwright maintenance eats sprints one broken locator at a time. The practices that cut it, in payoff order, and the honest floor where the model stops.
Playwright maintenance rarely arrives as a crisis. It arrives as a tax: two specs fixed here after a redesign, a helper rewritten there after an auth change, until someone counts the hours and finds the suite consuming a meaningful slice of every sprint. The good news is that most suites are far from the maintenance floor, and disciplined structure gets you a long way down. The honest news is that the floor is not zero, and we will be clear about where it sits.
1. Make locators resilient before anything else
Most maintenance is locator repair, so this is where the payoff lives. Prefer user-facing locators (getByRole, getByLabel, getByText) over CSS chains and XPath: they bind the test to what a user perceives instead of how the DOM happens to be structured, and they survive refactors that would kill a class-based selector. Where semantics are not enough, agree on data-testid attributes with the frontend team and treat them as a public contract: removing one is a breaking change and should fail code review. A suite that mixes brittle selectors with resilient ones gets the maintenance bill of the worst locator in each test.
2. Centralize what changes together
When the login page changes, the fix should live in one file. Page objects (or lightweight fixture helpers, the pattern matters less than the discipline) exist so that UI knowledge is written once. The smell to hunt for is the same locator string appearing in more than one spec; every duplicate is a future double-fix. The same applies to flows: one signUp() helper beats fifteen inlined signup sequences, because product flows change more often than test intent does.
3. Kill timing repairs at the root
If your team regularly "fixes" tests by extending timeouts or adding waits, that is maintenance spent making flakiness quieter. Playwright's auto-waiting handles most timing when tests assert on user-visible outcomes, so hard-coded waits usually mark a place where the test asserts on the wrong thing. Our guide to why your Playwright tests are flaky covers the mechanics; the maintenance angle is simple: flaky tests get "repaired" over and over, and stable tests get repaired when the product changes, which is much rarer.
4. Contain authentication once
Auth changes break suites broadly because auth touches every authenticated test. Move login into a setup project with storageState, keep exactly one real login test, and auth changes stop being a suite-wide event. The full setup is in our authentication guide.
5. Delete tests like you delete code
Suites grow monotonically because deleting a test feels like losing coverage. It is not; it is losing cost. A quarterly pass that removes tests for retired features, merges near-duplicates, and demotes low-value paths does more for the maintenance bill than any tooling. If nobody can say what a test protects, it protects nothing and bills you anyway.
The floor, and what sits below it
Do all of the above well and maintenance drops sharply. It does not reach zero, because the model has a floor: tests are code that encodes the UI's structure, and someone updates that encoding when the product moves. Resilient locators lower how often; nothing in the framework model changes whether.
Below that floor there is a different model rather than a better practice. TesterArmy runs flows described in plain English ("sign up with email, complete onboarding, upgrade to Pro") with an agent that looks at the rendered page on every run, so a moved button or a rebuilt DOM is something it sees and handles rather than something that breaks an encoded selector. There is no suite to structure, and the maintenance surface shrinks to keeping flow descriptions in sync with what the product does, which changes far less often than how the product renders. When a run fails, the evidence arrives assembled: recording, step trace, screenshots, and a check on the pull request. The comparison with the framework model is laid out honestly in TesterArmy vs Playwright.
A reasonable path many teams take: apply sections 1-5 to the suite you have, and point an agent at the flows that generate the most repair work. Run both, measure a month of fix-time, and let the numbers decide what migrates. (A structured tour of the options, including the ones that keep tests as code, is in the best Playwright alternatives.)
FAQ
How much time does Playwright maintenance take? It varies too much to give an honest universal number; the useful move is measuring your own. Tag test-repair commits or track them for one sprint. Teams are routinely surprised by the total, which is exactly why we wrote about the hidden tax of test maintenance.
Do self-healing tools fix this? Locator-healing tools reduce repair effort within the framework model; the suite and its ownership remain. What "self-healing" does and does not mean is its own topic: Self-Healing Tests: Real vs Marketing (month 2).
