Playwright Locators: A Detailed Guide

Finding and interacting with elements is the heart of any UI test. If your locators are weak, your tests break the moment the interface changes. That’s why playwright locators have become a favorite among developers and QA engineers who want stable, readable tests.

Playwright is a modern framework for end-to-end testing. It handles multiple languages such as JavaScript, TypeScript, Python, Java, and C#, and runs on Chromium, Firefox, and WebKit. One of its important features is how it handles element location. Instead of grabbing a reference once, a locator re-evaluates the element every time you act on it. This small design choice removes a lot of the flakiness that older frameworks struggled with.

In this guide, we’ll walk through what Playwright locators are, the types you can use, how to set everything up, and the best practices to keep your tests clean.

What are Playwright Locators

Locators in Playwright are objects that describe how to find one or more elements on a page. Think of a locator as a recipe rather than a snapshot. Each time you click, fill, or assert, Playwright runs that recipe again and grabs the current element from the live DOM.

This approach brings two big advantages:

• Auto-waiting: A locator automatically waits for the element to be ready before acting on it. You don’t need to scatter manual sleeps throughout your code.
• Retry behavior: Playwright keeps retrying the action until the element meets the required conditions or a timeout is reached. This makes tests far less prone to random failures.

Here’s a quick example of a locator in action:

await page.getByRole(‘button’, { name: ‘Submit’ }).click();

Before performing a click, Playwright checks that the element is visible and ready for interaction. If the element isn’t ready yet, Playwright automatically waits and retries. This built-in behavior removes much of the timing-related instability that commonly causes UI tests to fail.

You can create locators in two main ways. The first is page.locator(), which accepts CSS or XPath selectors. The second is the set of built-in locators, which is the recommended choice for most situations. We’ll look at those next.

Types of Playwright Locators

Playwright ships with a handful of built-in locators. Each one targets elements in a way that resembles how a real user perceives the page. Comprehending the types of locators in Playwright helps you pick the most stable option for each element.

• getByRole() — Finds elements by their ARIA role and accessible name. Best for interactive items like buttons, links, and checkboxes.
• getByText() — Locates elements by their visible text content. Great for non-interactive elements such as paragraphs or spans.
• getByLabel() — Finds form controls through their associated label text.
• getByPlaceholder() — Targets inputs using their placeholder text.
• getByAltText() — Locates images or other elements by their alt text.
• getByTitle() — Finds elements by their title attribute.
• getByTestId() — Uses a custom attribute (by default data-testid) for stable identification.

Here are a few of these in practice:

// By role
await page.getByRole('textbox', { name: 'Username' }).fill('peter');
​
// By text
await page.getByText('Welcome back').click();
​
// By label
await page.getByLabel('Email').fill('user@example.com');
​
// By placeholder
await page.getByPlaceholder('Search products').fill('mobile');
​
// By alt text
await page.getByAltText('Company logo').click();
​
// By title
await page.getByTitle('Close dialog').click();
​
// By test ID
await page.getByTestId('login-form').isVisible();

The official recommendation is to favor user-facing locators like getByRole, getByText, and getByLabel. They reflect what users actually see and interact with, so they stay reliable even when the underlying markup shifts.

Steps for Installing and Setting Up Playwright

Step 1: Install Node.js

Before installing Playwright, make sure Node.js is installed on your system. You can verify the installation by running:

node -v
npm -v

Step 2: Create a New Project

Create a folder for your Playwright project and move into it:

mkdir playwright-locators-demo
cd playwright-locators-demo

Step 3: Initialize the Node.js Project

Generate a basic package.json file:

npm init -y

Step 4: Install Playwright

Run the Playwright initialization command:

npm init playwright@latest

During setup, Playwright asks a few questions, such as whether you want to write JavaScript or TypeScript and where to store your test files. Once the setup is complete, Playwright installs the required browsers, including Chromium, Firefox, and WebKit, and creates the necessary project files.

Step 5: Verify the Installation

Run the sample test generated by Playwright:

npx playwright test

If the test executes successfully, your Playwright installation is ready to use.

Step 6: Launch the Playwright Code Generator

Playwright provides a code generator that records your actions and automatically creates test scripts. Launch it using:

