Skip to content

Commit ecbb409

Browse files
ankur22ankur22
committed
Add page.getByText docs page
1 parent 06007ee commit ecbb409

File tree

1 file changed

+137
-0
lines changed
  • docs/sources/k6/next/javascript-api/k6-browser/page

1 file changed

+137
-0
lines changed

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

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
title: 'getByText(text[, options])'
3+
description: 'Browser module: page.getByText(text[, options]) method'
4+
---
5+
6+
# getByText(text[, options])
7+
8+
Returns a locator for elements containing the specified text. This method finds elements by their visible text content, making it ideal for locating user-facing content like buttons, links, headings, and other text elements.
9+
10+
<TableWithNestedRows>
11+
12+
| Parameter | Type | Default | Description |
13+
| ------------- | -------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
14+
| text | string\|RegExp | - | Required. The text content to search for. Can be a string for exact match or a RegExp for pattern matching. |
15+
| options | object | `null` | |
16+
| options.exact | boolean | `false` | Whether to match the text exactly with case sensitivity. When `true`, performs a case-sensitive match. |
17+
18+
</TableWithNestedRows>
19+
20+
### Returns
21+
22+
| Type | Description |
23+
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
24+
| [Locator](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/locator/) | A locator object that can be used to interact with the element(s) containing the specified text. |
25+
26+
### Examples
27+
28+
Find and click elements by their visible text:
29+
30+
{{< code >}}
31+
32+
```javascript
33+
import { browser } from 'k6/browser';
34+
35+
export const options = {
36+
scenarios: {
37+
browser: {
38+
executor: 'shared-iterations',
39+
options: {
40+
browser: {
41+
type: 'chromium',
42+
},
43+
},
44+
},
45+
},
46+
};
47+
48+
export default async function () {
49+
const page = await browser.newPage();
50+
51+
try {
52+
await page.goto('https://quickpizza.grafana.com/');
53+
54+
await page.getByText('Pizza, Please!').click();
55+
56+
const noThanksBtn = page.getByText('No thanks');
57+
await noThanksBtn.click();
58+
} finally {
59+
await page.close();
60+
}
61+
}
62+
```
63+
64+
{{< /code >}}
65+
66+
### Text matching behavior
67+
68+
**Whitespace normalization**: Text matching automatically normalizes whitespace, meaning:
69+
70+
- Multiple spaces become single spaces
71+
- Line breaks become spaces
72+
- Leading and trailing whitespace is ignored
73+
74+
Consider the following DOM structure:
75+
76+
{{< code >}}
77+
78+
<!-- eslint-skip -->
79+
80+
```html
81+
<div>Hello <span>world</span></div>
82+
<div>Hello</div>
83+
```
84+
85+
{{< /code >}}
86+
87+
You can locate by text substring, exact string, or a regular expression:
88+
89+
{{< code >}}
90+
91+
<!-- eslint-skip -->
92+
93+
```js
94+
// Matches <span>
95+
page.getByText('world');
96+
// Matches first <div>
97+
page.getByText('Hello world');
98+
// Matches second <div>
99+
page.getByText('Hello', { exact: true });
100+
// Matches both <div>s
101+
page.getByText(/Hello/);
102+
// Matches second <div>
103+
page.getByText(/^hello$/i);
104+
```
105+
106+
{{< /code >}}
107+
108+
### Common use cases
109+
110+
- **Button interactions**: Submit, Cancel, Delete, Edit buttons
111+
- **Navigation**: Menu items, breadcrumbs, pagination links
112+
- **Content verification**: Success messages, error messages, headings
113+
- **Form interactions**: Checkbox labels, radio button options
114+
- **Status indicators**: Active, Inactive, Pending states
115+
116+
### Best practices
117+
118+
1. **User-focused testing**: Using `getByText()` ensures your tests interact with content as users see it.
119+
120+
2. **Avoid brittle text**: Be cautious with exact text that might change frequently (like dates, counts, or user-generated content).
121+
122+
3. **Use meaningful text**: Prefer descriptive button text and labels over generic terms like "Click here" or "Button".
123+
124+
4. **Handle dynamic content**: Use regular expressions for text that contains variable parts (timestamps, user names, counts).
125+
126+
5. **Consider accessibility**: Text-based selection encourages better accessibility practices in your application.
127+
128+
6. **Internationalization**: For multi-language applications, consider using test IDs or roles instead of text for critical interactions.
129+
130+
### Related
131+
132+
- [page.getByRole()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role
133+
- [page.getByAltText()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text
134+
- [page.getByLabel()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/getbylabel/) - Locate by form labels
135+
- [page.getByPlaceholder()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/getbyplaceholder/) - Locate by placeholder text
136+
- [page.getByTestId()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/getbytestid/) - Locate by test ID
137+
- [page.getByTitle()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/getbytitle/) - Locate by title attribute

0 commit comments

Comments
 (0)