Playwright waitForURL: Wait for the Right URL, Every Time

Playwright waitForURL pauses a test until the main frame is on a URL that matches a pattern you give it. It's the right wait after a login redirect, a form submit, or a client-side route change in a single-page app. It's one tool in a bigger kit; the Playwright wait guide shows which wait fits which situation.

This post covers the signature, all four ways to match a URL, the waitUntil and timeout options, whether you need to start waiting before the click, SPA routes, toHaveURL() as the assertion alternative, and how to fix "Timeout exceeded" errors. Every example is JavaScript and was run on Playwright 1.62.

page.waitForURL() Syntax

Playwright waitForURL is a page method that pauses a test until the main frame's URL matches a string, glob, RegExp or predicate, then waits for the waitUntil load state (load by default). Use it after clicks, form submits and redirects that change the URL.

await page.waitForURL(url, options);

// url:     string (exact or glob) | RegExp | (url: URL) => boolean
// options: { timeout?: number,
//            waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit' }

It returns a promise that resolves with no value once the URL matches and the waitUntil state is reached. Under the hood it works in two steps: if the current URL already matches, it just waits for the load state; otherwise it waits for a navigation to a matching URL. Recent versions also accept a URLPattern object, but the string, RegExp and function forms below cover everyday use.

Matching URLs: String, Glob, RegExp and Predicate

All five tests below log in on the-internet's demo login page, then wait for /secure in a different way:

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

test.beforeEach(async ({ page }) => {
  await page.goto('https://the-internet.herokuapp.com/login');
  await page.getByLabel('Username').fill('tomsmith');
  await page.getByLabel('Password').fill('SuperSecretPassword!');
  await page.getByRole('button', { name: 'Login' }).click();
});

test('glob pattern', async ({ page }) => {
  await page.waitForURL('**/secure');
  await expect(page.getByRole('heading', { name: 'Secure Area', exact: true })).toBeVisible();
});

test('exact string (full URL, no wildcards)', async ({ page }) => {
  await page.waitForURL('https://the-internet.herokuapp.com/secure');
});

test('regular expression', async ({ page }) => {
  await page.waitForURL(/\/secure$/);
});

test('predicate function', async ({ page }) => {
  await page.waitForURL((url) => url.pathname === '/secure');
});

test('with waitUntil and timeout options', async ({ page }) => {
  await page.waitForURL('**/secure', { waitUntil: 'domcontentloaded', timeout: 10000 });
  await expect(page.locator('#flash')).toContainText('You logged into a secure area!');
});

One trap with exact strings: page.waitForURL('/login') only works if you set baseURL in your config, because then Playwright resolves the relative path against it. Without baseURL it times out even while the page sits on https://the-internet.herokuapp.com/login. Use '**/login' when in doubt.

waitUntil and timeout Options

• waitUntil (default 'load'): what must happen after the URL matches. 'domcontentloaded' is faster when you only need the HTML; 'commit' resolves as soon as the response arrives and the document starts loading; 'networkidle' is discouraged by Playwright, because it waits for 500 ms with no network traffic, which some pages never reach.
• timeout: in milliseconds. 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 usually stops it. Pass { timeout: 10000 } to fail faster with a clearer message.

Click, Then waitForURL: Is There a Race?

For waitForResponse and waitForEvent you must start waiting before the click, because they only see events that happen after you call them. waitForURL is different: it first checks the current URL. If the navigation finished while the click was still returning, the URL already matches and waitForURL resolves at once. On the demo login page, page.url() is usually already /secure by the time click() returns, so the following waitForURL('**/secure') resolves at once.

So both of these are correct:

// 1. Wait after the click (simplest, and safe)
await page.getByRole('link', { name: 'Get started' }).click();
await page.waitForURL('**/docs/intro');

// 2. Promise first (also fine; same result)
const urlPromise = page.waitForURL('**/docs/intro'); // no await yet
await page.getByRole('link', { name: 'Get started' }).click();
await urlPromise;

The real race is a pattern that already matches before the navigation. Both styles fail the same way here. Enter a wrong password on the-internet's login page and the app redirects you back to /login; a waitForURL('**/login') resolves instantly and proves nothing. The same happens with a broad pattern such as '**/docs/**' when you're already inside the docs. The fix:

• Make the pattern match only the destination: '**/docs/intro', not '**/docs/**'.
• Follow the wait with an assertion on the new page's content, such as its heading.

waitForURL with SPA Route Changes

Single-page apps change the URL with the History API instead of loading a new document. waitForURL still works, because Playwright treats History API changes and hash changes as navigations. Both tests below change the URL without a full page load:

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

test('SPA route change on playwright.dev', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.getByRole('link', { name: 'Get started' }).click();

  // Client-side route change (no full page load) still counts
  await page.waitForURL('**/docs/intro');
  await expect(page.getByRole('heading', { level: 1 })).toHaveText('Installation');
});

test('hash route change in TodoMVC', async ({ page }) => {
  await page.goto('https://demo.playwright.dev/todomvc');
  const input = page.getByPlaceholder('What needs to be done?');
  await input.fill('Buy milk');
  await input.press('Enter');

  await page.getByRole('link', { name: 'Completed' }).click();
  await page.waitForURL('**/#/completed');
  await expect(page.getByTestId('todo-item')).toHaveCount(0);
});

test('promise-first pattern', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  const urlPromise = page.waitForURL('**/docs/intro'); // no await yet
  await page.getByRole('link', { name: 'Get started' }).click();
  await urlPromise;
});

test('assertion alternative: toHaveURL', async ({ page }) => {
  await page.goto('https://playwright.dev/');
  await page.getByRole('link', { name: 'Get started' }).click();
  await expect(page).toHaveURL(/\/docs\/intro$/);
});

The first test clicks "Get started" on playwright.dev, a client-side route change to /docs/intro. The second clicks the "Completed" filter in TodoMVC, which only changes the hash to #/completed. In both cases the URL is the cheap check, and the assertion on content is what confirms the new view actually rendered.

waitForURL vs expect(page).toHaveURL()

In a test, toHaveURL() is usually the better choice because its failure is self-explanatory:

Error: expect(page).toHaveURL(expected) failed

Expected pattern: /secure/
Received string:  "https://the-internet.herokuapp.com/login"
Timeout: 1000ms

Fixing "Timeout Exceeded" in waitForURL

When the URL never matches, you get this (captured on 1.62 with a 1.5-second timeout):

page.waitForURL: Timeout 1500ms exceeded.
=========================== logs ===========================
waiting for navigation to "**/secure" until "load"
============================================================

Work through these causes in order:

1. The navigation didn't happen. The click missed, a validation error blocked the form, or the login failed. Check the trace or a screenshot. How to debug Playwright tests shows how.
2. The pattern is wrong. Exact string with a trailing slash, a query string you didn't expect, or a relative path without baseURL. Log page.url() and compare, or switch to a RegExp.
3. The URL matched but the load state didn't arrive. The log says until "load". A slow third-party script can hold up load; pass waitUntil: 'domcontentloaded' and assert on the content you need.
4. The navigation opened in a new tab. target="_blank" links don't change the current page's URL. Wait for page.waitForEvent('popup') instead, as shown in the waitForLoadState guide.

For other timeout messages, see the Playwright timeout errors guide, and for the full picture of stabilising tests, the flaky tests fix guide.

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