Skip to content

Update Handle stale elements docs #2116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Nov 17, 2025
Merged

Update Handle stale elements docs #2116

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
31a7c42
Update wait-dom-changes.md
heitortsergent Nov 4, 2025
4650271
Rename wait-dom-changes to handle-dynamic-elements
heitortsergent Nov 4, 2025
f503240
Update page weight
heitortsergent Nov 4, 2025
9be3f01
Apply to previous versions
heitortsergent Nov 17, 2025
169053a
Apply force click info to previous versions
heitortsergent Nov 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ...xt/using-k6-browser/recommended-practices/clean-up-test-resources-page-close.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: 'Use Page.close to clean up test resources'
description: 'Use Page.close in your browser tests to ensure k6 properly flushes metrics and cleans up resources'
weight: 01
weight: 650
---

# Use Page.close to clean up test resources
Expand Down
16 changes: 9 additions & 7 deletions ...recommended-practices/wait-dom-changes.md → ...nded-practices/handle-dynamic-elements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,18 @@
---
title: 'Handling Stale or Dynamic Elements After Navigation'
title: 'Handle stale or dynamic elements after navigation'
description: 'Wait for elements to appear in k6 browser tests to avoid interacting with stale or dynamic content'
weight: 01
weight: 50
---

# How To Handle Stale or Dynamic Elements After Navigation
Modern websites often update the DOM asynchronously after navigation or user interactions. Waiting for navigation to complete is not sufficient, as test scripts may still fail or attempt to interact with elements that are not yet available. Instead, wait for specific elements to appear before continuing your test. Use [locator APIs](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/) such as `waitFor` to ensure elements are ready for interaction. This is especially important when testing SPAs or any pages with dynamic content, where elements may be added, removed, or updated asynchronously.
# Handle stale or dynamic elements after navigation

Modern websites often update the DOM asynchronously after navigation or user interactions. Waiting for navigation to complete isn't sufficient, as test scripts may still fail or attempt to interact with elements that aren't yet available.

To avoid these issues, wait for specific elements to appear before you continue your test. Use [locator APIs](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/) such as `waitFor` to ensure elements are ready for interaction.

This approach is especially important when you test single-page applications (SPAs) or any pages with dynamic content, where elements may be added, removed, or updated asynchronously.

## Example
{{< code >}}

```javascript
import { browser } from 'k6/browser';
Expand Down Expand Up @@ -36,5 +40,3 @@ export default async function () {
});
}
```

{{< /code >}}
2 changes: 1 addition & 1 deletion ...6/next/using-k6-browser/recommended-practices/hybrid-approach-to-performance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: 'Hybrid approach to performance'
heading: 'Hybrid performance with k6 browser'
head_title: 'Hybrid performance with k6 browser'
description: 'An example on how to implement a hybrid approach to performance with k6 browser'
weight: 200
weight: 100
---

# Hybrid performance with k6 browser
Expand Down
2 changes: 1 addition & 1 deletion .../next/using-k6-browser/recommended-practices/prevent-cookie-banners-blocking.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "Prevent cookie banners from blocking interactions"
description: "How to reveal and dismiss cookie banners in k6 browser tests to prevent blocked interactions and improve test reliability."
weight: 100
weight: 350
---

