How to use waitForLoadState in Playwright?

Flaky waits remain one of the biggest causes of unstable end-to-end tests in modern JavaScript applications. A 2022 empirical study that analyzed 452 flaky-test-related commits across large JavaScript projects found that async wait issues, race conditions, and concurrency problems were among the most dominant causes of test flakiness.

Playwright’s waitForLoadState() method helps synchronize tests with browser lifecycle events so interactions happen only after the page reaches a predictable state.

In this article, I will explain how waitForLoadState() works, when to use each load state, common mistakes that make tests unstable, and how to choose the right waiting strategy for reliable Playwright automation.

waitForLoadState Syntax and How It Works

The waitForLoadState method pauses the script execution until the page triggers a specific state. Unlike element-level waits, this function operates at the page or frame level, making it ideal for verifying that an entire navigation or heavy reload has concluded.

Unlike locator-based waits, waitForLoadState() does not wait for a specific element to become visible or interactive. Instead, it listens for browser page lifecycle events such as load or DOMContentLoaded. Once the selected event is triggered, the wait resolves and the test continues execution.

Basic syntax:

await page.waitForLoadState('load');

You can also wait for other lifecycle states:

await page.waitForLoadState('domcontentloaded');

await page.waitForLoadState('networkidle');

If no state is provided, Playwright waits for the default load state:

await page.waitForLoadState();

You can also pass a custom timeout. If the page does not reach the specified state within that time, Playwright throws a TimeoutError.

await page.waitForLoadState('load', { timeout: 10000 });

This waits up to 10 seconds for the page to reach the load state. It is useful when you want the test to fail clearly instead of hanging for too long in a slow local or CI environment.

The Three waitForLoadState States: load, domcontentloaded, and networkidle

To use waitForLoadState correctly, it is vital to understand the three distinct states it can monitor. Choosing the wrong state can either lead to unnecessary delays or tests that proceed before the UI is stable.

Code:

import { test } from '@playwright/test';

test('Understand waitForLoadState states', async ({ page }) => {

  await page.goto('https://playwright.dev', {

    waitUntil: 'commit'

  });

  console.log('Initial navigation started');

  await page.waitForLoadState('domcontentloaded');

  console.log('DOMContentLoaded reached here');

  await page.waitForLoadState('load');

  console.log('load reached here');

});

• load: This is the default state. It waits for the load event to be fired, which occurs when the entire page has loaded, including all dependent resources like stylesheets, scripts, and images. Use this when the test depends on images, stylesheets, or other resources being fully loaded before interaction.

await page.goto('https://example.com');

await page.waitForLoadState('load');

• domcontentloaded: This state resolves when the HTML document has been completely loaded and parsed, without waiting for stylesheets, images, and subframes to finish loading. This is useful for server-rendered pages where the required content is already present in the initial HTML and the test does not need to wait for heavy assets like images.

await page.goto('https://example.com');

await page.waitForLoadState('domcontentloaded');

• networkidle: This state resolves when there are no network requests for at least 500 ms. While powerful, this is often discouraged for general use because a single “noisy” analytics request or a long-polling API can prevent the wait from ever resolving, leading to timeouts. This can help in applications that fetch data after the initial page load, but it should be used carefully because background requests may prevent the page from ever reaching a fully idle state.

await page.waitForLoadState('networkidle');

When to Use waitForLoadState in Playwright Tests

Understanding when to reach for waitForLoadState versus relying on Playwright’s built-in auto-waiting is a key skill for any automation engineer.

After page.goto()

When you call await page.goto(url), Playwright waits for the page’s load event by default using waitUntil: ‘load’. In many cases, this removes the need for an additional waitForLoadState() call after navigation.

However, if your application triggers additional background redirects or heavy client-side rendering immediately after the initial load, calling waitForLoadState manually can provide an extra layer of stability.

await page.goto('https://example.com', {

waitUntil: 'domcontentloaded'

});

