Skip to content

Commit 34a8dad

Browse files
ankur22ankur22
committed
Add docs for url option for waitForNavigation
1 parent 06a2b15 commit 34a8dad

File tree

4 files changed

+127
-16
lines changed

4 files changed

+127
-16
lines changed

‎docs/sources/k6/next/javascript-api/k6-browser/frame/_index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,3 +56,4 @@ Frame represents a single frame in a browser window. It can be a top-level frame
5656
| [waitForNavigation([options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/waitfornavigation/) | Waits for the given navigation lifecycle event to occur and returns the main resource response. |
5757
| [waitForSelector(selector[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/waitforselector/) | Returns when element specified by selector satisfies `state` option. |
5858
| [waitForTimeout(timeout)](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/waitfortimeout) | Waits for the given `timeout` in milliseconds. |
59+
| [waitForURL(url[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/waitforurl/) | Waits for the frame to navigate to the specified URL. |

‎docs/sources/k6/next/javascript-api/k6-browser/frame/waitfornavigation.md

Lines changed: 63 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,19 @@ Waits for the given navigation lifecycle event to occur and returns the main res
99

1010
<TableWithNestedRows>
1111

12-
| Parameter | Type | Default | Description |
13-
| ----------------- | ------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
14-
| options | object | `null` | |
15-
| 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/). |
16-
| options.waitUntil | string | `load` | When to consider operation to have succeeded. See [Events](#events) for more details. |
12+
| Parameter | Type | Default | Description |
13+
| ----------------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
14+
| options | object | `null` | |
15+
| 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/). |
16+
| options.url | string\|RegExp | `null` | URL or URL pattern to match the navigation URL against. Useful when frame navigation performs multiple redirects and you need to wait until a final destination within the frame is reached. |
17+
| options.waitUntil | string | `load` | When to consider operation to have succeeded. See [Events](#events) for more details. |
1718

1819
</TableWithNestedRows>
1920

21+
### When to use the url option
22+
23+
Use `options.url` when frame navigation passes through several intermediate pages (e.g., third‑party authentication or consent flows) before settling on a final URL. Matching the final URL or a regex pattern helps you reliably wait for the intended destination inside the frame. However, opt to work with [waitForURL](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/frame/waitforurl) instead since it mitigates the risk of race conditions better than `waitForNavigation`.
24+
2025
### Events
2126

2227
{{< admonition type="caution" >}}
@@ -36,3 +41,56 @@ Events can be either:
3641
| Type | Description |
3742
| --------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
3843
| Promise<null \| [Response](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/response/)> | The `Response` instance associated with the frame. Else, it returns `null` |
44+
45+
### Examples
46+
47+
{{< code >}}
48+
49+
```javascript
50+
import { browser } from 'k6/browser';
51+
52+
export const options = {
53+
scenarios: {
54+
browser: {
55+
executor: 'shared-iterations',
56+
options: {
57+
browser: {
58+
type: 'chromium',
59+
},
60+
},
61+
},
62+
},
63+
};
64+
65+
export default async function () {
66+
const page = await browser.newPage();
67+
68+
try {
69+
await page.setContent(`
70+
<iframe src="https://quickpizza.grafana.com/test.k6.io/" width="50%" height="50%"></iframe>
71+
`);
72+
73+
// Retreive the frame of the iframe
74+
const iframeElement = await page.$('iframe');
75+
const frame = await iframeElement.contentFrame();
76+
77+
// Wait for navigation to a specific URL
78+
await Promise.all([
79+
frame.click('a[href="/my_messages.php"]'),
80+
frame.waitForNavigation({ url: 'https://quickpizza.grafana.com/my_messages.php' }),
81+
]);
82+
83+
await frame.goto('https://quickpizza.grafana.com/test.k6.io/');
84+
85+
// Wait for navigation using URL pattern with RegExp
86+
await Promise.all([
87+
frame.click('a[href="/browser.php"]'),
88+
frame.waitForNavigation({ url: /\/browser\.php$/ }),
89+
]);
90+
} finally {
91+
await page.close();
92+
}
93+
}
94+
```
95+
96+
{{< /code >}}

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,4 +72,5 @@ Page provides methods to interact with a single tab in a running web browser. A
7272
| [waitForNavigation([options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/waitfornavigation/) | Waits for the given navigation lifecycle event to occur and returns the main resource response. |
7373
| [waitForSelector(selector[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/waitforselector/) | Returns when element specified by selector satisfies `state` option. |
7474
| [waitForTimeout(timeout)](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/waitfortimeout) | Waits for the given `timeout` in milliseconds. |
75+
| [waitForURL(url[, options])](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/waitforurl/) | Waits for the page to navigate to the specified URL. |
7576
| [workers()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/workers) | Returns an array of the dedicated [WebWorkers](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/worker) associated with the page. |

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

Lines changed: 62 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -9,14 +9,19 @@ Waits for the given navigation lifecycle event to occur and returns the main res
99

1010
<TableWithNestedRows>
1111

12-
| Parameter | Type | Default | Description |
13-
| ----------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
14-
| options | object | `null` | |
15-
| 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/). |
16-
| options.waitUntil | string | `load` | When to consider operation to have succeeded. See [Events](#events) for more details. |
12+
| Parameter | Type | Default | Description |
13+
| ----------------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
14+
| options | object | `null` | |
15+
| 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/). |
16+
| options.url | string\|RegExp | `null` | URL or URL pattern to match the navigation URL against. When provided, the method will wait for navigation to a URL that matches this parameter. |
17+
| options.waitUntil | string | `load` | When to consider operation to have succeeded. See [Events](#events) for more details. |
1718

1819
</TableWithNestedRows>
1920

21+
## When to use the url option
22+
23+
Use `options.url` when frame navigation passes through several intermediate pages (e.g., third‑party authentication or consent flows) before settling on a final URL. Matching the final URL or a regex pattern helps you reliably wait for the intended destination. However, opt to work with [waitForURL](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/waitforurl) instead since it mitigates the risk of race conditions better than `waitForNavigation`.
24+
2025
### Events
2126

2227
{{< admonition type="caution" >}}
@@ -37,7 +42,9 @@ Events can be either:
3742
| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
3843
| Promise<null \| [Response](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/response/)> | The `Response` instance associated with the page. Else, it returns `null` |
3944

40-
### Example
45+
### Examples
46+
47+
#### Basic navigation waiting
4148

4249
{{< code >}}
4350

@@ -69,13 +76,10 @@ export default async function () {
6976

7077
const submitButton = page.locator('input[type="submit"]');
7178

72-
await Promise.all([
73-
submitButton.click(),
74-
page.waitForNavigation(),
75-
]);
79+
await Promise.all([submitButton.click(), page.waitForNavigation()]);
7680

7781
await check(page.locator('h2'), {
78-
header: async h2 => await h2.textContent() == 'Welcome, admin!'
82+
header: async (h2) => (await h2.textContent()) == 'Welcome, admin!',
7983
});
8084
} finally {
8185
await page.close();
@@ -84,3 +88,50 @@ export default async function () {
8488
```
8589

8690
{{< /code >}}
91+
92+
#### Wait for navigation to specific URL
93+
94+
{{< code >}}
95+
96+
```javascript
97+
import { browser } from 'k6/browser';
98+
99+
export const options = {
100+
scenarios: {
101+
browser: {
102+
executor: 'shared-iterations',
103+
options: {
104+
browser: {
105+
type: 'chromium',
106+
},
107+
},
108+
},
109+
},
110+
};
111+
112+
export default async function () {
113+
const page = await browser.newPage();
114+
115+
try {
116+
await page.goto('https://quickpizza.grafana.com/test.k6.io/');
117+
118+
// Wait for navigation to a specific URL
119+
await Promise.all([
120+
page.click('a[href="/my_messages.php"]'),
121+
page.waitForNavigation({ url: 'https://quickpizza.grafana.com/my_messages.php' }),
122+
]);
123+
124+
await page.goto('https://quickpizza.grafana.com/test.k6.io/');
125+
126+
// Wait for navigation using URL pattern with RegExp
127+
await Promise.all([
128+
page.click('a[href="/browser.php"]'),
129+
page.waitForNavigation({ url: /\/browser\.php$/ }),
130+
]);
131+
} finally {
132+
await page.close();
133+
}
134+
}
135+
```
136+
137+
{{< /code >}}

0 commit comments

Comments
 (0)