Playwright Locators - Comprehensive Guide

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

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.
• 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.
• 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.

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.

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"]');

Combining Selectors:

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.

Pseudo-classes and Pseudo-elements:

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. This approach is especially useful for interacting with elements like buttons, links, and labels where the text content is a significant identifier.

• 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.

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.

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.

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.

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 attributes that are meaningful to the application's users, such as role attributes for accessibility, which tend to be more stable.

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.

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.

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.

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.

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.
• 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.

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.

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.

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.

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"]');

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');

Locator Actions

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

• Clicking: await locator.click();
• Filling Text: await locator.fill('text');
• Getting Text: const text = await locator.textContent();
• Asserting Visibility: await 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()); }

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.

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.

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.

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.

💡 Check also Top Playwright Alternatives.