Guide ·
Playwright Wait for Page to Load in JavaScript and Python
"The page has loaded" can mean three different things: the HTML arrived, the browser fired the load event, or the data your test or script needs is on the screen. Playwright has a wait for each, and on modern apps only the last one is reliable. We timed every option on the same test page, and the default page.goto() returned more than a second before the content appeared.

Short answer
Navigate, then wait for the element that only exists once the page is ready:
This works on server-rendered sites and on single-page apps alike, and it is faster than networkidle. Use the other waits below only when there is no element to wait for.
Which wait to use
| What you are waiting for | JavaScript / TypeScript | Python |
|---|---|---|
| Content to appear | locator.waitFor() | locator.wait_for() |
| Content to appear, in a test | await expect(locator).toBeVisible() | expect(locator).to_be_visible() |
| A spinner or overlay to go away | locator.waitFor({ state: "hidden" }) | locator.wait_for(state="hidden") |
| A specific API call to finish | page.waitForResponse() | page.expect_response() |
| A redirect or route change after a click | page.waitForURL() | page.wait_for_url() |
| A JavaScript condition (flag, fonts, images) | page.waitForFunction() | page.wait_for_function() |
| The HTML to be parsed, nothing more | goto(url, { waitUntil: "domcontentloaded" }) | goto(url, wait_until="domcontentloaded") |
| Network quiet, on a page you do not control | waitForLoadState("networkidle") | wait_for_load_state("networkidle") |
The four load states
page.goto(), page.waitForURL() and page.reload() take a waitUntil option, and page.waitForLoadState() accepts three of the same values:
| Value | Resolves when | Good for |
|---|---|---|
commit | The response arrived and the document started loading | Checking status codes or headers; then wait for something specific |
domcontentloaded | The HTML is parsed and deferred scripts have run | Fast navigation when you wait for an element next |
load (default) | The load event fired: images, stylesheets and scripts in the HTML finished | Server-rendered pages |
networkidle | No network connections for at least 500 ms | Quick scripts on pages you do not control. Playwright marks it as discouraged |
None of these states knows about your app. A React or Vue page usually fetches its data after load, so the browser reports the page as loaded while it still shows a skeleton.
What we measured
To see the gap, we built a small test page that behaves like a typical SPA: the HTML shell loads a deferred script, the script calls /api/products, the API answers after 1.2 seconds, and the script then renders a .results list. One image on the page loads in 300 ms. We ran each wait 5 times with Playwright 1.65 and Chromium 156 on macOS (Apple silicon), with the test server on the same machine, and recorded the median time from goto() until the wait returned, plus whether .results was on the page at that moment.
| Wait | Median time | Content on the page? |
|---|---|---|
waitUntil: "commit" | 3 ms | No, in 0 of 5 runs |
waitUntil: "domcontentloaded" | 158 ms | No, in 0 of 5 runs |
waitUntil: "load" (default) | 311 ms | No, in 0 of 5 runs |
domcontentloaded + locator(".results").waitFor() | 1,465 ms | Yes, in 5 of 5 runs |
waitUntil: "networkidle" | 1,863 ms | Yes, in 5 of 5 runs |
Two things stand out. The default goto() returned an empty page every time. And networkidle did get the content, but it was 400 ms slower than waiting for the element. That is the 500 ms quiet window it needs after the last request. On a page with ten navigations, that adds up to several seconds per test.
Full benchmark script and raw output
One script reproduces every number in this article: the load-state table, the waitForResponse() timing, the polling page and both timeouts. Nothing in it sets a timeout, so the 30-second results are Playwright's defaults.
Output of the run used in this article (MacBook, Apple silicon, Node.js 24, test server on the same machine):
These are timings for this one synthetic page on a local server. On real sites, the gaps depend on how late the app fetches its data and how much background traffic it has, so measure your own pages before choosing a wait.
Why networkidle is discouraged
Playwright's own docs mark networkidle as discouraged and tell you not to use it for testing. Being slow is the smaller problem. The bigger one is that many real pages never go quiet. Analytics beacons, chat widgets, live dashboards and ad scripts keep sending requests, so the 500 ms window never comes.
We added a second test page that polls /api/ping every 400 ms, like a dashboard that refreshes itself. Its heading is in the HTML, so the page is usable right away:
With networkidle, goto() waited the full 30-second default timeout and then threw. That is where most "works on my machine, times out in CI" reports about networkidle come from: a tag manager or chat widget that is only enabled on staging or production.
When networkidle is still fine: one-off scripts against pages you do not control and cannot inspect, where there is no obvious element to wait for. If you use it, set a short timeout and catch the error, so a page that never goes quiet does not block the whole run.
Wait for an element: locator.waitFor and waitForSelector
Pick an element that only appears when the page is ready: the first row of a table, a product price, a chart container, a "Welcome back" heading. Waiting for it answers the real question directly.
The four states are visible, hidden, attached and detached. page.waitForSelector() still works and takes the same states, but it returns an element handle, and the Playwright docs now point to locators and web-first assertions instead. In new code, use locator.waitFor().
Inside Playwright Test, an assertion does the same job and reads better:
You often do not need an explicit wait before an action. Locator actions such as click() and fill() already wait until the element is ready for that action. Which checks each action runs, and how this compares with Puppeteer, is covered in Playwright vs Puppeteer. You need an explicit wait when you read something (text, a count, a screenshot) rather than act on it.
Wait for an API response
When the content comes from one known request, wait for that request. Start waiting before the action that triggers it; otherwise a fast response can arrive before your listener exists, and the wait hangs until the timeout.
One catch: a finished response is not a rendered page. In our test, waitForResponse() returned at 1,364 ms, and the framework still has to turn the JSON into DOM after that. In our tiny page the list was already there, but on a heavy React page it may not be. If you read the screen next, add a locator.waitFor() after the response wait.
Use page.waitForRequest() the same way when you only care that a call was sent, for example an analytics event.
Wait after a click that navigates
Older guides use page.waitForNavigation(). It is deprecated because it is racy: if the navigation finishes before the call, it waits forever. Use page.waitForURL(), which also returns at once if the URL already matches:
waitForURL() also catches client-side route changes made with the History API, so it works in SPAs where no full page load happens.
For a link that opens a new tab, wait for the popup and then for its load state:
Common mistake: await page.waitForLoadState() right after page.goto() does nothing. goto() has already waited for load, so the call returns at once (1 ms in our run). It is useful after a click that navigates, or on a popup, not after goto().
Custom ready signals with waitForFunction
If no single element marks "ready", wait for a condition in the page. page.waitForFunction() runs your function in the browser until it returns a truthy value:
If you own the app, the flag is the most reliable option of all: set window.__APP_READY__ = true (or a data-ready attribute on the root element) after the first data load, and every test and script gets a clear signal.
Avoid waitForTimeout
await page.waitForTimeout(3000) is the most common fix and the worst one. It is too long on a fast machine and too short on a slow CI runner, so the test is both slow and flaky. Playwright's docs say it should only be used for debugging.
The one acceptable use outside debugging: a short pause after the content is ready, for a CSS animation you cannot disable. For screenshots, Playwright can disable animations instead with animations: "disabled".
Playwright wait for page to load in Python
Python uses the same waits with snake_case names. The response wait is a context manager, which avoids the race described above:
With the async API, add await and use async with page.expect_response(...) as info:, then response = await info.value. In pytest-playwright tests, use expect(locator).to_be_visible() from playwright.sync_api for the same retrying behavior as in JavaScript.
More Python capture options, including Selenium and an API, are in five ways to take a website screenshot in Python.
Timeouts and the "Timeout 30000ms exceeded" error
In the Playwright library, with no timeout set anywhere in your code, navigation and locator waits give up after 30 seconds. We checked this on 1.65 (see the raw output in What we measured): both goto() and locator.waitFor() threw at 30,000 ms. The API reference describes the per-call timeout option as "defaults to 0", which reads like "no limit", but the library still applies its 30-second default unless you change it. Set it explicitly so the behavior does not depend on the version:
In Playwright Test, the limits are set in the config. The whole test has 30 seconds by default and each expect() retries for 5 seconds; navigation and actions have no separate limit unless you set one:
When you see page.goto: Timeout 30000ms exceeded, check in this order:
- Are you using
networkidle? Switch todomcontentloadedplus an element wait. - Does one slow resource block
load? A stuck image or third-party script delays the event. Usedomcontentloaded, or block that host withpage.route(). - Is the server actually slow from CI? Then raise the navigation timeout instead of the global one, so a broken locator still fails fast.
Waiting before a screenshot
Screenshots are where a bad wait shows up most: a capture taken at load on an SPA is a picture of a skeleton. Wait for an element that only exists once the data is rendered, not for a heading or layout that is already in the HTML shell and shows up while a skeleton is still on screen:
For masking dynamic areas, retina output and the rest of the capture options, see the Playwright screenshot guide.
If screenshots are the whole job, for example link previews, archives or reports, you can skip running the browser yourself. The SnapshotFlow API takes the same kind of waits as parameters:
wait_until accepts load, domcontentloaded, networkidle0 and networkidle2 (the default; it tolerates up to two open connections, so a polling widget does not block it). wait_for_selector waits for a CSS selector and returns a SELECTOR_NOT_FOUND error if it never appears, and delay adds up to 10 seconds after that. There is no equivalent of waitForFunction(); if you need a custom condition, keep that page in Playwright. All parameters are in the API docs.
FAQ
How do I make Playwright wait for the page to load completely?
There is no single event for "completely". load covers resources in the HTML, and networkidle waits for network quiet but can hang on pages that keep polling. The reliable way is to wait for the element or response that means your content is ready, using locator.waitFor() or page.waitForResponse().
What is the default waitUntil in page.goto()?
load. goto() returns after the load event, which on a single-page app is usually before its data arrives.
Is networkidle deprecated in Playwright?
Not removed, but discouraged. It is still accepted by goto() and waitForLoadState(), and the docs recommend web assertions and element waits instead, especially in tests.
What replaced waitForNavigation?
page.waitForURL(). It takes a glob, RegExp or function, handles History API route changes, and does not miss a navigation that finished early.
Should I use waitForSelector or locator.waitFor?
Both work. locator.waitFor() is the current API and fits with the rest of locator-based code; page.waitForSelector() returns an element handle and is mainly kept for existing scripts.
How do I wait for the page to load after a click?
If the URL changes, call page.waitForURL() after the click. If only data changes, start page.waitForResponse() before the click and await it after. In both cases, finish with a wait for the element you are going to read.
Sources and further reading
- Playwright: page.goto() and waitUntil
- Playwright: page.waitForLoadState()
- Playwright: locator.waitFor()
- Playwright: page.waitForURL()
- Playwright: timeouts
- Can a screenshot API render JavaScript? on this site, for SPA captures without running a browser.
Try it: 300 free screenshots, no card
Keep Playwright for your tests. For screenshots your product depends on, send one request with wait_for_selector and get the image back, without running Chromium yourself.