In most cases, configuring the navigation wait directly through waitUntil is cleaner than calling waitForLoadState() immediately after page.goto().

After A Click Or Action That Triggers Navigation

If clicking a button triggers a page transition that does not use a standard <a> tag (e.g., a JavaScript-driven redirect), Playwright’s auto-waiting on the next element might occasionally fail if the DOM is replaced too quickly. In such cases, explicitly waiting for the load state after the click ensures the new page is ready.

await Promise.all([

page.waitForLoadState('load'),

page.click('#login-button')

]);

In authentication or redirect-heavy flows, waitForURL() is often more reliable because it confirms the application reached the expected route.

SPAs With Client-Side Routing

In Single Page Applications (SPAs), the load event often fires very early because the shell of the page is small. Since SPA content is often rendered after API calls complete, waiting for a specific UI element is usually more reliable than relying on the standard load state.

In some cases, networkidle may help, but it should be used carefully because background requests can keep the page from ever becoming fully idle.

await page.click('#spa-nav');

await page.waitForLoadState('networkidle');

await expect(

page.getByRole('heading', {

name: 'Products'

})

).toBeVisible();

This combines a network-level wait with a UI-level assertion, which is more reliable than depending entirely on networkidle.

API-Heavy Pages

For pages that rely on multiple background API calls to populate the UI, the load state might resolve while the data is still fetching. Here, networkidle waits until there are no active network requests for at least 500 ms. While useful for some API-heavy pages, it does not guarantee that all UI updates or background browser activity have finished.

await page.goto('/dashboard');

await page.waitForLoadState('networkidle');

await expect(

 page.getByText('Revenue Report')

).toBeVisible();

This pattern helps stabilize pages that fetch data after the initial load while still verifying that the expected UI content is rendered.

Server-Rendered Pages

For traditional server-side rendered (SSR) pages where most content is present in the initial HTML, the domcontentloaded state is often sufficient. This allows your tests to run faster by not waiting for heavy non-critical assets like tracking pixels or footer images.

await page.goto('/products', {

 waitUntil: 'domcontentloaded'

});

await expect(

 page.getByRole('heading', {

   name: 'Products'

 })

).toBeVisible();

This allows the test to continue as soon as the HTML is parsed, which is usually enough for server-rendered pages where the important content is already present in the initial response.

waitForLoadState() vs waitUntil

A common point of confusion in Playwright is the difference between waitUntil and waitForLoadState().

The waitUntil option is used during navigation methods like page.goto(). It controls which lifecycle event Playwright should wait for before considering the navigation complete.

For example:

await page.goto('https://example.com', {

  waitUntil: 'domcontentloaded'

});

In this case, Playwright finishes the navigation as soon as the DOMContentLoaded event fires.

By default, page.goto() uses waitUntil: ‘load’. That means Playwright already waits for the page’s load event during navigation, which removes the need for an additional waitForLoadState(‘load’) call in many situations.

In contrast, waitForLoadState() is used after a navigation or action has already started. It adds an explicit wait for a page lifecycle state before the test continues.

For example:

await Promise.all([

page.waitForLoadState('load'),

page.click('text=Login')

]);

Here, the click triggers the navigation first, and waitForLoadState() waits for the new page to reach the specified state.

As a general rule:

• Use waitUntil to control how navigation methods behave.
• Use waitForLoadState() only when an action or client-side transition requires additional synchronization after navigation begins.

waitForLoadState vs waitForSelector vs Auto-Waiting

One of Playwright’s biggest advantages is its built-in auto-waiting system. In many situations, you do not need to manually pause execution because Playwright automatically waits for elements to become actionable before interacting with them.

Understanding the difference between auto-waiting, waitForSelector(), and waitForLoadState() helps prevent unnecessary waits and reduces flaky tests.

Auto-Waiting

Playwright automatically waits before actions like click(), fill(), and press(). Before performing the action, it checks whether the element is:

• visible
• stable
• attached to the DOM
• enabled for interaction

In many cases, this removes the need for manual waits entirely.

