Waits and Flakiness Control

A test clicks Save, then looks for the success message — and fails intermittently with element not found, even though the message does appear, within half a second. The test is not broken and the app is not broken: they disagree about time. The click returned a 200 response, but React had not yet re-rendered, or the follow-up request to fetch the updated list was still in flight, or the CSS transition had not finished. The DOM your assertion reads is a snapshot of a system mid-update. Every flaky-timing failure you will ever triage has this shape.

The mechanics are worth making concrete. A modern click triggers: an HTTP round trip (50–300 ms locally, worse through VPN), response parsing, state update, virtual-DOM diff, browser paint. findElement/locators execute against the live DOM during that chain. A test asserting on the post-save state one millisecond after the click reads pre-save truth and calls it a defect. The race window is not large — it is unbounded on a loaded CI machine, where one more test in parallel adds a queue delay nobody predicted locally.

Failure taxonomy — read the message to name the gap:

NoSuchElementException            element not in DOM yet (render pending)
ElementNotInteractable / visible  element exists but is hidden/zero-size (CSS/animation pending)
ElementClickIntercepted           overlay (spinner, banner) still covering the target
assertion 'expected X' after timeout  state changed too late — wrong condition or genuinely broken

Each one points at a different wait you needed: presence, visibility, disappearance of an overlay, or none at all (a real bug).

Two wrong fixes dominate, and both fail in opposite directions. Fixed sleeps (Thread.sleep(2000), waitForTimeout(2000)) assume a distribution: 2 seconds is enough except when CI is loaded, VPN spikes, or a nightly data job locks the table — so the sleep is simultaneously wasted on 95% of runs and insufficient on the 5% that matter. It is not merely slow (2000 ms × 40 tests = 80 seconds of pure waiting per run); it teaches the team that flakiness is normal. The second wrong fix is retrying the action blindly — clicking five times until one works — which masks a genuinely broken button as cheerfully as a slow one, converting a real defect into a green run.

The right mental model: wait for the condition you actually care about, with a timeout that fails loudly. The condition is not "time has passed"; it is "the state that makes my next step meaningful is true" — the success message is visible, the URL is /orders/42, the button is enabled again after loading. This is called explicit waiting, and it couples your test's progress to the application's progress rather than to a wall clock. The next chapter covers the concrete APIs — Selenium's WebDriverWait with expected conditions, Playwright's auto-waiting and web-first assertions — but the principle is established here: synchronization bugs are diagnosed as timing gaps, never fixed as duration problems. A test that needs longer sleeps has not failed slowly; it has failed to explain what it was waiting for.

Explicit waiting means: poll (or be notified) until a named condition holds, or fail at a defined timeout with a message that names the condition that never came. Two ecosystems, two APIs, one principle.

Selenium: WebDriverWait with expected conditions.

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));

// wait for the element to be *present and visible* before acting
wait.until(ExpectedConditions.visibilityOfElementLocated(By.cssSelector("[data-testid='save-confirm']")));

// wait for a state change before asserting
wait.until(ExpectedConditions.urlContains("/orders/42"));

// wait for an overlay to LEAVE — the classic missed case
wait.until(ExpectedConditions.invisibilityOfElementLocated(By.cssSelector(".spinner")));

// negative condition: element is *supposed* to disappear
wait.until(ExpectedConditions.not(
    ExpectedConditions.presenceOfElementLocated(By.id("loading-indicator"))));

The fluent variant lets you tune the polling interval: new FluentWait<>(driver).withTimeout(10, SECONDS).pollingEvery(250, MILLISECONDS).ignoring(NoSuchElementException.class) — the .ignoring(...) clause matters: without it, the first NoSuchElementException from a not-yet-rendered element aborts the wait instead of being the thing being waited for. Default polling is ~500 ms, which is fine for UI; do not poll faster, it only burns CPU without reducing the actual wait much.

Playwright: the API makes the wait implicit — deliberately. Actions do their own five-condition actionability checks (from Writing First Playwright Tests), and assertions retry:

await expect(page).toHaveURL(/\/orders\/42/);            // navigation settled
await expect(page.getByTestId('save-confirm')).toBeVisible();  // render done
await expect(page.getByRole('button', { name: 'Save' })).toBeEnabled();  // form re-enabled
await expect(page.getByTestId('toast')).toBeHidden();      // overlay gone

This is why Playwright suites read without explicit waits: the assertion is the wait. Writing await page.waitForTimeout(1500) in Playwright is almost always a bug in the test — the exception is when you are waiting for something with no observable condition (a non-deterministic animation you truly must outlast), and even then waitForFunction on a concrete predicate beats a timeout.

