Playwright Locators - Comprehensive Guide

Playwright Locators are designed to locate web page elements with precision and flexibility, offering a robust solution to the challenges of dynamic web applications through effective element identification.

They are the central piece in the puzzle of web automation, enabling testers to specify locators using various strategies, such as CSS selectors, XPath expressions, text content, and custom attributes like test IDs.

These locators are adept at handling multiple elements, matching elements by text, and even locating elements that contain or do not contain specified text somewhere inside, showcasing their versatility.

🎯 TL;DR – Playwright Selectors and Locators

• Comprehensive Locator Strategies – Playwright offers multiple locator strategies, including Playwright locator by ID, Playwright locator by class, Playwright get element by ID, Playwright get by text, and Playwright get by ARIA label, making it easy to target web elements precisely.
• Playwright Tests – Playwright tests enhance maintainability and reduce flakiness. Integration with platforms like HeadSpin and features such as the Test Generator make test creation and element locating easier, ensuring reliable automation testing.
• CSS and XPath Selectors – Playwright supports CSS selectors like Playwright class selector, Playwright ID selector, data-test attribute, and XPath selectors, including advanced queries like XPath nth child.
• Test Script Execution – Running a test script in Playwright executes all defined test cases, allowing users to see the resulting webpage and its title in the terminal.
• Optimized Testing with Auto-Wait – Playwright ensures stable tests by automatically waiting for elements to be actionable, reducing flakiness and improving test reliability.
• Chaining and Parent Selection – Playwright allows selector chaining and Playwright get parent element, enabling precise element targeting within complex DOM structures.

Understanding Playwright Locators

One of the standout features of Playwright Locators is their auto-waiting and retry-ability, ensuring that actions on elements proceed only when conditions are right, thus mitigating the risks of flaky tests. They always normalize whitespace in text matches, enhancing the accuracy and reliability of tests that involve text verification.

Moreover, Playwright allows for the use of regular expressions and filters by text, providing a fine-grained control over element selection that is unmatched by traditional testing tools.

A notable method for locating elements in Playwright is by using the 'title text' attribute. This attribute plays a significant role in assisting technologies and can be utilized in test scenarios to locate elements efficiently. It is particularly useful when multiple elements share the same title text, which can impact the locator's effectiveness.

This approach, where a locator must be relative, allows for the construction of complex queries that can navigate the nested structures of modern web applications with ease. It matches elements based on their visible text, providing a clear method for identifying components that contain a given string.

Furthermore, the built-in locators and the capability to create custom locators using the Playwright Inspector tool underline the flexibility and power that Playwright brings to the table.

Types of Playwright Selectors

Playwright supports a variety of selector engines, allowing for flexible and powerful element selection strategies. The main types include:

CSS Selectors

CSS selectors in Playwright are a cornerstone for selecting elements in the browser efficiently and effectively. They leverage standard CSS syntax to target elements based on their tag name, class, ID, attributes, and relationships within the DOM.

Types of CSS Selectors:

1. Type Selectors: Target elements by their tag name, e.g., div, a.
2. Class Selectors: Use a period . followed by the class name, e.g., .btn-primary.
3. ID Selectors: Use a hash # followed by the ID value, e.g., #submit-button.
4. Attribute Selectors: Use square brackets to specify an element with a certain attribute, e.g., [type='checkbox'].
5. Pseudo-classes and Pseudo-elements: Use pseudo-classes (:hover, :nth-child(n)) and pseudo-elements (::before, ::after) for state-based and structural targeting.
6. Combinators: Use combinators like >, +, ~ to define relationships between elements, e.g., div > .item selects elements with class item that are direct children of a div.

To use a CSS selector in Playwright, you pass the CSS string directly into the page.locator or page.$ methods. For example:

// Selecting an element by tag name const heading = page.locator('h1');

// Selecting elements by class name const buttons = page.locator('.button');

// Selecting an element by ID const navbar = page.locator('#navbar'); // Selecting elements by attribute const input = page.locator('input[type="text"]');

