Playwright Locators Best Practices

As an experienced engineer, I've seen firsthand how crucial Playwright locators are for building stable, maintainable test automation frameworks.

In this deep dive, I'll share the best practices and rules for using Playwright locators effectively. Let's get started with the fundamentals of Playwright locators and how to leverage them for rock-solid test scripts.

What Are Playwright Locators?

Locators are the cornerstone of element interaction in Playwright.

They're identifiers that allow your tests to find and manipulate specific elements on a web page. Choosing the right locator strategy is critical for test stability and maintenance.

There are two key approaches to selecting the locators in Playwright:

• User-facing attributes

• CSS attributes

Let's examine each in detail.

User-Facing Attributes (Recommended)

Playwright strongly recommends prioritizing user-facing attributes (aka user-facing locators) when selecting elements. These locators reflect how users and assistive technologies perceive the page.

Here are the key user-facing locator methods:

1. getByRole()

This should be your go-to method whenever possible. It selects elements based on their ARIA role, label, or other accessibility attributes. You can also pass a second argument to this method with visible text on the targeted element.

Example:

page.getByRole('button', { name: 'Submit' })

2. getByLabel()

Ideal for form controls associated with a label. For example, the input field for email address.

Example:

page.getByLabel('Email address')

3. getByPlaceholder()

Selects input elements based on their placeholder text.

Example:

page.getByPlaceholder('Enter your username')

4. getByText()

Finds elements containing specific text content. This is a good approach if the text you are targeting is unique and static.
Note: visible text inside the input fields is not text; it's a value. So it can't be selected by this method.

Example:

page.getByText('Welcome to our site')

5. getByAltText()

Locates images by their alt text, if the "alt" attribute is available in the DOM for this image

Example:

page.getByAltText('Company logo')

6. getByTitle()

Selects elements with a matching "title" attribute.

Example:

page.getByTitle('More information')

CSS Attributes

While user-facing attributes should be your first choice, CSS selectors are still valuable in certain scenarios.

Use the locator() method with CSS selectors like this:

Find by ID:

Use the # sign followed by the value of id attribute

Example:

page.locator('#myIdValue')

Find by class:

Use the "dot" sign followed by the value of class attribute. Note: the class attribute often contains multiple class values separated by spaces. You can target each of those values individually or combined.

Example:

page.locator('.myClassValue')page.locator('.myClassValue1.myClassValue2')

Find by HTML tag:

It's simple. Just provide a tag name as an argument. Can be combined with class values or other attributes.

Example:

page.locator('button')page.locator('button.primary')

Find by attribute:

Any HTML attribute can be used. Use square brackets to locate by attribute or attribute with value.

Example:

page.locator('[value]')page.locator('[value="green"]')

Using Filters

When using a locator() method, you can make the locator more unique by providing a second argument filtering the output. Or use a filter() method, which has an identical behavior.

Example:

page.locator('button', {hasText: "Log In"})page.locator('button').filter({hasText: "Log In"})

The filter() method can also be applied to user-facing locators.

Example:

page.getByRole('link').filter({ hasText: 'Learn more' })

Chaining Locators

You can combine multiple locators to create more specific selectors. Chain locators one by one, searching a child element within the scope of the previous locator.

Example:

page.locator('app-form').getByRole('button', { name: 'Submit' })

This finds a button with the text "Submit" within an "app-form" element.

The Locator Picker: Your Secret Weapon

Playwright includes a powerful built-in tool called the Locator Picker. Quickly find the perfect locator with a single click. Access it through:

The Playwright VS Code extension.

At the bottom of the Playwright test explorer window, click "Pick locator". A new browser window will open, and navigate to the desired page. Click the target element on the page, and the locator will be copied to VS Code's clipboard.

Playwright's UI Mode

Open test in UI Mode with "npx playwright test --ui" command. Run the test. In the console window below, select "Pick locator" icon to identify the locator for the element

This tool is a massive time-saver and helps ensure you're following best practices.

Best Practices for Playwright Locators

1. Prioritize user-facing attributes (getByRole, getByLabel, etc.) whenever possible.

2. Use CSS selectors as a fallback when user-facing attributes aren't suitable.

3. Avoid XPath selectors entirely.

4. Leverage the Locator Picker to quickly generate optimal locators.

5. Chain locators for increased specificity when needed.

6. Use filters to further refine your element selection.

7. Keep locators as simple and readable as possible for better maintainability.

8. When using getByRole(), include the accessible name for precision.

9. Regularly review and update your locators as the application evolves.

10. Document your locator strategy for your team to ensure consistency.

Conclusion

Mastering Playwright locators is essential for creating robust, maintainable test automation frameworks.

By prioritizing user-facing attributes, leveraging advanced techniques such as chaining and filtering, and using tools like the Locator Picker, you'll be well-equipped to handle even the most complex web applications.

Remember, the key is to think like a user, not a machine.

Choose locators that reflect how people interact with your application, and your tests will be more resilient and meaningful.

Ready to take your Playwright skills to the next level? Check out my in-depth course on Playwright at Bondar Academy. You'll get hands-on practice, personalized code reviews, expert guidance to master these concepts, and more.

Check more related articles in our blog:

• Playwright Timeout 30000ms Exceeded

• How to Use Playwright Expect Assertions