Menu
Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
Open source
getByLabel(text[, options])
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.
Returns
Examples
Basic form interaction
Fill form fields using their labels:
import { browser } from 'k6/browser';
export const options = {
scenarios: {
ui: {
executor: 'shared-iterations',
options: {
browser: {
type: 'chromium',
},
},
},
},
};
export default async function () {
const page = await browser.newPage();
try {
await page.setContent(`
<label for="username">Username (hint: default)</label>
<input type="text" id="username" name="username">
<label for="password">Password (hint: 12345678)</label>
<input type="password" id="password" name="password">
`);
const frame = page.mainFrame();
const username = frame.getByLabel('Username (hint: default)', { exact: true });
const password = frame.getByLabel(/^Password.*$/);
await username.fill('default');
await password.fill('12345678');
} finally {
await page.close();
}
}Working with different input types
Handle various form control types in various label association patterns:
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();
try {
await page.setContent(`
<label for="username">Username (hint: default)</label>
<input type="text" id="username" name="username">
<span id="password-label">Password (hint: 12345678)</span>
<input type="password" aria-labelledby="password-label">
<label for="subscribe">Subscribe to newsletter</label>
<input type="checkbox" id="subscribe" name="subscribe">
<label for="email">Email</label>
<input type="radio" id="email" value="email">
<label for="sms">Text message</label>
<input type="radio" id="sms" value="sms">
<label for="theme">Theme</label>
<select id="theme" name="theme">
<option value="light">Light</option>
<option value="dark">Dark</option>
<option value="system">System</option>
</select>
<textarea aria-label="Comments"></textarea>
`);
const frame = page.mainFrame();
// Inputs
await frame.getByLabel('Username (hint: default)', { exact: true }).fill('default');
await frame.getByLabel(/^Password.*$/).fill('12345678');
// Checkbox
await frame.getByLabel('Subscribe to newsletter').check();
// Radio button
await frame.getByLabel('Email', { exact: true }).check();
// Select dropdown
await frame.getByLabel('Theme').selectOption('light');
// Textarea
await frame.getByLabel('Comments').fill('This is a test comment');
} finally {
await page.close();
}
}Label association patterns
The getByLabel() method works with several HTML patterns for associating labels with form controls:
Explicit association with
forattribute:<label for="username">Username</label> <input type="text" id="username" name="username" />ARIA labeling:
<span id="username-label">Username</span> <input type="text" aria-labelledby="username-label" />ARIA label attribute:
<input type="text" aria-label="Username" />
Common use cases
- Form testing: Login forms, registration forms, contact forms
- E-commerce: Checkout forms, shipping information, payment details
- Settings pages: User preferences, account settings, configuration forms
- Accessibility testing: Ensuring proper label association and screen reader compatibility
Best practices
- Accessibility-first approach: Using
getByLabel()ensures your tests work the same way users with assistive technology interact with forms. - Meaningful labels: Encourage developers to use descriptive, unique label text that clearly identifies the form control’s purpose.
- Required field indicators: When testing required fields, include any visual indicators (like asterisks) in your label text matching.
- Form validation testing: Use labels to test form validation scenarios, as they provide a stable way to identify fields regardless of styling changes.
Related
- frame.getByRole() - Locate by ARIA role
- frame.getByAltText() - Locate by alt text
- frame.getByPlaceholder() - Locate by placeholder text
- frame.getByTestId() - Locate by test ID
- frame.getByTitle() - Locate by title attribute
- frame.getByText() - Locate by text content

