Difference between Playwright's locator(), getByRole(), and getByText()

• getByRole – Finds by accessibility role (button, heading, textbox) and accessible name. Most reliable, most accessibility-aligned, most readable.
• getByText – Finds by visible text content. Appropriate when text is the real identifier. Risk: text changes for marketing or localization.
• locator() – Accepts raw CSS or XPath. Most flexible but least reliable, readable, and maintainable. Fallback only.
• All three – Return a lazy Locator resolved with auto-waiting and strict mode at action time.
• Strict mode – Fails if the selector matches multiple elements, catching ambiguous locators early.

How does getByRole work?

getByRole couples the test to the element's semantic role together with its accessible name. This mirrors how a user interacts with the page and how a screen reader announces controls.

// getByRole: most reliable and readable
await page.getByRole('button', { name: 'Transfer' }).click();
await page.getByRole('heading', { name: 'Account Summary' }).isVisible();
await page.getByRole('link', { name: 'View Statement' }).click();
await page.getByRole('textbox', { name: 'Amount' }).fill('5000');
await page.getByRole('alert').textContent(); // Error banner

How does getByText work?

getByText locates by visible text, matching a substring, exact string, or regex. It is reliable when the text is genuinely the stable identifier.

// getByText: good for content assertions
await expect(page.getByText('Transfer Successful')).toBeVisible();
await expect(page.getByText('Insufficient Balance')).toBeVisible();
await page.getByText('View all transactions').click();

// Exact match to avoid partial collisions
await page.getByText('Transfer', { exact: true }).click();

How does the generic locator() work?

The generic locator accepts CSS or XPath and is the most flexible but least stable option.

// locator(): flexible but fragile
await page.locator('.transfer-form button.primary').click();
await page.locator('//div[@class="balance"]/span').textContent();
await page.locator('[data-testid="account-balance"]').textContent();

How do they compare across dimensions?

| Dimension | getByRole | getByText | locator() |
|---|---|---|---|
| Reliability | Best: survives refactors | Good: survives structure changes | Fragile: breaks on any markup change |
| Accessibility | Best: tests and improves a11y | Partial: reflects screen, not role | None: ignores semantics |
| Maintainability | Best: role and name rarely change | Risk: copy edits break it | Poor: generated values change |
| Readability | Best: states intent plainly | Good: readable when text is clear | Poor: long CSS paths say nothing |
| Use case | Interactive elements, landmarks | Content, messages, unique links | Last resort, scoped within a known container |

// Same element, three ways:

// getByRole: "click the button named Transfer" (best)
await page.getByRole('button', { name: 'Transfer' }).click();

// getByText: "click the thing that says Transfer" (good)
await page.getByText('Transfer').click();
// Risk: might match a heading, a link, or a label too

// locator: "click the element at this CSS path" (fragile)
await page.locator('.form-actions > button.btn-primary').click();

What do they share in common?

All three return a Playwright Locator, a lazy handle resolved with auto-waiting and strict mode at action time.

// All three auto-wait and enforce strict mode:

// Auto-waiting: waits until the element is actionable
await page.getByRole('button', { name: 'Transfer' }).click();
// No need for explicit waits or sleeps

// Strict mode: fails if multiple elements match
// This catches ambiguous locators early in development

When should you combine them?

Combine locators for precision, scoping a text match within a role.

// Combine: find the alert that contains a specific message
const error = page.getByRole('alert').filter({
  hasText: 'Insufficient Balance',
});
await expect(error).toBeVisible();

// Combine: find a button within a specific row
const row = page.getByRole('row', { name: 'ACC-001' });
await row.getByRole('button', { name: 'Transfer' }).click();

What are common mistakes?

The first mistake is defaulting to the generic locator by copying selectors from the browser inspector. Those CSS paths are almost always fragile.

The second mistake is using getByText for a button when getByRole is available. getByText does not distinguish a button from a plain span with the same words, so it can match the wrong element.

// WRONG: getByText for a button (might match a label too)
await page.getByText('Transfer').click();

// CORRECT: getByRole specifies the element type
await page.getByRole('button', { name: 'Transfer' }).click();

What are common interview follow-up questions?

• "Can you use getByRole for a div?" Only if the div has an explicit ARIA role. Most semantic elements have implicit roles.
• "What if the text changes for localization?" Use getByRole with an ARIA label that stays consistent, or use getByTestId for localized text.
• "Does getByText match hidden text?" By default no, only visible text. Use the includeHidden option if needed.