Skip to content

Commit e77d217

Browse files
ankur22ankur22
committed
Add page.getByLabel doc page
1 parent 8a5ca50 commit e77d217

File tree

1 file changed

+189
-0
lines changed

1 file changed

+189
-0
lines changed

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

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
title: 'getByLabel(text[, options])'
3+
description: 'Browser module: page.getByLabel(text[, options]) method'
4+
---
5+
6+
# getByLabel(text[, options])
7+
8+
Returns a locator for form controls associated with the specified label text. This method is ideal for interacting with form elements in an accessible and user-focused way, as it mirrors how users typically identify form fields.
9+
10+
<TableWithNestedRows>
11+
12+
| Parameter | Type | Default | Description |
13+
| ------------- | -------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
14+
| text | string\|RegExp | - | Required. The label text 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 label 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 form control associated with the specified label. |
25+
26+
### Examples
27+
28+
#### Basic form interaction
29+
30+
Fill form fields using their labels:
31+
32+
{{< code >}}
33+
34+
```javascript
35+
import { browser } from 'k6/browser';
36+
37+
export const options = {
38+
scenarios: {
39+
ui: {
40+
executor: 'shared-iterations',
41+
options: {
42+
browser: {
43+
type: 'chromium',
44+
},
45+
},
46+
},
47+
},
48+
};
49+
50+
export default async function () {
51+
const page = await browser.newPage();
52+
53+
try {
54+
await page.setContent(`
55+
<label for="username">Username (hint: default)</label>
56+
<input type="text" id="username" name="username">
57+
<label for="password">Password (hint: 12345678)</label>
58+
<input type="password" id="password" name="password">
59+
`);
60+
61+
const username = page.getByLabel('Username (hint: default)', { exact: true });
62+
const password = page.getByLabel(/^Password.*$/);
63+
64+
await username.fill('default');
65+
await password.fill('12345678');
66+
} finally {
67+
await page.close();
68+
}
69+
}
70+
```
71+
72+
{{< /code >}}
73+
74+
#### Working with different input types
75+
76+
Handle various form control types in various label association patterns:
77+
78+
{{< code >}}
79+
80+
```javascript
81+
import { browser } from 'k6/browser';
82+
83+
export const options = {
84+
scenarios: {
85+
browser: {
86+
executor: 'shared-iterations',
87+
options: {
88+
browser: {
89+
type: 'chromium',
90+
},
91+
},
92+
},
93+
},
94+
};
95+
96+
export default async function () {
97+
const page = await browser.newPage();
98+
99+
try {
100+
await page.setContent(`
101+
<label for="username">Username (hint: default)</label>
102+
<input type="text" id="username" name="username">
103+
<span id="password-label">Password (hint: 12345678)</span>
104+
<input type="password" aria-labelledby="password-label">
105+
<label for="subscribe">Subscribe to newsletter</label>
106+
<input type="checkbox" id="subscribe" name="subscribe">
107+
<label for="email">Email</label>
108+
<input type="radio" id="email" value="email">
109+
<label for="sms">Text message</label>
110+
<input type="radio" id="sms" value="sms">
111+
<label for="theme">Theme</label>
112+
<select id="theme" name="theme">
113+
<option value="light">Light</option>
114+
<option value="dark">Dark</option>
115+
<option value="system">System</option>
116+
</select>
117+
<textarea aria-label="Comments"></textarea>
118+
`);
119+
120+
// Inputs
121+
page.getByLabel('Username (hint: default)', { exact: true }).fill('default');
122+
page.getByLabel(/^Password.*$/).fill('12345678');
123+
124+
// Checkbox
125+
await page.getByLabel('Subscribe to newsletter').check();
126+
127+
// Radio button
128+
await page.getByLabel('Email', { exact: true }).check();
129+
130+
// Select dropdown
131+
await page.getByLabel('Theme').selectOption('light');
132+
133+
// Textarea
134+
await page.getByLabel('Comments').fill('This is a test comment');
135+
} finally {
136+
await page.close();
137+
}
138+
}
139+
```
140+
141+
{{< /code >}}
142+
143+
### Label association patterns
144+
145+
The `getByLabel()` method works with several HTML patterns for associating labels with form controls:
146+
147+
**1. Explicit association with `for` attribute:**
148+
149+
```html
150+
<label for="username">Username</label> <input type="text" id="username" name="username" />
151+
```
152+
153+
**2. ARIA labeling:**
154+
155+
```html
156+
<span id="username-label">Username</span> <input type="text" aria-labelledby="username-label" />
157+
```
158+
159+
**3. ARIA label attribute:**
160+
161+
```html
162+
<input type="text" aria-label="Username" />
163+
```
164+
165+
### Common use cases
166+
167+
- **Form testing**: Login forms, registration forms, contact forms
168+
- **E-commerce**: Checkout forms, shipping information, payment details
169+
- **Settings pages**: User preferences, account settings, configuration forms
170+
- **Accessibility testing**: Ensuring proper label association and screen reader compatibility
171+
172+
### Best practices
173+
174+
1. **Accessibility-first approach**: Using `getByLabel()` ensures your tests work the same way users with assistive technology interact with forms.
175+
176+
2. **Meaningful labels**: Encourage developers to use descriptive, unique label text that clearly identifies the form control's purpose.
177+
178+
3. **Required field indicators**: When testing required fields, include any visual indicators (like asterisks) in your label text matching.
179+
180+
4. **Form validation testing**: Use labels to test form validation scenarios, as they provide a stable way to identify fields regardless of styling changes.
181+
182+
### Related
183+
184+
- [page.getByRole()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/getbyrole/) - Locate by ARIA role
185+
- [page.getByAltText()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/getbyalttext/) - Locate by alt text
186+
- [page.getByPlaceholder()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/getbyplaceholder/) - Locate by placeholder text
187+
- [page.getByTestId()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/getbytestid/) - Locate by test ID
188+
- [page.getByTitle()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/getbytitle/) - Locate by title attribute
189+
- [page.getByText()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-browser/page/getbytext/) - Locate by text content

0 commit comments

Comments
 (0)