Example:

await page.click('#submit-button');

Here, Playwright automatically waits until the button is ready to receive the click.

waitForSelector()

waitForSelector() is an element-level wait. It is useful when a specific UI element appears dynamically after an API call, animation, or client-side update.

Example:

await page.waitForSelector('#dashboard');

This waits until the target element appears in the DOM before continuing.

In modern Playwright tests, locator assertions like expect(locator).toBeVisible() are often preferred over waitForSelector() because assertions automatically retry until the condition is satisfied.

waitForLoadState()

waitForLoadState() is a page-level wait. Instead of waiting for a specific element, it waits for the page to reach a lifecycle state such as:

• load
• domcontentloaded
• networkidle

Example:

await Promise.all([

 page.waitForLoadState('load'),

 page.click('#login-button')

]);

This is useful when an action triggers a navigation, reload, or major document transition.

Which Wait Strategy Should You Prefer?

In most Playwright tests:

• auto-waiting should be your first choice
• element-level waits should be used when UI content loads dynamically
• page-level waits should only be used for navigations or complex loading flows

A common mistake is adding page-level waits everywhere, even when the test only depends on a single UI element becoming visible.

For example, this is usually unnecessary:

await page.click('#submit');

await page.waitForLoadState('load');

A more reliable approach is to wait for the actual UI state you care about:

await expect(

 page.getByText('Dashboard')

).toBeVisible();

Because Playwright automatically retries assertions, locator-based waits are often more stable than generic page lifecycle waits.

When NOT to Use waitForLoadState()

Avoid using Playwright waitForLoadState() method when:

• Interacting with ordinary UI elements like buttons or inputs
• Waiting for a single element to appear
• Validating dynamic content that already has a reliable locator
• Replacing assertions with generic page-level waits

In many situations, waiting for the actual UI state produces more stable tests than waiting for a page lifecycle event.

Instead of:

await page.click('#submit');

await page.waitForLoadState('load');

Prefer:

await expect(

 page.getByText('Dashboard')

).toBeVisible();

This makes tests more resilient because assertions automatically retry until the expected UI condition is satisfied.

Common waitForLoadState Mistakes, and How to Fix Them

Most issues with waitForLoadState() come from using it too broadly instead of synchronizing with the actual UI or navigation behavior the test depends on.

• Overusing networkidle: The networkidle state can become unreliable in modern applications that continuously send background requests through analytics scripts, polling APIs, or websocket connections. In these situations, tests may hang or timeout because the network never becomes fully idle. Fix: Prefer waiting for a specific API response with waitForResponse() or wait for a UI element that confirms the page is ready.
• Waiting After Every Action: Adding waitForLoadState() after every click slows down test execution and is unnecessary for standard interactions because Playwright already includes built-in auto-waiting for most actions. Fix: Use it only when an action triggers a real navigation, reload, or major page transition that Playwright does not automatically track.
• Forgetting to Await: Because waitForLoadState() returns a Promise, failing to use await causes the test to continue execution immediately before the page reaches the expected lifecycle state.

// Correct usage

await page.waitForLoadState('load');

// Incorrect: execution continues immediately

page.waitForLoadState('load');

Handling Edge Cases with waitForLoadState

While waitForLoadState() works well for standard navigations, some application patterns require additional synchronization strategies to avoid flaky behavior.

• Lazy-loaded Content: The page may reach the load state before lazy-loaded images or components are rendered. In these situations, combine waitForLoadState() with a locator-based wait or assertion for the specific element the test depends on.

await page.waitForLoadState('load');

await expect(

 page.locator('img.lazy')

).toBeVisible();

• Redirect Chains: Authentication flows and SSO systems often trigger multiple redirects before the final page is rendered. Waiting only for a generic load state can make tests unstable because intermediate navigations may complete before the application reaches its final route. In these cases, waitForURL() is often more reliable.

await Promise.all([

 page.waitForURL('**/dashboard'),

 page.click('#login-button')

]);

