Playwright: How to Wait for Page to Load (Best Practices & Examples)

When automating browser interactions with Playwright, ensuring the page is fully loaded before performing actions is crucial. This article explores how to wait for a page to load in Playwright, different strategies, and when to use each. Whether you're using JavaScript, TypeScript, or Python, this guide has you covered.

✅ Quick Answer

Use page.goto(url, { waitUntil: 'load' }) to wait until the page load event is fired.

await page.goto('https://example.com', { waitUntil: 'load' });

🔍 Page Load Events in Playwright

Playwright provides different waitUntil options to control when navigation is considered "finished":

🧪 Method 1: page.goto() with waitUntil

await page.goto('https://example.com', { waitUntil: 'networkidle' });

When to use:

• Waiting for complex SPAs
• Pages with dynamic content loading via AJAX

🧪 Method 2: page.waitForLoadState()

This method can be used after navigation or an action to ensure the page reaches a specific load state.

await page.click('a#nav-link');
await page.waitForLoadState('load');

Load states:

🧪 Method 3: page.waitForNavigation()

This method waits for navigation triggered by actions like clicks or form submissions.

await Promise.all([
  page.waitForNavigation({ waitUntil: 'load' }),
  page.click('a#nav-link'),
]);

Pro Tip:

Always wrap both the action and wait in a Promise.all() to avoid race conditions.

🧪 Method 4: Custom Wait for Selectors

For pages that dynamically render after initial load (common in React/Vue), waiting for a specific selector may be more reliable.

await page.goto('https://example.com');
await page.waitForSelector('#main-content');

⚖️ Comparison Table

🎯 Best Practices

• Use 'networkidle' for SPAs with heavy JS.
• Avoid time.sleep() or waitForTimeout() unless debugging.
• Always wait for a relevant element or state, not just time-based delays.

🧼 Bonus Tip: Combining Waits

You can combine multiple wait strategies for precision.

await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
await page.waitForSelector('#dashboard');
await page.waitForLoadState('networkidle');

📦 Playwright Python Example

page.goto("https://example.com", wait_until="networkidle")
page.wait_for_selector("#main")

🚀 Conclusion

Waiting for the page to load properly is critical for stable tests and automation in Playwright. Choose the right wait strategy based on your application's behavior:

• Static pages? → waitUntil: 'load'
• Dynamic content? → waitForSelector
• Complex SPAs? → networkidle or combine waits

Want more? Check out the official Playwright docs.