Skip to content

Commit 70220d1

Browse files
ankur22ankur22
committed
Add page.waitForURL docs page
1 parent 3d6eb0e commit 70220d1

File tree

1 file changed

+153
-0
lines changed

1 file changed

+153
-0
lines changed

‎docs/sources/k6/next/javascript-api/k6-browser/page/waitforurl.md

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
title: 'waitForURL(url[, options])'
3+
description: 'Browser module: page.waitForURL(url[, options]) method'
4+
---
5+
6+
# waitForURL(url[, options])
7+
8+
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.
9+
10+
<TableWithNestedRows>
11+
12+
| Parameter | Type | Default | Description |
13+
| ----------------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
14+
| url | string\|RegExp | - | Required. URL or URL pattern to match against. The method will wait until the page navigates to a URL that matches this parameter. |
15+
| options | object | `null` | |
16+
| options.timeout | number | `30000` | Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on [BrowserContext](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/browsercontext/) or [Page](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/). |
17+
| options.waitUntil | string | `load` | When to consider operation to have succeeded. See [Events](#events) for more details. |
18+
19+
</TableWithNestedRows>
20+
21+
### Events
22+
23+
{{< admonition type="caution" >}}
24+
25+
`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.
26+
27+
{{< /admonition >}}
28+
29+
Events can be either:
30+
31+
- `'domcontentloaded'` - consider operation to be finished when the `DOMContentLoaded` event is fired.
32+
- `'load'` - consider operation to be finished when the `load` event is fired.
33+
- `'networkidle'` - Consider operation to be finished when there are no network connections for at least `500` ms.
34+
35+
### Returns
36+
37+
| Type | Description |
38+
| ------- | ----------------------------------------------------------------------------------------------------------------------- |
39+
| Promise | A Promise that resolves when the page has navigated to the specified URL and the specified load state has been reached. |
40+
41+
### Examples
42+
43+
{{< code >}}
44+
45+
```javascript
46+
import { browser } from 'k6/browser';
47+
48+
export const options = {
49+
scenarios: {
50+
browser: {
51+
executor: 'shared-iterations',
52+
options: {
53+
browser: {
54+
type: 'chromium',
55+
},
56+
},
57+
},
58+
},
59+
};
60+
61+
export default async function () {
62+
const page = await browser.newPage();
63+
64+
try {
65+
await page.goto('https://quickpizza.grafana.com/test.k6.io/');
66+
67+
// Wait for navigation to a specific URL
68+
await Promise.all([
69+
page.click('a[href="/my_messages.php"]'),
70+
page.waitForURL('https://quickpizza.grafana.com/my_messages.php'),
71+
]);
72+
73+
await page.goto('https://quickpizza.grafana.com/test.k6.io/');
74+
75+
// Wait for navigation using URL pattern with RegExp
76+
await Promise.all([page.click('a[href="/browser.php"]'), page.waitForURL(/\/browser\.php$/)]);
77+
} finally {
78+
await page.close();
79+
}
80+
}
81+
```
82+
83+
{{< /code >}}
84+
85+
### Valid usage patterns for waitForURL
86+
87+
Use one of the following patterns to coordinate the action that triggers navigation with waiting for the final URL.
88+
89+
{{< code >}}
90+
91+
<!-- eslint-skip -->
92+
93+
```js
94+
await Promise.all([
95+
page.waitForURL('https://quickpizza.grafana.com/my_messages.php'),
96+
page.locator('a[href="/my_messages.php"]').click(),
97+
]);
98+
```
99+
100+
{{< /code >}}
101+
102+
or
103+
104+
{{< code >}}
105+
106+
<!-- eslint-skip -->
107+
108+
```js
109+
const navPromise = page.waitForURL('https://quickpizza.grafana.com/my_messages.php');
110+
await page.locator('a[href="/my_messages.php"]').click();
111+
await navPromise;
112+
```
113+
114+
{{< /code >}}
115+
116+
Unlike [waitForNavigation](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/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:
117+
118+
{{< code >}}
119+
120+
<!-- eslint-skip -->
121+
122+
```js
123+
await page.locator('a[href="/my_messages.php"]').click();
124+
await page.waitForURL('https://quickpizza.grafana.com/my_messages.php');
125+
```
126+
127+
{{< /code >}}
128+
129+
### Best practices
130+
131+
1. **Use appropriate matching**: Choose the right matching method based on your needs:
132+
133+
- Exact strings for known, static URLs
134+
- RegExp for pattern-based matching and complex URL validation
135+
136+
2. **Handle dynamic content**: For URLs with dynamic parts (IDs, timestamps), use regular expression patterns instead of exact matches.
137+
138+
3. **Set appropriate timeouts**: Adjust timeouts based on expected navigation time and network conditions.
139+
140+
4. **Verify final state**: After waiting for URL, verify that the page content matches your expectations.
141+
142+
### Common use cases
143+
144+
- **Form submissions**: Verify redirects after successful form submission
145+
- **Authentication flows**: Wait for login/logout redirects
146+
- **E-commerce**: Track progression through shopping and checkout flows
147+
- **SPAs**: Handle client-side routing changes
148+
- **API redirects**: Wait for server-side redirects after API calls
149+
150+
### Related
151+
152+
- [page.waitForNavigation()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/waitfornavigation/) - Wait for navigation events
153+
- [page.waitForLoadState()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/waitforloadstate/) - Wait for load states

0 commit comments

Comments
 (0)