waitFor

When auto-wait on a single action is not enough, Playwright provides explicit wait helpers tied to real browser events — not arbitrary delays.

Explicit Wait Tools

page.waitForURL() waits for navigation or SPA route changes. page.waitForResponse() waits for a matching network response — useful after actions that trigger fetches.

locator.waitFor({ state: 'visible' }) waits for a single locator state; often replaced by asserting with expect instead.

const responsePromise = page.waitForResponse('**/api/orders');
await page.getByRole('button', { name: 'Refresh' }).click();
const response = await responsePromise;
expect(response.status()).toBe(200);
await expect(page.getByText('Order #123')).toBeVisible();

Start waiting before the action that triggers the event.

Common waitFor APIs

page.waitForURL(url | RegExp)
page.waitForResponse(url | predicate)
page.waitForRequest(url | predicate)
page.waitForLoadState('load' | 'domcontentloaded')
locator.waitFor({ state: 'visible' | 'hidden' | 'attached' })

Register wait promises before triggering actions.
Predicate functions filter responses by method, status, body.
Prefer expect over waitFor when asserting final state.
waitForEvent('popup') handles new windows/tabs.

waitFor Reference

Pick the wait matching your condition.

API	Waits For
`waitForURL`	URL change
`waitForResponse`	Network response matching pattern
`waitForRequest`	Outgoing request
`waitForLoadState`	Page load phase
`locator.waitFor`	Locator state
`waitForFunction`	Custom JS predicate in page
`waitForEvent('download')`	File download

Waiting for Popups

const popupPromise = page.waitForEvent('popup');
await page.getByRole('link', { name: 'Open window' }).click();
const popup = await popupPromise;
await expect(popup.getByRole('heading')).toHaveText('Details');

waitForLoadState and Navigation

await page.waitForLoadState('networkidle') is rarely needed on SPAs with polling. Prefer waiting on specific locators or waitForURL after navigation.

Common Mistakes

Awaiting waitForResponse after click — race lost, register first.
Using waitForSelector with CSS when locator assertion suffices.
waitForLoadState('networkidle') on websocket SPAs.
waitForTimeout copied from Stack Overflow.

Key Takeaways

Explicit waits should target events or conditions.
Register network waits before triggering requests.
expect() often replaces locator.waitFor with better errors.
waitForEvent handles popups, dialogs, downloads.

Pro Tip

Wrap waitForResponse + click in Promise.all only when order is guaranteed — the 'promise first, then action' pattern is clearer for readers.