A Guide to Wait for Page to Load in Playwright

Have you ever seen a Playwright script fail because the page was still loading? Your test attempted to click or look at an element that appeared only after the test started. It's very frustrating when some of your tests behave differently each time, even though the code hasn’t changed. With Playwright, you can redirect everything until the page is fully loaded.

In this post, we’ll explore how to wait for a website page to load properly using Playwright’s wait for page to load tools to ensure your tests run all the time.

Understanding Page Load Events

Playwright’s idea of “page load” is when a new document is loaded into the browser context after navigation events, such as opening a new URL, clicking a link, sending a form, or being redirected. This idea is crucial in automation, as much of web testing or scraping relies on fully loading the page before you do anything else.

It's frustrating when some of your tests behave differently each time, even though the code hasn’t changed.

The page load starts quickly after a Playwright script navigates to a URL using page.goto('https://example.com'). Playwright can consider the page loaded later using the waitUntil option. With this option, you decide the event that causes the script to go on to its next step. Only these values are provided when working with waitUntil: load, domcontentloaded, and networkidle.

The load option isn't triggered until all HTML content, related stylesheets, images, and subframes are finished loading. It’s an effective way to tell the browser about all the assets, which makes it slower since all external resources are first fetched. Consequently, domcontentloaded waits only for parsing the basic HTML and building the DOM. Because styles and images are left out, CSS is faster to load, and this option is ideal when the script is not reliant on them. In single-page applications (SPAs), the networkidle option is handy since pages may not need to reload when there is navigation. It joins back in once all network connections have been idle for more than 500 milliseconds, meaning all critical content should have finished displaying.

Whenever you need to coordinate a click on a link with the navigation process, use Promise.all() to ensure the link is processed before the page loads. For example, when clicking a link, wait for the new page to load using Promise.all({ getClick(), waitForNavigation({ waitUntil: 'load' }) }). As a result, the script will not advance until the resulting page has fully loaded. Using this technique, we avoid cases where the script accesses elements of a web page before they are ready. You need to know how Playwright handles waiting for page loads to create scripts that are never ambiguous when automating the browser.

Methods for Waiting for Page Load in Playwright

1. page.goto(url, options) with waitUntil

Testers use page.goto() to enable a page to finish loading. The page loads automatically, but you can change this using the waitUntil option.

When we trigger load, the page is ready when all its resources have also loaded. Specifying domcontentloaded delays the app until the initial HTML file is parsed, speeding things up and allowing resources to load later. Using network idle will wait for 500ms without any network requests, which is helpful for pages using asynchronous data loading.

2. page.waitForLoadState([state])

You can now perform a wait to ensure the page is in the desired load state at any moment, not only after it has finished loading. The allowable states in fetch are load, domcontentloaded, and networkidle.

3. page.waitForSelector(selector[, options])

This looks for the element in the DOM and, optionally, when set as visible, allows the page to render it. This becomes important when you need on-screen elements before working with your script.

4. page.waitForResponse(urlOrPredicate[, options])

This waits for the network to respond with a URL or the result of a predicate function. This is useful when waiting until the API data is ready.

5. locator.waitFor([options])

This monitors aspects of an element using locators, such as whether it is attached, visible, hidden or even detached—waitFor() allows that specific action. It provides firm control of each area within the page design.

6. Auto-Waiting on Actions

If you use actions like click(), fill(), or type(), Playwright does not act until the page is ready. This often means designers don’t need to include explicit waits.

Best Practices for Managing Page Load in Automation

1. Use Specific Elements Instead of Set Timeframes

Do not add waitForTimeout() delays because they create unnecessary pauses that make your tests slow and fragile. Instead, rely on specific elements or page conditions showing the correct start time. You can pause the script by adding await page.waitForSelector('#main-content'). By processing tests this way, your testing improves because the tests begin immediately when the necessary area is loaded.

2. Pick the Load State Task You Are Doing

Several load states are available from Playwright when navigating pages, such as load, domcontentloaded, and networkidle. With domcontentloaded, your script will run sooner if it just needs the main HTML structure and DOM. Wait until you need all your media files before using load, but if network activity affects your process, ensure that you use networkidle after everything has finished. Because networkidle slows tests, you should match the delay strategy to the page’s background load activity instead of just using networkidle too much.

3. Make Use of Playwright’s Auto-Waiting Components

With click(), fill(), and type(), Playwright automatically waits until the elements you are using become available to interact with. So, you rarely have to wait longer before performing these actions. If you wait explicitly too many times, it increases the time it takes to complete the tests. Rely on Playwright’s waits for elements and only add explicit waits at key points, like when navigation is done or an essential element appears.

Not everfy network request is essential for the automation process

4. Avoid Waiting for Activities That Don’t Affect Your Network

Not every network request is essential for the automation process. Third-party scripts, analytics, or updates often run in the background on your pages. Waiting until there are no more network requests can cause your tests to be slower than they should be. So, pick and wait only for necessary details with commands like waitForResponse() or waitForSelector.

5. Process Fast and Asynchronous Tasks With Ease

Today's typical trend in web pages is adding content after the main page loads dynamically. Since asynchronous behavior can cause problems, make your automation resistant to it by including conditional waits and error management. For example, wait for specific HTML elements to appear using waitForSelector(). You should also consider retrying actions if elements disappear or aren’t ready during the test. Because of its flexibility, testing won’t be as likely to fail, and the tests will work well under multiple network conditions or slow pages.

Performance Considerations When Waiting for Page Load

1. Don’t Rely on Static Timeouts

Having fixed waiting times, such as page.waitForTimeout(5000), in your scripts decreases their speed. Choose waits that instantly activate themselves when everything your test needs is ready.

2. Pick the Most Suitable Load State

If all you need is the HTML and DOM set up, go for domcontentloaded since it loads faster. Choose load or networkidle to ensure tasks finish, but understand that they may cause things to take more time.

3. Take Advantage of Playwright’s Automatic Waiting Feature

Playwright waits for elements to be ready automatically during click() and fill() actions. To speed up the tests, write these actions so they don’t need extra explicit waits.

4. Focus Waits on Important Elements

If you only need part of the page or a particular network request, use waitForSelector() for UI and waitForResponse() for networks instead of waiting for everything.

5. Don’t Rely on Slow or Repetitive Network Activity When You Are Redressing

Some pages still have background requests or open connections. Waiting to confirm that the network is idle can result in lengthy and possibly endless delays. Filters should only apply to network requests that play a role in your workflow.

6. Use Conditional and Flexible Waiting

Use time limits and error handling for your asynchronous content to keep your application working well for all users, regardless of load speed.

Whether you trigger navigation, handle a user’s action, or load dynamic content, the same method can decide if your test is flaky or reliable.

Why‌ Use Wait for Page to Load in Playwright?

There is more to managing page load with Playwright than passive waiting; you should be smart about it. Whether you trigger navigation, handle a user’s action, or load dynamic content, the same method can decide if your test is flaky or reliable. Adopting these approaches as you build your Playwright tests will guarantee your tests are solid, correct, and quick. You can also take advantage of Autify Nexus, which offers a low-code solution that makes your testing faster and more resilient. 

‍