playwright page.waitForLoadState networkidle hangs: how to fix

TL;DR

networkidle only fires when the page has no network activity for 500ms, so pages with polling, websockets, or analytics beacons hang forever. Wait for 'load' or 'domcontentloaded' plus a locator assertion on the element you actually need.

The query

playwright page.waitForLoadState networkidle hangs: how to fix

Use this when

• waitForLoadState('networkidle') times out
• pages with live data hang tests
• CI-only hangs on busy pages

Not for

• pages that truly never finish their initial load
• API timeouts unrelated to page load
• slow test machines in general

Steps

1. Read the timeout error and confirm it names networkidle as the load state. Expected output: an error mentioning the networkidle load state timing out.
2. Open the page's network activity and look for repeating requests: polling, live updates, or tracking pixels. Expected output: at least one request repeating indefinitely.
3. Replace networkidle with 'load' and add an explicit assertion, e.g. await expect(page.locator('[data-testid="results"]')).toBeVisible(). Expected output: the test waits for the real readiness signal, not network silence.
4. If you own the polling, pause it under test via a query flag so the page settles. Expected output: no repeating requests during the test run.
5. Re-run several times to confirm the hang is gone and the test is stable. Expected output: consistent passes with no networkidle timeouts.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_NW3kVB0USpbZgYLahOSjXQ