The wrong goal is zero breakage
Teams sometimes talk about wanting tests that 'never break'. That goal is counterproductive. A test suite that never breaks when the UI changes is not resilient — it is not testing anything meaningful.
The real goal is making maintenance fast, cheap, and obvious. When the checkout button label changes, the right outcome is a one-line update to a readable scenario file that goes through normal code review — not an hour of debugging selector failures across a sprawling test suite.
That distinction is everything. Teams that achieve durable E2E coverage do not have suites that never require updates. They have suites where updates are so cheap that maintenance never becomes a blocker.
Author at the level of user intent, not DOM detail
The most important decision in any E2E testing strategy is what level of abstraction to write at. Teams that write directly against DOM selectors will pay a maintenance cost every time a component moves, a label changes, or a layout shifts. Teams that write against stable product concepts — what the user clicks, what they fill in, what they expect to see — pay that cost far less often.
This is not about magic tooling. It is about discipline in authoring. A test that says 'Click Sign in, Fill email with qa@example.com, Expect Dashboard' is easier to update than a test that says 'click the button with class btn-primary inside the div with id auth-container'. One of those tests is describing user behavior. The other is describing the current DOM.
- Use button labels and field names as selectors where possible — they are tied to product intent, not layout
- Add stable `data-assert` attributes to important controls that do not have natural labels
- Avoid selectors that depend on CSS class names, positional relationships, or component internals
- Review test files in PRs alongside the UI changes that affect them
Keep test definitions in the repo
A test artifact that lives outside the repo is a test artifact that will fall out of sync with the product. Version history, peer review, and the discipline of treating test changes like code changes are the structural habits that keep a suite healthy over time.
This is especially important when UI changes happen frequently. If test updates go through the same pull request as the UI changes that require them, the team builds a culture where maintenance is just part of shipping — not a separate, deferred task that accumulates into a crisis.
What Assert changes about this workflow
Assert keeps the scenario — the human-readable description of what the user does — as the primary artifact in the repo. When the UI changes, engineers update the scenario file in plain English. Assert regenerates the Playwright execution layer from the updated scenario.
This does not eliminate maintenance, but it changes the nature of it. Instead of hunting through selectors and debugging which DOM node no longer matches, the engineer makes a readable change that another engineer can review in thirty seconds. The cognitive cost of maintenance drops significantly.
FAQ
Should engineers update tests when the UI changes?
Yes, always — and ideally in the same pull request as the UI change. A test that is not updated when the product changes is not protecting anything; it is either failing (and creating noise) or it was written at a level too abstract to notice the change (and is now less valuable than it looks).
Are stable selectors enough by themselves?
They help significantly and are worth investing in, but they are not sufficient on their own. Stable selectors reduce selector-level breakage, but they do not address the larger problem of intent legibility. If nobody can read a test and understand what user behavior it is protecting, the team will make poor decisions about when to update, fix, or delete it.
What is the most common mistake teams make when maintaining E2E suites?
Deferring maintenance. When a test breaks during a UI change, the tempting shortcut is to skip or delete it rather than update it properly. Over time, this leaves the suite full of gaps where coverage used to be. The fix is making updates cheap enough that skipping them is not tempting — which is fundamentally an authoring and workflow problem.
Put the workflow in your repo, not in a chat transcript
Assert is strongest when scenarios become durable project assets: readable Markdown in the repo, generated execution underneath, and result inspection in the dashboard.