Playwright Locators: The Complete Guide with Real-World Examples

What are Playwright Locators?

A locator identifies an element on a web page.

Unlike traditional automation tools, Playwright continuously evaluates locators before every interaction. This makes tests significantly more stable because Playwright automatically waits until an element is ready before performing actions.

Locators are the foundation of reliable UI automation and should always be chosen carefully.

Why Playwright Locators are Better

Playwright provides:

• Auto Waiting
• Retry Mechanism
• Cross Browser Support
• Better Readability
• More Reliable Tests
• Less Flaky Automation

Instead of relying on fragile XPath expressions, Playwright encourages engineers to locate elements the same way users interact with the application.

getByRole()

Recommended locator.

await page.getByRole('button', {
    name: 'Login'
}).click();

Use for:

• Buttons
• Links
• Checkboxes
• Radio Buttons
• Menus

getByText()

await page.getByText('Welcome Back').click();

Perfect for:

• Links
• Messages
• Navigation
• Labels

getByLabel()

await page.getByLabel('Email')
.fill('admin@test.com');

Excellent for forms.

getByPlaceholder()

await page.getByPlaceholder('Enter Email')
.fill('admin@test.com');

Useful for modern React and Angular applications.

getByTestId()

HTML

<button data-testid="login-btn">
Login
</button>

Playwright

await page.getByTestId('login-btn')
.click();

Enterprise teams often use data-testid because it is one of the most stable locator strategies.

CSS Selector

await page.locator('#username')
.fill('admin');

await page.locator('.submit-btn')
.click();

Use CSS selectors only when semantic locators are unavailable.

XPath

await page.locator("//button[text()='Login']")
.click();

Playwright supports XPath, but Microsoft recommends using semantic locators whenever possible.

Locator Chaining

await page
.getByRole('table')
.getByRole('row')
.nth(2)
.click();

Perfect for large tables.

Filtering

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

Makes selectors cleaner and easier to maintain.

nth(), first(), last()

nth()

await page
.locator('.product')
.nth(2)
.click();

first()

await page
.locator('.card')
.first()
.click();

last()

await page
.locator('.card')
.last()
.click();

Best Practices

Enterprise Locator Priority

Use locators in this order:

1. getByRole()
2. getByLabel()
3. getByPlaceholder()
4. getByTestId()
5. CSS
6. XPath

Common Mistakes

Avoid:

//*[@id="content"]/div[4]/div[2]/button

Avoid:

div > div > button > span

Long XPath and deeply nested CSS selectors make tests fragile.

Best Practices Checklist

• ✔ Prefer semantic locators.
• ✔ Keep selectors readable.
• ✔ Use data-testid for enterprise applications.
• ✔ Avoid long XPath.
• ✔ Build reusable Page Objects.
• ✔ Keep locators independent of styling.

Common Interview Questions

Why is getByRole() recommended?

Because it mirrors how users interact with the application and produces more stable automation.

When should you use XPath?

Only when semantic locators or CSS selectors cannot uniquely identify an element.

What is the most reliable locator?

For enterprise applications: data-testid, followed by getByRole().

Summary

Playwright provides one of the most modern locator APIs available today.

Choosing the right locator strategy dramatically improves automation stability, reduces flaky tests, and makes maintenance easier.

For enterprise projects, prioritize semantic locators and data-testid attributes while avoiding long XPath expressions whenever possible.