Last updated on July 7th, 2025 at 04:41 am
When writing automated tests in Playwright, choosing the right locator is essential. A poor selector can make your tests flaky, hard to read, and difficult to maintain. One of the best ways to select form elements like inputs, checkboxes, and dropdowns is by using the getByLabel locator.
The getByLabel method allows you to find elements based on their associated label text, just like a real user would. This approach not only improves test reliability but also aligns with web accessibility standards. If you’re building modern web apps that prioritize usability and accessibility, this locator is your go-to choice.
In this complete guide, we’ll show you:
- What the getByLabel locator does
- Why it’s better than CSS or XPath for forms
- How to use it with real-world examples
- When to use it over other Playwright locators
- Best practices and common mistakes
By the end, you’ll be confident in using getByLabel to write clean, readable, and accessible Playwright tests.
If you’re new to Playwright, start with our Playwright Automation Tutorial. It covers setup, basic syntax, and first test execution.
Playwright getByLabel Locator Practical Examples
Let’s walk through real examples that show how the getByLabel locator improves test clarity and user-simulated behavior.
Select the Input Field by getByLabel Locator
Suppose you have an Email input field wrapped by Label as HTML given below.
<label>Email <input id="emailid" /></label>await page.getByLabel('Email').fill('test@example.com');This line finds the input field that has the label “Email” and types a sample email into it.
Select the Checkbox by getByLabel Locator
await page.getByLabel('I agree to terms').check();It locates a checkbox with the label “I agree to terms” and selects it.
Playwright getByLabel Locator to Select a Radio Button
await page.getByLabel('Male').check();Finds a radio button labeled “Male” and checks it.
Use RegExp in getByLabel locator
await page.getByLabel(/phone/i).fill('1234567890');Uses a regular expression to match labels like “Phone”, “Phone Number”, or “Your phone number”.
Handle Nested Labels
Suppose the input field is wrapped by a label.
<label>Username <input type="text" /></label>You can locate the input field using the given syntax.
await page.getByLabel('Username').fill('playwrightuser');Even if the label wraps the input element, getByLabel works seamlessly.
📚 Related Articles
When to Use getByLabel vs Other Locators
Sometimes, you may wonder whether to use getByLabel, getByPlaceholder, getByRole, or even CSS selectors. Here’s a quick comparison:
| Locator | Best For | Example Use |
| getByLabel | Form inputs with visible labels | Login forms, contact forms |
| getByRole | Semantic elements like buttons, links, checkboxes | Buttons, dropdowns, tabs |
| getByPlaceholder | Inputs with placeholder text instead of label | Search fields |
| locator(‘css=…’) | Complex or deeply nested elements | Tables, modals, nested lists |
Pro tip: If the form has a label, always prefer getByLabel over CSS or XPath. It’s more human-readable and accessible.
Common Mistakes To Avoid
Avoid these issues while using getByLabel locator in your Playwright automation test to make your tests reliable:
No Element
If your input doesn’t have a label, getByLabel won’t work. Add a or use aria-label.
Wrong Label-Input Association
Make sure the label uses for=”id” or wraps the input. Otherwise, Playwright won’t find it.
Multiple Labels with Same Text
Use .nth() or make label text more specific.
await page.getByLabel('Name').nth(1).fill('John');Playwright getByLabel Locator Best Practices
To get the most out of the getByLabel locator, follow these tips:
- Use clear and unique label text
- Prefer semantic HTML with tags
- Combine with regex for flexible matching
- Avoid using it for elements without proper labels
- Add aria-label if visible label is not possible
Frequently Asked Questions (FAQs)
1. What is getByLabel in Playwright?
It’s a locator that finds form elements by their associated label text. It makes tests more readable and accessible.
2. Can I use getByLabel for checkboxes?
Yes. It works great for checkboxes, radio buttons, and other form inputs.
3. How does getByLabel match labels?
It searches for a match with the given text and then selects the input element associated with it.
4. Can I use regular expressions with getByLabel?
Yes, you can pass a RegExp like /Email/i for partial or case-insensitive matches.
Final Words
The getByLabel locator is one of the most intuitive and reliable selectors in Playwright. By targeting form controls based on their label text, it simulates how real users interact with your app. Whether you’re filling out forms, checking boxes, or selecting options, this locator keeps your tests clear, stable, and accessible.
Hi, I’m Aravind, a seasoned Automation Test Engineer with 17+ years of industry experience. I specialize in tools like Selenium, JMeter, Appium, and Excel automation. Through this blog, I share practical tutorials, tips, and real-world insights to help testers and developers sharpen their automation skills.