# Prevent cookie banners from blocking interactions
Expand Down
2 changes: 1 addition & 1 deletion docs/sources/k6/v1.1.x/javascript-api/k6-browser/elementhandle/click.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Mouse click on the chosen element.
| options.button | string | `left` | The mouse button (`left`, `middle` or `right`) to use during the action. |
| options.clickCount | number | `1` | The number of times the action is performed. |
| options.delay | number | `0` | Milliseconds to wait between `mousedown` and `mouseup`. |
| options.force | boolean | `false` | Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`). |
| options.force | boolean | `false` | Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`). Avoid using `force: true` in `click` actions, as it may mask underlying test design or app issues. It bypasses normal user interaction checks, and elements may not be clickable due to [cookie banner interference](https://grafana.com/docs/k6/<K6_VERSION>/using-k6-browser/recommended-practices/prevent-cookie-banners-blocking/). |
| options.modifiers | string[] | `null` | `Alt`, `Control`, `Meta` or `Shift` modifiers keys pressed during the action. If not specified, currently pressed modifiers are used. |
| options.noWaitAfter | boolean | `false` | If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete. |
| options.position | object | `null` | A point to use relative to the top left corner of the element. If not supplied, a visible point of the element is used. |
Expand Down
2 changes: 1 addition & 1 deletion docs/sources/k6/v1.1.x/javascript-api/k6-browser/frame/click.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ This method clicks on an element matching a `selector`.
| options.button | string | `left` | The mouse button (`left`, `middle` or `right`) to use during the action. |
| options.clickCount | number | `1` | The number of times the action is performed. |
| options.delay | number | `0` | Milliseconds to wait between `mousedown` and `mouseup`. |
| options.force | boolean | `false` | Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`). |
| options.force | boolean | `false` | Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`). Avoid using `force: true` in `click` actions, as it may mask underlying test design or app issues. It bypasses normal user interaction checks, and elements may not be clickable due to [cookie banner interference](https://grafana.com/docs/k6/<K6_VERSION>/using-k6-browser/recommended-practices/prevent-cookie-banners-blocking/). |
| options.modifiers | string[] | `null` | `Alt`, `Control`, `Meta` or `Shift` modifiers keys pressed during the action. If not specified, currently pressed modifiers are used. |
| options.noWaitAfter | boolean | `false` | If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete. |
| options.position | object | `null` | A point to use relative to the top left corner of the element. If not supplied, a visible point of the element is used. |
Expand Down
2 changes: 1 addition & 1 deletion docs/sources/k6/v1.1.x/javascript-api/k6-browser/locator/click.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Mouse click on the chosen element.
| options.button | string | `left` | The mouse button (`left`, `middle` or `right`) to use during the action. |
| options.clickCount | number | `1` | The number of times the action is performed. |
| options.delay | number | `0` | Milliseconds to wait between `mousedown` and `mouseup`. |
| options.force | boolean | `false` | Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`). |
| options.force | boolean | `false` | Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`). Avoid using `force: true` in `click` actions, as it may mask underlying test design or app issues. It bypasses normal user interaction checks, and elements may not be clickable due to [cookie banner interference](https://grafana.com/docs/k6/latest/using-k6-browser/recommended-practices/prevent-cookie-banners-blocking/). |
| options.modifiers | string[] | `null` | `Alt`, `Control`, `Meta` or `Shift` modifiers keys pressed during the action. If not specified, currently pressed modifiers are used. |
| options.noWaitAfter | boolean | `false` | If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete. |
| options.position | object | `null` | A point to use relative to the top left corner of the element. If not supplied, a visible point of the element is used. |
Expand Down
2 changes: 1 addition & 1 deletion docs/sources/k6/v1.1.x/javascript-api/k6-browser/page/click.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ This method clicks on an element matching a `selector`.
| options.button | string | `left` | The mouse button (`left`, `middle` or `right`) to use during the action. |
| options.clickCount | number | `1` | The number of times the action is performed. |
| options.delay | number | `0` | Milliseconds to wait between `mousedown` and `mouseup`. |
| options.force | boolean | `false` | Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`). |
| options.force | boolean | `false` | Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`). Avoid using `force: true` in `click` actions, as it may mask underlying test design or app issues. It bypasses normal user interaction checks, and elements may not be clickable due to [cookie banner interference](https://grafana.com/docs/k6/<K6_VERSION>/using-k6-browser/recommended-practices/prevent-cookie-banners-blocking/). |
| options.modifiers | string[] | `null` | `Alt`, `Control`, `Meta` or `Shift` modifiers keys pressed during the action. If not specified, currently pressed modifiers are used. |
| options.noWaitAfter | boolean | `false` | If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete. |
| options.position | object | `null` | A point to use relative to the top left corner of the element. If not supplied, a visible point of the element is used. |
Expand Down
2 changes: 1 addition & 1 deletion ....x/using-k6-browser/recommended-practices/clean-up-test-resources-page-close.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: 'Use Page.close to clean up test resources'
description: 'Use Page.close in your browser tests to ensure k6 properly flushes metrics and cleans up resources'
weight: 01
weight: 650
---

# Use Page.close to clean up test resources
Expand Down
42 changes: 42 additions & 0 deletions ...ces/k6/v1.1.x/using-k6-browser/recommended-practices/handle-dynamic-elements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
title: 'Handle stale or dynamic elements after navigation'
description: 'Wait for elements to appear in k6 browser tests to avoid interacting with stale or dynamic content'
weight: 50
---

# Handle stale or dynamic elements after navigation

Modern websites often update the DOM asynchronously after navigation or user interactions. Waiting for navigation to complete isn't sufficient, as test scripts may still fail or attempt to interact with elements that aren't yet available.

To avoid these issues, wait for specific elements to appear before you continue your test. Use [locator APIs](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/) such as `waitFor` to ensure elements are ready for interaction.

This approach is especially important when you test single-page applications (SPAs) or any pages with dynamic content, where elements may be added, removed, or updated asynchronously.

## Example

```javascript
import { browser } from 'k6/browser';

export const options = {
scenarios: {
browser: {
executor: 'shared-iterations',
options: {
browser: {
type: 'chromium',
},
},
},
},
};

export default async function () {
const page = await browser.newPage();

await page.goto('https://test.k6.io/browser.php');
const text = page.locator('#input-text-hidden');
await text.waitFor({
state: 'hidden',
});
}
```
2 changes: 1 addition & 1 deletion ...v1.1.x/using-k6-browser/recommended-practices/hybrid-approach-to-performance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: 'Hybrid approach to performance'
heading: 'Hybrid performance with k6 browser'
head_title: 'Hybrid performance with k6 browser'
description: 'An example on how to implement a hybrid approach to performance with k6 browser'
weight: 200
weight: 100
---

# Hybrid performance with k6 browser
Expand Down
2 changes: 1 addition & 1 deletion ...1.1.x/using-k6-browser/recommended-practices/prevent-cookie-banners-blocking.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "Prevent cookie banners from blocking interactions"
description: "How to reveal and dismiss cookie banners in k6 browser tests to prevent blocked interactions and improve test reliability."
weight: 100
weight: 350
---

# Prevent cookie banners from blocking interactions
Expand Down
Loading
Loading