Playwright · Reliable end-to-end tests
When should you use expect.poll?
Short answer
Use expect.poll to retry a function that reads state outside a locator, such as an API response, a file or a database. Locator assertions already retry and are preferable for DOM checks.
Web-first assertions can only retry against locators and pages. If the thing you need to verify lives in an HTTP response, a queue or a file, you wrap the read in expect.poll. Playwright calls the function repeatedly until the value matches or the timeout expires.
await expect.poll(async () => {
const response = await request.get("/api/jobs/42");
const body = await response.json();
return body.status;
}, { timeout: 15000 }).toBe("complete");Good uses
- Waiting for an asynchronous backend job to reach a terminal state
- Checking a value that is written to a file or an external store
- Asserting on a plain value produced by a helper or a page evaluate
- Verifying that a mocked counter was called the expected number of times
Keep the polled function fast and side-effect free. If it creates data or triggers a job, repeated calls can produce duplicates. Polling is a waiting mechanism, not a retry policy for failed operations.
expect.poll to replace a locator assertion. expect.poll(() => locator.textContent()) is worse than expect(locator).toHaveText(...) because it bypasses actionability and produces a less useful failure message.Follow-ups you should expect
Interviewers use these to check whether the first answer was understanding or memorisation.
- 1How is expect.poll different from waitForTimeout?
- 2Can expect.poll assert on a locator's text?
- 3What timeout and interval can you configure?
- 4Why should the polled function avoid side effects?
Say it in the interview
The poll assertion is for state that is not a locator, like an API response or a background job status. It calls my function repeatedly until the assertion passes or it times out. For DOM state I stick with locator assertions, which already retry and understand actionability. I keep the polled function cheap and read-only so repeated calls do not create duplicate data.
Use this as a model, not a script. Saying it in your own words is what makes it survive follow-up pressure.
Related questions
Reading is step one
Now say it out loud.
Understanding an answer and delivering it under pressure are different skills. Rehearse this topic in a live Playwright mock interview and get scored feedback on depth, clarity and confidence.