e2e-selectors

E2E Selectors

Locator Priority

Always prefer locators that reflect how users perceive and interact with the UI. Apply them in this order — use the first that uniquely identifies the element:

1. User-facing semantic locators — getByRole, getByLabel, getByPlaceholder, getByText
2. Test-ID locators — getByTestId (when semantic locators are ambiguous or unstable)
3. Attribute locators — locator('[data-testid="..."]') as a fallback for custom attribute schemes
4. CSS selectors — last resort, only for structural queries with no semantic equivalent

Never use XPath or CSS class selectors tied to styling (e.g., .btn-primary, .MuiButton-root).

Framework Selector Tables

React

Element type	Preferred locator	Example
Button	getByRole('button', { name })	page.getByRole('button', { name: 'Submit' })
Link	getByRole('link', { name })	page.getByRole('link', { name: 'Dashboard' })
Text input	getByLabel('Label text')	page.getByLabel('Email')
Checkbox	getByRole('checkbox', { name })	page.getByRole('checkbox', { name: 'Remember me' })
Heading	getByRole('heading', { name })	page.getByRole('heading', { name: 'Welcome' })
Any text	getByText('text')	page.getByText('No results found')
Ambiguous element	getByTestId('test-id')	page.getByTestId('product-card-42')

Add data-testid attributes to React components only when getByRole or getByLabel cannot uniquely identify the element.

Angular

Element type	Preferred locator	Example
Button	getByRole('button', { name })	page.getByRole('button', { name: 'Save' })
Form field	getByLabel('Label text')	page.getByLabel('Username')
Navigation link	getByRole('link', { name })	page.getByRole('link', { name: 'Profile' })
Any text	getByText('text')	page.getByText('Loading...')
Ambiguous / no ARIA	locator('[data-testid="id"]')	page.locator('[data-testid="user-menu"]')
Angular component root	locator('app-user-card')	page.locator('app-user-card').first()

Use Angular component element selectors (app-*) only when querying the component root itself, not for interacting with its internal elements.

Vue

Element type	Preferred locator	Example
Button	getByRole('button', { name })	page.getByRole('button', { name: 'Confirm' })
Form field	getByLabel('Label text')	page.getByLabel('Search')
Any text	getByText('text')	page.getByText('Cart is empty')
Ambiguous element	locator('[data-test="id"]')	page.locator('[data-test="checkout-btn"]')

Vue projects often use data-test (without -id). Check the project's test-attribute convention in .playwright-agent.json (testIdAttribute key) before defaulting to data-testid.

Plain HTML / No Framework

Element type	Preferred locator	Example
Button / submit	getByRole('button', { name })	page.getByRole('button', { name: 'Login' })
Input with label	getByLabel('Label text')	page.getByLabel('Password')
Placeholder input	getByPlaceholder('text')	page.getByPlaceholder('Search...')
Semantic text	getByText('text')	page.getByText('Welcome back')
ID attribute	locator('#element-id')	page.locator('#main-nav')
CSS — structural only	locator('table > tbody > tr')	page.locator('table > tbody > tr').nth(0)

Anti-Patterns

Never use these locator strategies:

Anti-pattern	Why	Alternative
XPath	Brittle, tied to DOM structure	getByRole, getByLabel
CSS class selectors	Break on styling refactors	getByRole, getByTestId
CSS-in-JS generated classes	Unstable hash suffixes	getByRole, getByTestId
nth-child / nth-of-type	Positional, fragile	Add data-testid to the specific element
Text matching translated strings	Breaks on locale changes	getByTestId or getByRole
Internal component state attributes	Implementation detail	Observable user-facing attributes

DO / DON'T Examples

// DO — semantic role selector
await page.getByRole('button', { name: 'Add to cart' }).click();

// DON'T — CSS class tied to styling
await page.locator('.btn-primary').click();

// DO — label-based input
await page.getByLabel('Email address').fill('[email protected]');

// DON'T — brittle CSS ID (fragile if ID changes)
await page.locator('#email-input-v2').fill('[email protected]');

// DO — test ID for ambiguous elements
await page.getByTestId('product-thumbnail-42').click();

// DON'T — XPath
await page.locator('//div[@class="product"]/img').click();

// DO — scoped locator to avoid false matches
const card = page.getByTestId('user-card').filter({ hasText: 'Alice' });
await card.getByRole('button', { name: 'Edit' }).click();

// DON'T — global text match that could hit multiple elements
await page.getByRole('button', { name: 'Edit' }).click(); // ambiguous if multiple Edit buttons

Playwright Locator API Reference

API	Use case
page.getByRole(role, options)	ARIA role + accessible name
page.getByLabel(text)	Form inputs associated with a <label>
page.getByPlaceholder(text)	Inputs with a placeholder attribute
page.getByText(text)	Visible text content
page.getByAltText(text)	Images with an alt attribute
page.getByTitle(text)	Elements with a title attribute
page.getByTestId(id)	Elements with the configured test-ID attribute
locator.filter({ hasText })	Narrow a locator set by contained text
locator.nth(index)	Select the Nth match (use sparingly)
locator.first() / .last()	First or last match in a list