Waiting on the network. Sometimes the correct condition is not a DOM node but the request: a filtered table can only be trusted after its fetch resolves. Options, in order of preference: wait for the observable outcome of the request (row text appears — most robust); intercept the specific response (page.waitForResponse(r => r.url().includes('/api/orders') && r.ok())) — precise and fast; or waitForLoadState('networkidle') — convenient but explicitly discouraged as a general strategy because "idle" is undefined for apps with polling, websockets, or analytics beacons, which never go idle. Match the wait to the state, and prefer outcomes over transport.

Timeout hierarchy. Set the per-test timeout as the outer bound (Playwright: timeout: 30_000 in config), then per-wait or per-action timeouts inside. When a wait times out, the error is your diagnosis: it names the condition, and with traces on, you see the last DOM state. A timeout message that says only "element not found after 30s" is a missing wait; a message that says "expected URL /orders/42, still at /checkout" is often a real defect. The quality of your failure messages is the quality of your debugging — which is the next topic's whole subject.

Anti-patterns to strike from review. "Wait for everything": wrapping every step in network-idle waits turns a 20-second suite into a two-minute one and still misses DOM-level timing. "Wait by polling the DOM in a loop": hand-rolled while (!elementExists()) loops re-implement WebDriverWait badly, usually without a timeout, hanging the suite instead of failing it. "One global magic number": a single 10-second constant applied everywhere hides which conditions are genuinely slow; prefer per-condition timeouts so an unusually slow payment gateway fails its wait with a clear message rather than starving the rest. And in Selenium specifically, never combine implicit waits (implicitlyWait(...)) with explicit ones in the same session — the implicit timeout applies to every findElement inside the explicit wait too, multiplying total delay and producing the infamous 10× wait-times-two failure mode that Selenium's own docs warn about.

Flakiness is a property, not an event: a test that passes on re-run but fails on first execution is reporting false information — and false information compounds. A green build with three flaky tests tells the team the suite is weaker than it looks; worse, engineers learn to re-run CI until green, at which point the suite has stopped gating anything. The discipline for handling this is quarantine: isolate the flaky test, keep it visible, fix it under a deadline — never delete, never hide.

First, measure, because "flaky" is often a mislabel. Three distinct things get called flaky:

1. Genuinely non-deterministic   same code, different outcome — timing, shared data, parallel collision
2. Order-dependent               passes alone, fails in the suite (leaked state, test dependencies)
3. Environment-broken           fails on one CI node, passes everywhere (DNS, browser version, cache)

They have different fixes, so classify before touching code. Playwright's --repeat-each=10 plus --workers=8 shakes out class 1; running the test alone versus after the full file exposes class 2; diffing the failing node's browser version and env config catches class 3. A one-line root-cause note per flaked test turns triage from archaeology into a list.

The quarantine mechanism. The standard shape: a separate tag or directory (@flaky / tests-quarantine/) excluded from the gating suite but still executed on a schedule with full artifacts, reported to a channel the team reads:

# gating pipeline — quarantined tests never block a deploy
npx playwright test --grep-invert @flaky

# nightly quarantine run — evidence continues to accumulate
npx playwright test --grep @flaky --repeat-each=5 --trace on

The properties that make this honest: the test keeps running (so you keep learning), it cannot block (so delivery is not held hostage), and its output stays visible (so nobody forgets it exists). The properties that make most teams' version dishonest: moving flaky tests to a file nobody runs, or silencing them — both are deletion with extra steps.

Retries are a seatbelt, not a strategy. CI retries (retries: 2) exist to keep a transient hiccup from wasting a developer's afternoon and to generate a trace of the intermittent state — Playwright records on-first-retry precisely for this. But every retry silently converts a red signal to green, so track the retry rate as a first-class metric: a suite at 6% retries is lying 6% of the time even when every final result is green. Teams that publish per-test flake rates watch them fall, because measurement is itself a fix — visible rot gets repaired.

Deadlines and ownership. Quarantine without an expiry is a graveyard. The convention that works: every quarantined test gets an owner and a date; if it is not stabilized within two weeks (pick your number), the team decides explicitly — fix now, rewrite at a different level (many UI flakes are better as API tests), or delete with a decision recorded. That last option is legitimate: a check that cannot be made reliable has negative value, because it trains the team to ignore red. What is never legitimate is leaving it half-alive. You now have stable locators and honest waits; the remaining skill is reading a failure correctly when it does happen — Debugging Failing Tests next.