Polling Wrappers

## Two wrappers, two units of retry Playwright gives you two ways to retry something that is not a locator assertion, and the whole choice comes down to **what** is retried. - `expect.poll(callback).toBe(value)` retries **one value and one matcher**. Playwright calls the callback, applies the chained matcher to the returned value, and repeats on failure. - `await expect(async () => { ... }).toPass()` retries **a block of code**. Playwright runs the callback body; if anything in it throws — an assertion, a parse, a request — the whole body is run again from its first statement. Everything else follows from that difference. ## expect.poll: retrying a value `expect.poll(fn, { timeout, intervals, message })` is the narrow tool. It is the right one when the question you are asking is genuinely a single comparison: *has this number reached 42 yet?* Its failure message is precise, because Playwright knows both the expectation and the last value it polled, so the report reads like an ordinary matcher mismatch rather than a stack trace. Its ceiling is equally clear: one callback return, one matcher. If you find yourself returning a tuple or a synthetic object just to assert three things at once, you have outgrown it — the failure will point at an object diff instead of the thing that was actually late. ## toPass: retrying a block `expect(async () => { ... }).toPass({ timeout, intervals })` inverts the shape. Inside the callback you write ordinary code, including ordinary throwing `expect` calls. A probe **succeeds** when the body returns without throwing; the first throw aborts that probe, Playwright waits an interval, and runs the body again. That makes `toPass` the escape hatch for conditions that are not one value: 1. Several assertions that must hold **at the same moment** — a settled balance *and* a complete transaction table, not one at a time. 2. Code that can throw rather than return a wrong value, such as parsing a payload that is briefly incomplete. 3. A check whose intermediate steps depend on each other, where re-deriving everything from scratch is the only sane retry. ## Side-by-side | | `expect.poll` | `toPass` | |---|---|---| | unit of retry | one callback's return value | the whole callback body | | assertions per attempt | exactly one chained matcher | as many as you write inside | | pass condition | the matcher passes | the body finishes without throwing | | default timeout | the expect timeout, 5 s | 0 — no timeout of its own | | default intervals | `[100, 250, 500, 1000]` ms | `[100, 250, 500, 1000]` ms | | failure message | matcher diff with the last value | whatever threw on the final attempt | | actions inside | should never be there | run again on every probe | ## Rules of thumb - If the check is **one value**, use `expect.poll`. The message alone is worth it. - If the check is **a conjunction**, use `toPass`, and keep the block to reads and assertions. - If a locator assertion already covers it, use **neither** — those retry on their own. - Whatever you choose, give it an **explicit timeout** when the wait is expected to be long, rather than letting the test timeout be the backstop. ## The costs of reaching for toPass by default - **Actions repeat.** A click, a fill, or a navigation inside the block fires on every probe. Sometimes harmless, often the reason the state never settles. - **Timeouts nest.** An auto-retrying locator assertion inside the block carries its own timeout, so a single probe can burn seconds before `toPass` gets to retry at all. - **Failures get vaguer.** You learn that the block did not pass, and see only the last thing that threw — not which condition was consistently late. - **It hides fine-grained flakiness.** Three assertions that each pass 90 % of the time look like one flaky block instead of three separate signals. Read this way, `toPass` is powerful precisely because it is coarse, and `expect.poll` is preferable precisely because it is narrow. Reach for the narrow one first, and let the coarse one earn its place.