CSS selectors can be combined to create more specific queries. For example, to select a button within a specific section:

const loginButton = page.locator('#login-section .login-button');

This selects elements with the class login-button within the element with the ID login-section.

Playwright supports CSS pseudo-classes and pseudo-elements, allowing for even more precise element selection:

// Selecting the first child of an element const firstItem = page.locator('ul > li:first-child');

// Selecting elements on hover state (pseudo-classes) const hoverButton = page.locator('button:hover');

Text Selectors

In Playwright, matching by text is a fundamental technique that enables precise targeting of elements based on their visible text content.

• Target elements based on their visible text.
• Syntax: text="button text" for exact matches, or text=/regex/ for regular expression matches.
• Particularly useful for selecting links, buttons, or other elements where the visible text is a clear identifier.

ID Selectors

In Playwright, ID selectors are a straightforward and efficient way to target elements based on their unique id attribute. Given that id attributes are intended to be unique within an HTML document, using ID selectors can lead to very precise element selection, making them a reliable choice for identifying specific elements on a page.

To use an ID selector in Playwright, you can simply prefix the ID value with a hash (#) symbol, similar to CSS. However, Playwright also provides a dedicated id= selector engine that can be used explicitly.

Here are both ways to target an element by its ID:

// Using the CSS-like syntax const element = page.locator('#elementId');

// Using the dedicated ID selector engine const sameElement = page.locator('id=elementId');

Both lines above will target an element with the id attribute of elementId.

XPath Selectors

XPath selectors in Playwright provide a powerful and flexible way to select elements based on their structure and content within the HTML document. XPath, or XML Path Language, allows you to navigate the DOM tree using paths, offering features that go beyond the capabilities of CSS selectors. Consider the following DOM to understand how XPath can be applied in practical scenarios.

This includes selecting elements based on their text content, attributes, hierarchy, and more complex criteria.

• Use XPath expressions to select elements based on their hierarchical position in the DOM or specific attributes.
• Syntax: xpath=//button[@name='submit'] selects button elements with a name attribute equal to submit.
• Provides a powerful way to navigate complex DOM structures or select elements based on sibling or ancestor relationships.

Data Attribute Selectors

In Playwright, data attribute selectors provide a robust way to target elements based on custom data attributes. These attributes, often prefixed with data-, are used for providing additional information about HTML elements without interfering with their styling or behavior. The 'data testid attribute' is particularly useful in identifying elements in testing frameworks, allowing for enhanced element selection during tests by configuring the default 'data-testid' attribute to a custom test id in the test configuration or by modifying the HTML to use an alternative attribute.

To use data attribute selectors in Playwright, you directly utilize the attribute in your locator string. Here are some examples demonstrating how to select elements by their data attributes:

// Targeting an element with a specific data attribute and value const element = page.locator('[data-test-id="unique-element"]');

// Using a data attribute to find a button within a specific component const button = page.locator('.component-class [data-action="save"]');

In these examples, data-test-id and data-action are custom attributes used to uniquely identify elements within the page.

• Target elements by custom data attributes, which are often used specifically for testing purposes.
• Syntax: data-test-id=my-element or [data-test-id="my-element"] selects elements with a data-test-id attribute equal to my-element.
• Helps maintain stable tests by separating testing identifiers from CSS classes and IDs used for styling.

Role Selectors

Playwright’s role selectors provide a powerful and semantic way to target elements based on their Accessible Rich Internet Applications (ARIA) role, enhancing the accessibility testing capabilities within your automated testing suite.

Role selectors make it easier to ensure that web applications are accessible and functional for users with disabilities, by allowing tests to interact with elements in a way that mirrors how assistive technologies interpret and interact with web content. Recognizing the roles of many HTML elements is crucial for effective testing, as it ensures that automated tests align with user accessibility experiences.

To use a role selector in Playwright, you specify the role followed by the role name you are targeting. The syntax looks like this:

const button = page.locator('role=button');

This example targets all elements with an ARIA role of button.

Component Selectors (React, Vue, etc.)

• Target elements based on their framework-specific component names. This requires using Playwright’s framework-specific selectors plugin.
• Syntax: react=MyComponent or vue=MyComponent to select elements corresponding to a specific React or Vue component.
• Enables testing that is more closely tied to the application’s architectural components.
• Additionally, Playwright allows users to locate elements based on unique properties from the DOM structure, utilizing locators such as CSS and XPath selectors for precise targeting.

Best Practices for Using Playwright Selectors

1. Prefer User-facing Attributes

Use locator that mimic user interactions, such as text content or labels, over technical attributes like classes or IDs that may change more frequently.

Use meaningful attributes to the application’s users, such as role attributes for accessibility, which tend to be more stable. Additionally, consider using placeholder text to identify input fields without labels, especially in forms for login, registration, and reviews.

2. Use Data Attributes for Stability

Implement custom data attributes (e.g., data-testid, data-cy) in your application specifically for testing purposes. These attributes provide a stable way to select elements without relying on CSS classes or IDs that might change due to styling updates. Using explicit test ids is crucial for creating resilient testing methodologies, as they allow QA and developers to effectively locate elements in a web application, ensuring tests remain stable and reliable over time.

3. Avoid Brittle Selectors

Avoid using selectors that are highly dependent on the page structure or that use indexed positions, as these can easily break with UI changes.

CSS selectors should be concise and not overly specific to avoid breakage from minor changes in the DOM structure. It is crucial to use robust locators to locate the element effectively, ensuring they remain reliable even if the underlying element changes.

4. Use CSS and Text Selectors

CSS selectors are powerful for selecting elements based on their class, ID, or other attributes. They are a good balance between simplicity and specificity.

Text selectors are invaluable for interacting with elements in a way that mirrors user behavior, such as clicking buttons or links labeled with specific text. Using 'sensitive and whole string' selectors ensures precise targeting of elements, which is crucial for effective automation in modern web applications.

5. Utilize Playwright's Auto-wait Features

Playwright automatically waits for elements to be actionable before interacting with them. Ensure your selectors take advantage of this feature to reduce flakiness and the need for explicit waits. Additionally, use 'await page' for searching elements before performing actions like clicking, as it is a crucial part of the interaction process.

6. Combine Selectors for Precision

When necessary, combine selectors to refine element targeting. For example, use a combination of CSS and text selectors to identify an element within a specific section of a page. Additionally, you can use regular expressions to locate multiple elements within web applications, which helps in finding both exact and approximate matches.

Playwright’s >> syntax allows chaining selectors, enhancing specificity without increasing brittleness.

7. Regular Expressions for Flexible Text Matching

Use regular expressions with text selectors when you need to match elements based on patterns rather than fixed strings. This is particularly useful for dynamic content that follows a predictable format. Additionally, using an 'exact match' is crucial for precise element selection, ensuring accurate matching of single values in various parameters or text locators.

8. Test Accessibility with Role Selectors

Utilize role selectors to ensure that your application is accessible. Selecting elements by their ARIA role can help validate that important elements are present and correctly labeled for screen readers. Accurately identifying the focused element is crucial for proper interaction, as it ensures that focus events are handled correctly, enhancing the visibility and functionality of web elements.

9. Keep Selectors Short and Readable

While specificity is important, overly complex selectors can be hard to read and maintain. Aim for a balance between specificity and readability. For example, consider the following: using class selectors like .button-primary instead of overly specific selectors like div.container > ul > li > a.button-primary can make your code cleaner and easier to manage.

10. Review and Refactor Selectors Regularly

As your application evolves, so too should your selectors. Regularly review and update selectors to ensure they remain effective and reflect any changes in the application’s UI. Additionally, define explicit test IDs to maintain test reliability, as they allow QA teams and developers to query elements even if their associated roles or text change.

Creating Locators

To create a locator in Playwright, you use the page.locator() method, passing in a string that specifies the selection criteria. Playwright supports a wide range of selector engines, including CSS, text, XPath, and others, allowing you to craft locators that can match elements in almost any scenario:

// CSS selector const button = page.locator(‘button.submit’);

// Text selector const welcomeMessage = page.locator(‘text=”Welcome, User”‘);

// XPath selector const checkbox = page.locator(‘//input\[@type=”checkbox”\]’);

Additionally, Playwright excels at locating input elements in web forms, such as those with placeholder text, making it easier to automate interactions like logging in or submitting reviews.

Selector Strategies

Playwright supports multiple strategies for selecting elements, including:

• CSS Selectors: For selecting elements based on their CSS properties.

const button = page.locator(‘button.submit’);

• XPath: For selecting elements with XPath expressions.

const listItem = page.locator(‘//ul/li\[3\]’);

• Text Selectors: For selecting elements based on their text content.

const heading = page.locator(‘text=”Welcome to Our Site”‘);

• ID Selectors: For selecting elements by their ID.

const passwordField = page.locator(‘#password’);

• Composite Selectors: Combining multiple strategies for more precise targeting.

const loginButton = page.locator(‘text=”Login” >> css=button’);

It is also important to use placeholder attributes and labels for form elements, especially when input fields lack labels.

Locator Actions

Once you have defined a locator, you can perform various actions on the targeted element(s), such as:

• Clickingawait locator.click();
• Filling Textawait locator.fill(‘text’); The locator.fill() method is particularly efficient in targeting a particular element to simulate user input.
• Getting Textconst text = await locator.textContent();
• Asserting Visibilityawait expect(locator).toBeVisible();

Working with Multiple Elements

Playwright locators can also handle multiple elements. For instance, to count elements matching a selector:

const itemCount = await page.locator(‘ul > li’).count();

To iterate over multiple elements:

const items = page.locator(‘ul > li’); const count = await items.count(); for (let i = 0; i \< count; ++i) { console.log(await items.nth(i).textContent()); }

When multiple elements match a given locator, it is crucial to specify which element to interact with to avoid unintended actions.

Playwright Chain Locators and Multiple Locators

Chaining locators in Playwright refers to the process of creating a locator that is based on the context of another locator. This is particularly useful when you need to perform actions on elements that are within a specific part of the page or are related to other elements in some way.

You can chain locators using the locator method on an existing locator object, allowing you to refine your selection based on a relative context. This approach enables you to create precise and resilient selectors that can navigate complex page structures. Additionally, filtering elements to ensure actions are executed on the correct matching element is crucial to avoid errors during testing and interaction.

Automate your tests for free

Test easier than ever with BugBug test recorder. Faster than coding. Free forever.

Example of Chaining Locators:

const parentLocator = page.locator(‘div.parent’); const childLocator = parentLocator.locator(‘div.child’); await childLocator.click();

In this example, childLocator is a locator that specifically targets div.child elements that are descendants of div.parent elements. This allows for precise targeting of elements within a specific context.

In summary, Playwright’s locators and selector engines offer a powerful and flexible way to interact with web elements, supporting a wide range of scenarios from simple element selection to complex, dynamic interactions. Chaining locators further enhance this by allowing for context-specific element selection, making it easier to write stable and reliable tests. Precise targeting of a single DOM element is crucial for reliable test execution, as operations on locators are strict and exceptions will occur if multiple matching DOM elements are found.

💡 Check also our guide on Playwright Test Recorder

Key Takeaways: Mastering Locators for Efficient Playwright Automation

Locators are the central piece of Playwright’s automation framework, allowing you to locate and interact with elements on the page efficiently. By understanding and leveraging various locator strategies, testers can ensure stable, reliable, and maintainable automated tests. Here’s how you can take full advantage of Playwright’s locators:

1. Understand the Difference Between Locators and Selectors – A selector describes how to find elements on a web page, while an element locator is used to interact with those elements dynamically. This distinction is crucial for ensuring that the element corresponding to the locator remains valid even as the DOM updates over time.
2. Utilize Playwright’s Built-in Locators – Playwright comes with multiple locators that provide an easy way to locate elements on a web page. Locators such as role, text, CSS, and XPath in Playwright are commonly used to find elements by their role, attributes, or the text they contain. Understanding when and how each locator is used will improve your test accuracy.
3. Filter and Chain Locators for Precision – Locators can be filtered to refine element matching. Whether you need to target elements containing specified text or exclude elements that do not contain certain attributes, filtering ensures precision. Additionally, chaining locators can help scope selections to a single locator and ensure that the outer locator match aligns with the intended element.
4. Handle Dynamic Content with Auto-Waiting – Elements on the web page often change state due to asynchronous loading. Playwright resolves a given locator dynamically, ensuring that actions like clicking, filling fields, or asserting values only execute when the element is interactable.
5. Leverage Locator and FrameLocator Classes – When working with complex pages, including those with nested iframes, Playwright provides powerful tools like the Locator and FrameLocator classes. These ensure that your automation tests can accurately locate and interact with elements inside frames or deeply nested structures.
6. Locate Elements Using Accessibility Attributes – A robust way to locate elements in web pages is by using accessibility-based locators such as getByRole(), which identifies elements by their semantic roles. This approach not only improves test stability but also ensures better accessibility compliance.
7. Avoid Overly Complex Selectors – While selectors such as CSS and XPath in Playwright can be used to find elements, relying on long, complex selectors can reduce test maintainability. Instead, opt for structured locators that match key attributes and user-facing identifiers.
8. Write Tests Effectively – Being able to write tests effectively is crucial for end-to-end testing. Utilize tools like the Test Generator to automate element location, which simplifies the process of writing tests and allows for the creation of reliable and maintainable test scripts.

By applying these best practices, you can efficiently locate and interact with elements, ensuring smoother, more reliable test execution. Whether dealing with dynamic elements, elements by the text they contain, or elements based on their attributes, mastering Playwright’s locator strategies will significantly enhance your test automation efforts. Start refining your locator usage today and elevate your Playwright automation game!

FAQ - Playwright Selector and Locators

What are Locators in Playwright?

Locators in Playwright represent a way to interact with elements on a web page.  Unlike a direct reference to an element (like an ElementHandle), a Locator is an abstraction that allows Playwright to efficiently re-query the element in the DOM whenever an action is performed.

This means that even if the page changes or the element is dynamically loaded or reloaded, Playwright can still interact with the element using the locator.

Can I Use XPath with Playwright?

Yes, you can use XPath with Playwright. Playwright supports a wide range of selector engines for identifying elements, and XPath is one of them.

XPath selectors allow you to navigate through elements and attributes in an XML document.

In the context of Playwright, XPath can be used to locate web elements based on their XML path in the HTML document.

What are the Playwright Selector Options?

Playwright supports multiple selector engines, enabling various strategies for selecting elements. Some of the selector options include:

• CSS: Standard CSS selectors to select elements based on their class, ID, attributes, etc.

• XPath: An expression language that allows for the navigation of XML documents to select nodes or node-sets.

• Text: Allows selection of elements based on their text content.

• ID: Shortcut for selecting elements based on their ID attribute.

• Data-testid: A common pattern for selecting elements using a specific attribute often used for testing.

These selectors can be combined and used together to create powerful and precise locators for any element on a page.

What is the Difference Between Locator and Element Handle in Playwright?

The primary difference between a Locator and an ElementHandle in Playwright lies in how they reference and interact with elements on a web page:

• Locator: Represents a query that can be used to find an element or elements every time an action is performed. It is stateless and re-evaluates the query on the DOM whenever it is accessed. This makes locators particularly useful for dealing with dynamic content that might change or be loaded asynchronously.

• ElementHandle: Represents a reference to an actual DOM element. ElementHandles are stateful, meaning they hold a direct reference to a particular element. If the element they reference is removed from the DOM, the handle becomes useless. ElementHandles are useful when you need to perform multiple operations on the same element and are sure that the element won't be recreated or removed.