Playwright waitForLoadState: When You Need It and When You Don't

Playwright waitForLoadState pauses a test until the page reaches a load state: load, domcontentloaded or networkidle. Most of the time you don't need it, because page.goto() already waits for load. Where it earns its place is on pages you didn't open with goto, such as popups and new tabs. For choosing between all the waits, start with the Playwright wait guide.

Below: the three states, the default, when the call resolves instantly, the popup pattern, why networkidle is discouraged, and how it compares with goto's waitUntil and with waitForURL. Every example is JavaScript and was run on Playwright 1.62.

page.waitForLoadState() Syntax and States

Playwright waitForLoadState is a page method that waits until the current document reaches a load state: load (the default), domcontentloaded or networkidle. If the page has already reached that state, it returns immediately, so it is mainly useful for popups and new tabs.

await page.waitForLoadState(state, options);

// state:   'load' (default) | 'domcontentloaded' | 'networkidle'
// options: { timeout?: number }

Note there is no 'commit' state here. commit exists only as a waitUntil value for goto, waitForURL and similar navigation methods.

Timeout: in Playwright Test the default comes from navigationTimeout, which is 0 (no limit) unless you set it, so the 30-second test timeout is what stops a stuck wait. Pass { timeout: 10000 } to fail sooner.

When waitForLoadState Resolves Immediately

If the current document has already reached the state, waitForLoadState returns at once. That's the most common reason it seems to "do nothing": after await page.goto(url), the load event has already fired, so a following await page.waitForLoadState() is a no-op.

const { test, expect } = require('@playwright/test');

test('resolves at once if the state is already reached', async ({ page }) => {
  await page.goto('https://the-internet.herokuapp.com/login'); // already waited for 'load'
  await page.waitForLoadState(); // returns immediately: 'load' already fired
  await expect(page.getByRole('button', { name: 'Login' })).toBeVisible();
});

test('goto fast, then wait for the full load', async ({ page }) => {
  await page.goto('https://playwright.dev/', { waitUntil: 'domcontentloaded' });
  // ...quick checks that only need the HTML...
  await expect(page).toHaveTitle(/Playwright/);

  await page.waitForLoadState('load'); // now wait for images, styles, scripts
});

test('wait for a popup to load', async ({ page }) => {
  await page.goto('https://the-internet.herokuapp.com/windows');

  const popupPromise = page.waitForEvent('popup');
  await page.getByRole('link', { name: 'Click Here' }).click();
  const popup = await popupPromise;
  await popup.waitForLoadState();

  await expect(popup).toHaveTitle('New Window');
  await expect(popup.getByRole('heading')).toHaveText('New Window');
});

test('wait for a new tab via the context', async ({ page, context }) => {
  await page.goto('https://the-internet.herokuapp.com/windows');

  const pagePromise = context.waitForEvent('page');
  await page.getByRole('link', { name: 'Click Here' }).click();
  const newPage = await pagePromise;
  await newPage.waitForLoadState('domcontentloaded');

  await expect(newPage).toHaveURL(/\/windows\/new$/);
});

The first two tests show the useful and useless cases on the same page object. The second one is a real pattern: go to the page with waitUntil: 'domcontentloaded', run quick checks that only need the HTML, then call waitForLoadState('load') when you need everything else.

One more rule from the Playwright docs: the navigation must already be committed when you call it. waitForLoadState checks the document the page has now; it doesn't wait for a navigation that hasn't started. After a click that navigates, use page.waitForURL() instead, explained in the waitForURL guide.

Wait for a Popup or New Tab to Load

This is where waitForLoadState is genuinely needed. A popup is a new page that Playwright hands you as soon as it exists, possibly before it has finished loading. Nobody called goto on it, so nobody waited for load:

const popupPromise = page.waitForEvent('popup');      // 1. start listening
await page.getByRole('link', { name: 'Click Here' }).click(); // 2. trigger
const popup = await popupPromise;                     // 3. get the new page
await popup.waitForLoadState();                       // 4. wait for 'load'

The third and fourth tests in the file above run this on the-internet's /windows page, which opens /windows/new in a new tab. Use page.waitForEvent('popup') when the tab was opened by that page; use context.waitForEvent('page') when you want any new page in the browser context. Either way, start the listener before the click, or the event can fire before you're listening.

Why networkidle Is Discouraged

The Playwright API docs label 'networkidle' DISCOURAGED: "Don't use this method for testing, rely on web assertions to assess readiness instead." Three reasons:

• It can hang. Analytics beacons, long polling, chat widgets and websockets keep the network busy, so the 500 ms quiet window may never come.
• It can pass too early. If the app pauses before firing its data request, the page looks idle and the wait resolves before the data arrives.
• It measures the wrong thing. Your test cares that the order list is on screen, not that the network went quiet.

// Avoid
await page.goto('https://demo.playwright.dev/api-mocking');
await page.waitForLoadState('networkidle');

// Prefer: wait for the content the API call produces
await page.goto('https://demo.playwright.dev/api-mocking');
await expect(page.getByText('Strawberry')).toBeVisible();

If you need a specific request to finish, wait for that request with page.waitForResponse(). It's precise where networkidle is a guess.

waitForLoadState vs goto's waitUntil

page.goto(url, { waitUntil }) navigates and waits in one call; waitForLoadState(state) only waits, on whatever document is already there. These two lines end in the same place:

await page.goto('https://playwright.dev/', { waitUntil: 'domcontentloaded' });

// is the same wait as
await page.goto('https://playwright.dev/', { waitUntil: 'commit' });
await page.waitForLoadState('domcontentloaded');

So when you control the navigation, set waitUntil on goto and skip waitForLoadState. Reach for waitForLoadState when you didn't start the navigation: popups, new tabs, or upgrading from a fast domcontentloaded to a full load later in the test.

waitForLoadState vs waitForURL

Rule of thumb: same tab, new URL → waitForURL. New tab → waitForEvent('popup') + waitForLoadState. Content → an assertion. If a wait still times out, the timeout errors guide and how to debug Playwright tests will find the cause, and the flaky tests fix guide covers the rest.

Frequently Asked Questions

Meet Your Instructor

Asim Noaman

Senior QA Automation Engineer & AI Testing Specialist

With years of hands-on experience building test automation frameworks for production applications, Asim specializes in combining traditional QA methodologies with cutting-edge AI tools. He has helped teams adopt Playwright and AI-driven testing workflows to ship faster with fewer bugs.

Udemy Instructor Published course author

Playwright + AI Expert Specialized in AI-powered QA

Production Experience Enterprise-grade frameworks

Connect on LinkedIn