Documentation for automated readers A curated documentation index is available at: https://grafana.com/llms.txt
A complete documentation index is available at: https://grafana.com/llms-full.txt These indexes can help with page discovery before fetching individual documents.
This page is also available in Markdown, which may be easier for automated readers
and AI tools to parse than HTML. The Markdown version is available at
https://grafana.com/docs/k6/next/using-k6-browser/recommended-practices/select-elements.md, or by sending
Accept: text/markdown to https://grafana.com/docs/k6/next/using-k6-browser/recommended-practices/select-elements/. For broader
documentation discovery, the curated index is available at https://grafana.com/llms.txt
and the complete index is available at https://grafana.com/llms-full.txt.
Selectors are strings that represents a specific DOM element on the page. When writing browser-level tests, it’s recommended to use selectors that are robust to avoid test flakiness when the DOM structure changes.
Currently, the browser module supports the standard CSS and XPath selectors.
Note
Text-based selectors are currently not supported. This will be supported in future releases.
Recommended practices
The selectors that you choose should not be tightly coupled to any behaviour or styling changes. If your application is prone to changes frequently, it’s recommended to use user-facing attributes or custom data attributes as these are not tightly coupled to the element.
Selector
Notes
✅ page.locator('[aria-label="Login"]')
User-facing attributes such as ARIA labels are rarely changed so these are great candidates.
✅ page.locator('[data-test="login"]')
Custom data attributes are not tightly coupled to the element.
✅ page.locator('//button[text()="Submit"]')
Text selectors are also great as text content rarely changes. While we don’t support text-based selectors as of yet, xpath can be used as a workaround.
⚠️ page.locator('#login-btn')
Selecting an element via its ID is also recommended if the ID doesn’t change.
⚠️ page.locator('.login-btn')
Selecting an element via its class name should be kept to a minimum as class names can be duplicated.
❌ page.locator('button')
Generic elements are not recommended because this has no context.
❌ page.locator('/html[1]/body[1]/main[1]
Absolute paths are not recommended as these are tightly coupled to the DOM structure.
