Playwright web-first assertions retry: what the 5-second budget actually covers.

Two things, and it is important to separate them. One: the locator query itself. Playwright re-queries the DOM for elements matching the selector on every poll, so if a hydration step renders a new button, the retry engine picks it up. Two: the matcher check. toBeVisible reads the element's bounding box, offsetParent, and CSS visibility and returns pass or fail. Both happen on the same timer, defaulting to 5000 ms, polling roughly every 100 ms. What it does NOT do: synthesize a different selector, pick a different element if the current one is wrong, or retry at the scenario level. If the locator string was wrong at millisecond 1, it is still wrong at millisecond 4999. The retry engine is a loop that re-runs the same query, not a planner that can change strategy.

The default sits in the Playwright test runner config under expect.timeout (5000 ms). It is separate from action timeout (default 30 seconds, used by click, fill, waitFor) and test timeout (default 30 seconds for the whole test). The 5-second number was chosen as a compromise: long enough to absorb typical React hydration and network-bound UI changes, short enough that a truly broken selector fails fast in CI. If you are testing flows with a genuine wait (chat streaming, big GraphQL queries, server-side rendering), bump it per-assertion with .toBeVisible({ timeout: 15_000 }) rather than globally; global increases tend to hide real regressions. If you find yourself raising it to 30 seconds, the problem is usually not timing, it is locator fragility.

Three different tools for three different layers. toBeVisible (and the other web-first matchers) retries inside a single matcher on a single locator. expect.poll wraps any async function and retries it until the returned value passes a matcher, so you can do expect.poll(() => fetchCount()).toBeGreaterThan(0) with a custom interval and timeout. expect.toPass wraps an entire block of code, retrying the whole block (several actions plus assertions) until it throws no exceptions or the budget expires. The escalation ladder is: web-first matcher for visibility-class checks, expect.poll for single-value polling with custom intervals, expect.toPass for compound sequences. All three share the same underlying retry engine and all three have the same limitation: they cannot rewrite the selector or the request body you passed in.

It does retry fast internally, roughly every 100 ms, but it does not fail fast. Each poll either returns pass (exit early and succeed) or continues silently. There is no halfway signal. If the matcher is checking a locator that does not exist in the current DOM, you will burn the full 5000 ms before seeing the error. This is one of the most surprising behaviors for engineers coming from Cypress, where assertions have a shorter default and retry is more visible. Mitigations: set a shorter per-assertion timeout when you expect immediate pass/fail; use .first() to narrow strict-mode ambiguity; prefer role-based selectors over CSS so a class rename does not invalidate the locator.

Two complementary tiers. Tier one is Playwright's web-first retry, which Assrt keeps because the agent drives a real @playwright/mcp@0.0.70 browser under the hood. Tier two is wait_for_stable, defined in /Users/matthewdi/assrt-mcp/src/core/agent.ts at lines 956-1008. It does something Playwright cannot: it injects a MutationObserver into the page, counts DOM mutations per 500 ms tick, and only proceeds when no mutations have occurred for a configurable stable window (default 2 seconds, clamped to 10 seconds max). Timeout is clamped to 60 seconds max via Math.min((toolInput.timeout_seconds as number) || 30, 60). So instead of retrying a single matcher against a single locator for 5 seconds, the agent can wait for the whole page to go quiet, then re-snapshot the accessibility tree to get fresh element refs. When that fails, the tool error handler at agent.ts lines 1014-1017 automatically injects the first 2000 characters of a fresh a11y snapshot into the agent's next message, so the retry uses an updated view of the page. That last step is the one web-first retry cannot do: it changes strategy, not just timing.

A typical post-action sequence: the agent clicks Submit, calls wait_for_stable with timeout_seconds 30 and stable_seconds 2, the MutationObserver ticks every 500 ms until 4 seconds of DOM activity calms to 2 seconds of quiet (elapsed 6 seconds), then the agent calls snapshot to get a fresh a11y tree, finds the new heading by role and accessible name, and calls the assert tool with description, passed, and evidence. If the selector drifted (button was renamed "Log in" instead of "Sign in"), the assertion fails with evidence pointing at the rename, not at a timeout. Contrast with a web-first retry: you would see Error: Timed out 5000ms waiting for expect(locator).toBeVisible() and have to open the trace viewer to learn that the button got renamed. The evidence string saves the 5 minute diagnostic loop.

All of them, unchanged. Assrt does not monopolise the browser or touch your .spec.ts files. It runs its own chromium instance via @playwright/mcp. You can keep toHaveScreenshot pixel diffs, keep expect.poll loops for waiting on backend work, keep .spec.ts files for tests where the selector is stable and the retry budget is fine. Add scenario.md files for the tests that are flaking because the AI-written selector drifts, or because the page has a long async settle and you want DOM-quiet semantics instead of a fixed 5 second poll. The two coexist, they do not compete.

The agent runtime, the MCP server, and the CLI are all open source under /Users/matthewdi/assrt and /Users/matthewdi/assrt-mcp. Tests are plain markdown (scenario.md with #Case N headers and English steps). The execution log is plain JSON on disk at /tmp/assrt/<runId>/events.json. No proprietary YAML, no cloud-only database. If you cancel, your scenarios and evidence remain on disk. A Playwright-literate engineer can translate a scenario.md back into a .spec.ts by hand in 15 minutes. This matters compared to QA SaaS vendors that store tests in their cloud for $7,500 per month: your tests are never exportable from them.