Introduction

Playwright is a popular end-to-end testing framework that supports multiple languages, including Python, and locators represent a way to identify and interact with elements on a webpage, and are also the central piece of Playwright's auto-waiting and retry-ability, ensuring that actions such as clicks or typing wait for the element to be ready before executing, which makes tests more reliable and resilient.

In this blog post, we'll explore how to effectively use locators in Playwright with Python. Locators play an essential part in interacting with web elements like buttons, forms, and text fields.

Note: Learn how to use locators in Playwright with Python to effectively identify and interact with web elements in your automation scripts.

Prerequisites

Python (3.8 or above)

Playwright Installed (refer blog)

Locators in Playwright

Playwright offers two main approaches to locating elements in Python: the versatile page.locator() method and a range of get_by locators that simplify element selection based on accessibility roles, labels, or placeholders. We'll explore both and explain how to effectively use them.

CSS Selectors with page.locator()

CSS selectors are a fundamental way to select elements based on their attributes, tag names, or positions within the DOM. With page.locator(), Playwright allows you to interact with elements using standard CSS syntax. CSS selectors are flexible and widely supported, making them ideal for selecting both simple and complex elements.

# Locating an element by its class
page.locator('.button-class').click()

# Locating an element by its ID
page.locator('#submit-button').click()

# Filling a form field by its ID
page.locator('#username').fill('myusername')

Advanced CSS Selectors:

Nth-child: Selects an element based on its order within its parent.

page.locator('div > p:nth-child(2)').click()

Best practices:

Avoid overly complex CSS selectors, as they can become brittle when the DOM structure changes. Stick to classes and IDs whenever possible for more stable test cases.

Text-based Locators with page.locator()

Text locators allows you to select elements based on their visible text content. This is particularly useful when dealing with buttons or links that have clear, distinct text content. You can match the text exactly or partially, making text locators flexible for many scenarios.

# Selecting an element by its visible text
page.locator('text="Submit"').click()

# Selecting using partial text
page.locator('text="Sign"').click()

Best practices:

Ensure that the text you’re targeting is unique to avoid ambiguity, especially when there are multiple elements with similar text.

XPath Locators with page.locator()

XPath locators are particularly powerful when CSS selectors or text locators fall short. XPath allows you to select elements based on their position in the document tree, traverse through the HTML structure in ways that CSS selectors cannot. For example, you can select elements based on their position relative to other elements or complex attributes.

# Locating using XPath
page.locator('//button[@id="submit-button"]').click()

# Selecting an element based on its position
page.locator('(//div[@class="example-class"])[2]').click()

Best practices:

Use XPath sparingly as it can make your tests less maintainable. XPath expressions tend to be longer and more complex than CSS selectors, making them harder to debug.

Role-based Locators with page.get_by_role()

Playwright's get_by_role() locator lets you select elements based on their ARIA roles, such as buttons, checkboxes, and other interactive elements. This is extremely useful for web accessibility testing. ARIA roles are often used in web applications to define the role of an element, such as a button, checkbox, or navigation.

# Locating an element by its ARIA role
page.get_by_role('button', name="Submit").click()

# Locating a checkbox by role
page.get_by_role('checkbox', name="Accept Terms").check()

Best practices:

Use get_by_role() to verify that elements are properly labeled and that they fulfill their intended roles for accessibility. It also ensures consistency in automated test cases.

Label-based Locators with page.get_by_label()

If your form fields are associated with labels, get_by_label() is an excellent way to select input elements directly based on the label text. This makes locating elements intuitive, especially when working with forms.

# Selecting an input field by its associated label
page.get_by_label('Email Address').fill('test@example.com')

# Selecting a textarea by its label
page.get_by_label('Message').fill('Your message here')

Best practices:

Ensure that all input fields in your forms have labels for accessibility. This not only helps your tests but also enhances the user experience.

Placeholder-based Locators with page.get_by_placeholder()

If an input field contains a placeholder text, you can use get_by_placeholder() to locate it. This is useful for forms where placeholder text guides users on what to enter.

# Selecting an input field by its placeholder
page.get_by_placeholder('Enter your username').fill('test_user')

Best practices:

Use placeholder-based locators when working with dynamic forms where placeholders are reliable and unique.

Alt Text Locators with page.get_by_alt_text()

To locate images or other non-text elements like images or icons, that use alt attributes, Playwright offers get_by_alt_text(). This is useful when automating media elements like logos or icons.

# Selecting an image using its alt text
page.get_by_alt_text('Company Logo').click()

Best practices:

Ensure all media elements have meaningful alt text. This improves both test automation and the overall accessibility of the website.

Nth-match Locators with page.locator()

When you have multiple elements that match a locator, you can use nth match locators to pick a specific element based on its index.

# Selecting the second button with the same class
page.locator('.button-class').nth(1).click()

Best practices:

Ensure all media elements have meaningful alt text. This improves both test automation and the overall accessibility of the website.

Chained Locators with page.locator()

Chaining locators allows you to select an element inside another element, which is useful for interacting with nested structures in complex HTML.

# Selecting a nested element inside a parent element
parent = page.locator('#parent-div')
parent.locator('text="Click Me"').click()

Best practices:

Use chained locators to avoid ambiguity, especially in cases where the DOM contains many similar elements. Chaining locators based on structure allows you to isolate and interact with specific elements without needing to rely solely on CSS classes or IDs, which might not be unique.

Custom Locators with page.locator()

Custom locators give you full control over the element selection process by allowing you to define your own rules for identifying elements.

# Custom locator using a function
page.locator(lambda element: element.tag_name == "button" and element.text == "Submit").click()

Best practices:

Use custom locators only when necessary. Standard locators like CSS selectors or text locators are typically faster and easier to understand. However, custom locators are invaluable in complex applications where elements may not have easily selectable properties, or where you need to apply specific logic to select them.

How to use locators in Playwright Python