npx playwright codegen https://example.com

Step 7: Generate Locator Code

The Playwright code generator opens a browser window and records your interactions with the website. As you click elements, enter text, and navigate through pages, it automatically generates Playwright code and suggests suitable locators for each action. This is a useful way to learn locator strategies, identify reliable selectors, and speed up test creation without having to write locator code from scratch.

How to Use Playwright Locators?

Once your setup is done, using locators follows a simple pattern: create a locator, then perform an action or assertion on it. Because of auto-waiting, you rarely need to add manual waits.

1. Filling Input Fields

Use locators to find input elements and populate them with data:

await page.getByLabel('First name').fill('Peter');
await page.getByPlaceholder('Date of birth').fill('2020-02-02');

2. Clicking Elements

Playwright supports different click actions depending on the interaction you want to simulate:

// Single click
await page.getByRole('button', { name: 'Save' }).click();
​
// Double click
await page.getByText('Item').dblclick();
​
// Right click
await page.getByText('Item').click({ button: 'right' });

3. Working with Checkboxes and Radio Buttons

You can check or uncheck options using label-based locators:

await page.getByLabel('I agree to the terms').check();
await page.getByLabel('Subscribe to newsletter').uncheck();

4. Selecting Dropdown Items

Use selectOption() to choose values from dropdown menus:

await page.getByLabel('Choose a color').selectOption('blue');

5. Making Assertions

Assertions help verify that the application behaves as expected:

await expect(page.getByText('Order confirmed')).toBeVisible();
await expect(page.getByLabel('Subscribe')).toBeChecked();

‍

Filtering and Chaining Locators

Sometimes a single locator isn’t specific enough. Playwright lets you narrow results with filtering and chaining.

6. Filtering Locators

Filtering refines a locator using an additional condition, such as matching text content:

await page
.getByRole('listitem')
.filter({ hasText: 'Table' })
.click();

7. Chaining Locators

Chaining allows you to locate elements within other elements, making selectors more precise:

await page
.getByRole('form', { name: 'Login' })
.getByLabel('Password')
.fill('secret');

‍

Best Practices for Effective Playwright Locator Usage

Good habits with locators save you hours of maintenance. Here are the playwright best practices locators that keep your suite healthy.

1. Start with user-facing locators: Use getByRole(), getByText(), or getByLabel() whenever possible. These locators reflect how users interact with the page and are less likely to break when the underlying HTML changes.
2. Use test IDs when needed: Some elements don’t have meaningful text, labels, or roles. In those cases, a data-testid attribute paired with getByTestId() provides a reliable way to locate elements.
3. Trust Playwright’s auto-waiting: Avoid adding fixed delays or sleep statements. Playwright automatically waits for elements to become ready before performing actions, making tests more reliable and easier to maintain.
4. Use filtering and chaining for precision: When multiple elements match a locator, filtering and chaining help narrow the search without relying on complex selectors.
5. Avoid dynamic class names: Auto-generated class names often change between builds and can make tests fragile. Relying on them usually leads to unnecessary test failures.
6. Use CSS and XPath sparingly: While Playwright supports both, they depend heavily on the page structure. User-facing locators and test IDs are generally more stable and easier to maintain over time.

Using Playwright with HeadSpin

Writing reliable locators is only one part of building effective test automation. Running those tests consistently across browsers and environments, while understanding how the application performs for users, is equally important.

HeadSpin helps teams execute Playwright tests at scale without changing their existing test code. You can continue using Playwright’s built-in locators, assertions, and workflows while running tests across a wider set of browsers and environments from a single platform.

In addition to test execution, HeadSpin provides performance insights amid test runs. Teams can analyze page load behavior, network activity, and user experience metrics to identify performance issues alongside functional failures. This helps connect failed tests and performance bottlenecks to their underlying causes without relying on separate tools.

Conclusion

Playwright locators give you a clean, reliable way to find and interact with elements during automation testing. Their built-in auto-wait and retry behavior reduce flaky tests, and the user-facing locator methods keep your code readable and resilient to UI changes.

Originally Published:- https://www.headspin.io/blog/playwright-locators-guide