• Using It On Frames: waitForLoadState() is also available on Frame objects. This is useful when interacting with iFrames that load content independently from the main page.

await frame.waitForLoadState('load');

• Multi-tab Flows: When an action opens a new browser tab, the new page may not be immediately ready for interaction. Wait for the new page object to reach a stable load state before interacting with elements inside it.

const [newPage] = await Promise.all([

 context.waitForEvent('page'),

 page.click('#open-report')

]);

await newPage.waitForLoadState('load');

Using waitForLoadState in the Page Object Model (POM)

In a Page Object Model (POM), encapsulation is key. You should generally avoid calling waitForLoadState directly in your test files. Instead, encapsulate these waits within the action methods of your Page Object.

For example, a login method should include the wait for the dashboard to load:

import { Page, expect } from '@playwright/test';

export class LoginPage {

 constructor(private page: Page) {}

 async login(username: string, password: string) {

   await this.page.fill('#username', username);

   await this.page.fill('#password', password);

   await Promise.all([

     this.page.waitForURL('**/dashboard'),

     this.page.click('button[type="submit"]')

   ]);

   await expect(

     this.page.getByRole('heading', {

       name: 'Dashboard'

     })

   ).toBeVisible();

 }

}

Explanation:

Step 1 — Import Required Modules

The Page object is imported to interact with the browser page, and expect is imported for performing assertions.

Step 2 — Create the Login Page Class

A Page Object Model (POM) class named LoginPage is created.

The constructor receives the Playwright page instance, which is used throughout the class methods.

Step 3 — Fill Login Credentials

The username and password fields are located and populated with the provided credentials.

Step 4 — Wait for Navigation After Login

The login button is clicked while simultaneously waiting for navigation to the dashboard page.

Step 5 — Verify Successful Login

The test verifies that the Dashboard heading is visible after login.

This confirms:

* navigation completed successfully

* the expected UI is rendered

* login functionality works correctly

Encapsulating navigation waits inside page object methods keeps test files cleaner and centralizes synchronization logic in one place.

Avoid placing waits inside constructors because constructors cannot handle asynchronous operations cleanly and can make test behavior harder to predict.

Debugging waitForLoadState Issues in CI/CD Pipelines

Tests often pass locally but fail in CI/CD pipelines due to network latency or resource constraints.

• Trace Viewer: Use the Playwright Trace Viewer to inspect the timeline. You can see exactly which state the page was in when the timeout occurred.

• Network Logs: If networkidle is hanging, check the network logs in the trace. Look for requests that stay “pending” for a long time; these are likely the culprits preventing the state from resolving.
• CI Configuration: If tests fail consistently in CI/CD, review whether the chosen wait strategy matches the application’s behavior. Increasing navigationTimeout may help in slow environments, but flaky waits are often caused by relying on generic page states instead of waiting for specific UI conditions.

# Run tests with trace enabled for debugging

npx playwright test --trace on

# Run tests in headed mode locally

npx playwright test --headed

# Install required browser dependencies in CI

npx playwright install --with-deps

Example GitHub Actions step: 

Use trace logs and proper CI setup to investigate flaky waits before increasing timeout values.

- name: Install dependencies

 run: npm ci

- name: Install Playwright browsers

 run: npx playwright install --with-deps

- name: Run Playwright tests

 run: npx playwright test --trace on-first-retry

Conclusion: Choosing The Right Wait Strategy In Playwright

waitForLoadState() is useful for handling navigations, reloads, and major page transitions, but it should not be the default waiting strategy in every test. In many cases, Playwright’s built-in auto-waiting and locator assertions already provide more reliable synchronization.

When additional waiting is required, choosing the right lifecycle state matters. The load state works well for full document stability, domcontentloaded helps reduce unnecessary waiting on server-rendered pages, and networkidle can help with API-heavy applications when used carefully.

The most stable Playwright tests wait for the actual application state they depend on, whether that is a visible UI element, a resolved API response, or a completed navigation.