Introduction to Playwright Locators
When writing automated tests, finding and interacting with page elements is crucial. This is where Playwright locators come into play. Locators are used to target elements on the page, such as buttons, links, input fields, and more. In this tutorial, you’ll learn how to use Playwright locators, see real-world examples, and understand the different types available.
Whether you’re new to automation or switching from Selenium to Playwright, this guide will help you understand everything you need to know about using locators effectively.
What Are Locators in Playwright?
In Playwright, locators are a high-level API that helps you locate DOM elements efficiently and reliably. Unlike traditional selectors like querySelector, Playwright locators are auto-waiting and retry on failure, making them more robust for modern web testing.
They are used with the page.locator() method or built-in helper locators like getByText, getByRole, and others.
Why Use Playwright Locators?
Here are a few reasons why Playwright locators are preferred:
- Auto-wait for elements to be visible and stable.
- Built-in retries for flaky tests.
- Cleaner syntax than raw selectors.
- Easy debugging and improved test reliability.
They help you build stable test automation that works across browsers.
Types of Locators in Playwright
Playwright offers a wide range of locator strategies. Here’s a complete list:
1. CSS Selectors
CSS selectors in Playwright are a powerful way to find and interact with elements on a web page. They let you target elements using tags, classes, IDs, attributes, and even complex combinations. This makes it easier to write accurate and flexible tests. Moreover, CSS selectors are widely used and easy to understand, especially for beginners.
In Playwright, you can use CSS selectors along with other locator methods to build strong and reliable test scripts. For example, combining them with page.locator() gives you more control. So, learning CSS selectors not only saves time but also improves your overall automation skills.
page.locator('button.submit')Using the above syntax, you can target elements directly with a CSS selector.
2. Text Locator
Text locators in Playwright make it easy to find elements based on the visible text on the page. This is especially helpful when working with buttons, links, or labels that users interact with. Instead of relying on IDs or classes, you can simply use the exact text you see on the screen.
Moreover, text locators are beginner-friendly and improve the readability of your tests. They work well when your app has consistent and clear content.
To begin, you can use the following syntax to target an element based on the text shown on the page.
page.getByText('Submit')3. Role Locator
Role locators in Playwright are perfect for selecting elements based on their ARIA roles, such as button, link, textbox, or checkbox. This makes your tests more readable and accessible. Instead of using complex CSS or XPath selectors, you can simply target elements by their intended purpose on the page.
Role-based locators are ideal for testing modern, accessibility-focused web applications. They work seamlessly with Playwright’s getByRole() method. Moreover, using role locators encourages better coding practices and aligns your tests with real user interactions.
Here’s a simple syntax to select a web element using the getByRole locator in Playwright.
page.getByRole('button', { name: 'Submit' })4. Placeholder Locator
Placeholder locators in Playwright allow you to select input fields based on their placeholder text. This is especially useful when forms don’t have labels or unique IDs. Instead of relying on CSS classes or roles, you can simply use the visible placeholder value to locate the element quickly and accurately.
With the getByPlaceholder() method, you can easily interact with input boxes, search fields, and forms that use placeholder attributes. So, if you’re working with dynamic or label-less forms, using placeholder locators is a smart and efficient choice.
page.getByPlaceholder('Enter your email')Using the getByPlaceholder() locator, the above example selects the element based on its placeholder text.
5. Label Locator
Label locators in Playwright allow you to select elements based on their associated text. This method is especially helpful when working with form fields like input boxes, checkboxes, or radio buttons. Instead of depending on classes or IDs, you can simply use the text inside the label to locate the element.
page.getByLabel('Email Address')In this example, the getByLabel() method is used to find the element through its label.
6. Title Locator
Title locators in Playwright allow you to select elements based on their title attribute. This is especially useful when elements don’t have visible text or labels but still include helpful tooltip-like information. Instead of relying on complex selectors, you can simply use the tooltip text to locate the element with ease.
getByTitle() method is a great choice for targeting icons, buttons, or links that only show their purpose through a title. So, when working with minimal UI designs, title locators are a smart and reliable way to improve your automation scripts.
page.getByTitle('Close')The above syntax targets elements by matching their title attribute.
7. Alt Text Locator
Alt text locators in Playwright help you find image elements based on their alt attribute. This is especially useful when testing websites that use descriptive alternative text for images. Instead of selecting images by class or ID, you can directly target them using their visible alt text, which improves both clarity and test accuracy.
page.getByAltText('Logo')As shown above, this syntax helps locate the image based on its alt text using getByAltText().
8. Test ID Locator
Test ID locators in Playwright allow you to target elements using custom data-testid attributes. These attributes are commonly added by developers specifically for testing purposes. Instead of relying on classes or IDs that may change over time, you can use stable test IDs to create more reliable and maintainable test scripts.
page.getByTestId('signup-button')As shown above, you can use getByTestId() to target elements by their data-testid attribute.
9. XPath Locator
XPath locators in Playwright allow you to select elements using XML path expressions. This method is very powerful, especially when working with complex or deeply nested HTML structures. Unlike CSS selectors, XPath can navigate both forward and backward in the DOM, making it ideal for targeting tricky elements.
Moreover, Playwright supports XPath through the page.locator(‘//xpath’) syntax, which gives you flexibility in advanced testing scenarios.
page.locator('//input[@id="username"]');Playwright Locators Examples
Let’s say you have an element with the following HTML structure.
<form>
<!-- 5. Label Locator -->
<label for="username-input">Username</label>
<!-- Input element with all necessary attributes -->
<input
id="username-input"
name="username"
type="text"
role="textbox" <!-- 3. Role Locator -->
placeholder="Enter your username" <!-- 4. Placeholder Locator -->
title="Username Field" <!-- 6. Title Locator -->
data-testid="usernameField" <!-- 7. Test ID Locator -->
value="sampleuser" <!-- 2. Text Locator -->
class="user-input special-field" <!-- 1. CSS Selector -->
/>
</form>
This element can be targeted in multiple ways using different Playwright locator strategies.
- CSS Selector: page.locator(‘.user-input’) or page.locator(‘#username-input’)
- Role Locator: page.getByRole(‘textbox’, { name: ‘Username’ })
- Placeholder Locator: page.getByPlaceholder(‘Enter your username’)
- Label Locator: page.getByLabel(‘Username’)
- Title Locator: page.getByTitle(‘Username Field’)
- Test ID Locator: page.getByTestId(‘usernameField’)
- XPath: page.locator(‘//input[@id=”username-input”]’)
Locator vs getBy in Playwright
Let’s compare the traditional locator() and modern getBy methods.
| Feature | locator() | getBy*() Methods |
| Flexibility | High (supports any selector) | Medium (semantic, focused) |
| Readability | Less readable | More readable |
| Accessibility | Needs manual role awareness | ARIA roles are built-in |
| Auto-wait | Yes | Yes |
In most cases, getByRole and getByText are preferred for clarity and robustness, especially in accessibility-focused apps.
Best Practices for Using Locators
Here are a few tips to keep in mind:
- Prefer getByRole or getByText for stable and readable tests.
- Avoid using overly complex CSS selectors.
- Use getByTestId only when semantic selectors aren’t enough.
- Add custom data-testid attributes in your app for testability.
- Use locator().first(), locator().nth(), and locator().last() when dealing with multiple matches.
Final Words
Playwright locators are the backbone of any reliable test script. By using the right type of locator, whether it’s a text match, ARIA role, or CSS selector, you can create readable and robust tests. For beginners, starting with getByRole, getByText, and getByLabel will make your journey smoother and your tests more maintainable.
FAQs – Playwright Locators
What are locators in Playwright?
Locators in Playwright are used to find and interact with elements on a web page. They act as a reference to UI elements in your automated tests.
How many types of locators are there in Playwright?
Playwright supports multiple types of locators such as CSS selectors, getByRole, getByText, getByLabel, getByPlaceholder, getByAltText, getByTitle, and test ID locators.
What is the difference between locator and getBy in Playwright?
The locator() method is a generic way to select elements using CSS or XPath. The getBy* methods are more readable, semantic-based locators introduced for better accessibility and test reliability.
Which is the best locator to use in Playwright?
Using getByRole is often recommended because it’s accessibility-friendly and stable. However, the best locator depends on the structure of your HTML.
Can I combine multiple locators in Playwright?
Yes, you can chain locators in Playwright using methods like locator().first(), locator().nth(index), and locator().filter() to fine-tune element targeting.
Hi, I’m Aravind — a seasoned Automation Test Engineer with over 17 years of hands-on experience in the software testing industry. I specialize in tech troubleshooting and tools like Selenium, Playwright, Appium, JMeter, and Excel automation. Through this blog, I share practical tutorials, expert tips, and real-world insights to help testers and developers improve their automation skills.In addition to software testing, I also explore tech trends and user-focused topics, including Snapchat guides, codeless test automation, and more.
