waitForURL(url[, options])
Waits for the page to navigate to the specified URL. This method is useful for ensuring that navigation to a particular URL has completed before proceeding with the test. This is especially useful if there are multiple redirects before hitting the end destination.
Events
Caution
networkidle
is DISCOURAGED. Don’t use this method for testing especially with chatty websites where the event may never fire, rely on web assertions to assess readiness instead.
Events can be either:
'domcontentloaded'
- consider operation to be finished when theDOMContentLoaded
event is fired.'load'
- consider operation to be finished when theload
event is fired.'networkidle'
- Consider operation to be finished when there are no network connections for at least500
ms.
Returns
Examples
Valid usage patterns for waitForURL
Use one of the following patterns to coordinate the action that triggers navigation with waiting for the final URL.
await Promise.all([
page.waitForURL('https://quickpizza.grafana.com/my_messages.php'),
page.locator('a[href="/my_messages.php"]').click(),
]);
or
const navPromise = page.waitForURL('https://quickpizza.grafana.com/my_messages.php');
await page.locator('a[href="/my_messages.php"]').click();
await navPromise;
Unlike
waitForNavigation, waitForURL
will first check whether it is already on the page with the given URL before proceeding to wait. If it is already there and the waitUntil
condition has also been met, it will return straight away. This means that it is safe to do this:
await page.locator('a[href="/my_messages.php"]').click();
await page.waitForURL('https://quickpizza.grafana.com/my_messages.php');
Best practices
Use appropriate matching: Choose the right matching method based on your needs:
- Exact strings for known, static URLs
- RegExp for pattern-based matching and complex URL validation
Handle dynamic content: For URLs with dynamic parts (IDs, timestamps), use regular expression patterns instead of exact matches.
Set appropriate timeouts: Adjust timeouts based on expected navigation time and network conditions.
Verify final state: After waiting for URL, verify that the page content matches your expectations.
Common use cases
- Form submissions: Verify redirects after successful form submission
- Authentication flows: Wait for login/logout redirects
- E-commerce: Track progression through shopping and checkout flows
- SPAs: Handle client-side routing changes
- API redirects: Wait for server-side redirects after API calls
Related
- page.waitForNavigation() - Wait for navigation events
- page.waitForLoadState() - Wait for load states