Stable selectors and auto-waiting in browser end-to-end tests

Goal

Remove the two dominant causes of flaky browser tests: selectors that break on markup changes or match the wrong element, and timing assumptions that fail on a slower runner or network. The general procedure for flaky tests is a separate entry; this one is specific to browser suites.

Prerequisites

A browser automation framework with locators and auto-waiting (Playwright, Cypress or similar); an application whose controls have accessible names; test data that can be created per test so pages start in a known state.

Steps

1. Locate elements the way a user perceives them. Playwright's documentation recommends role-based locators (a button named "Sign in", a textbox labelled "Email") and states that CSS and XPath are not recommended because the DOM changes often; test ids are described as the most resilient option but not user-facing, so they suit controls with no stable accessible name.
2. Make every locator resolve to exactly one element. Playwright locators are strict and raise an error when several elements match; prefer filtering on text or a container over first() or nth(), which pick by position and follow a reordered DOM without complaint.
3. Never sleep. Playwright actions wait for actionability checks (visible, stable, receives events, enabled, editable as applicable) before acting, and assertions such as toBeVisible or toHaveText retry until the condition holds or the timeout expires. Cypress documents that queries and assertions retry while most commands such as .click() are not retried, so an assertion placed before an action is the synchronisation point.
4. Wait on effects, not on time: after a submit, assert on the resulting URL, text or network response before continuing.
5. Keep tests independent: create needed data through an API or seed, authenticate with a stored session instead of the login form, and never rely on another test having run.
6. Handle animation and overlays explicitly: assert that an overlay is gone before clicking behind it. Playwright's stability check requires the same bounding box for two consecutive animation frames.
7. Use automatic retries only while diagnosing, with traces and videos collected, and remove them once the cause is fixed.

Expected result

Failures reflect real regressions; tests survive markup refactors that keep the accessible structure; suite runtime falls because fixed sleeps are gone.

Limits and test basis

Role-based locators need accessible markup, which is a product requirement in its own right. Auto-waiting cannot help an application that renders stale content and replaces it later; such pages need an explicit loaded state. Timeouts still exist and still fire on an overloaded CI runner. No measurement is claimed.