# Choosing a Locator Strategy

> **When to use**: When deciding which Playwright locator method to use for an element

## Quick Answer

Use `getByRole()` for everything that has a semantic HTML role (buttons, links, headings, form fields, dialogs). Fall back to `getByLabel()` for form fields, `getByText()` for plain content, and `getByTestId()` only as a last resort for custom components with no accessible role.

## Decision Flowchart

```
Start: You need to locate an element
  |
  v
Does the element have a semantic role?
(button, link, heading, textbox, checkbox, combobox, dialog, img, row, cell, navigation...)
  |
  +-- YES --> Use getByRole('role', { name: 'accessible name' })
  |             |
  |             +-- Need to narrow scope? Chain from a parent role locator:
  |                   getByRole('navigation').getByRole('link', { name: '...' })
  |
  +-- NO
       |
       v
     Is it a form field with a visible <label>?
       |
       +-- YES --> Use getByLabel('label text')
       |
       +-- NO
            |
            v
          Is it static text content (paragraph, span, div with text)?
            |
            +-- YES --> Use getByText('text content')
            |             Prefer { exact: true } when text is short or common
            |
            +-- NO
                 |
                 v
               Does it have a placeholder?
                 |
                 +-- YES --> Use getByPlaceholder('placeholder text')
                 |             (Less preferred -- placeholders disappear on input)
                 |
                 +-- NO
                      |
                      v
                    Does it have a title attribute or alt text?
                      |
                      +-- YES --> Use getByTitle('...') or getByAltText('...')
                      |
                      +-- NO
                           |
                           v
                         Add data-testid="..." to the markup
                         Use getByTestId('identifier')
                         |
                         +--> NEVER fall back to CSS selectors or XPath.
                              Fix the markup instead.
```

## Decision Matrix

| Element Type      | Recommended Locator                                          | Fallback                         | Example                                                        |
| ----------------- | ------------------------------------------------------------ | -------------------------------- | -------------------------------------------------------------- |
| Button            | `getByRole('button', { name })`                              | `getByText()` if role missing    | `getByRole('button', { name: 'Submit' })`                      |
| Link              | `getByRole('link', { name })`                                | `getByText()` for anchor text    | `getByRole('link', { name: 'Sign up' })`                       |
| Text input        | `getByLabel('...')`                                          | `getByRole('textbox', { name })` | `getByLabel('Email address')`                                  |
| Checkbox          | `getByRole('checkbox', { name })`                            | `getByLabel()`                   | `getByRole('checkbox', { name: 'Accept terms' })`              |
| Radio button      | `getByRole('radio', { name })`                               | `getByLabel()`                   | `getByRole('radio', { name: 'Express shipping' })`             |
| Dropdown / Select | `getByRole('combobox', { name })`                            | `getByLabel()`                   | `getByLabel('Country')`                                        |
| Heading           | `getByRole('heading', { name, level })`                      | `getByText()`                    | `getByRole('heading', { name: 'Dashboard', level: 1 })`        |
| Nav link          | chain: `getByRole('navigation').getByRole('link', { name })` | scope with `locator('nav')`      | see detailed example below                                     |
| Table cell        | chain: `getByRole('row').filter().getByRole('cell')`         | `locator('td')` scoped           | see detailed example below                                     |
| Image             | `getByRole('img', { name })`                                 | `getByAltText()`                 | `getByRole('img', { name: 'Company logo' })`                   |
| Modal / Dialog    | `getByRole('dialog')` then chain within                      | `locator('[role="dialog"]')`     | `getByRole('dialog').getByRole('button', { name: 'Confirm' })` |
| Dynamic list item | `.filter({ hasText })` or `.filter({ has })`                 | `nth()` as last resort           | `getByRole('listitem').filter({ hasText: 'Milk' })`            |
| Custom component  | `getByTestId('...')`                                         | Add `data-testid` to markup      | `getByTestId('color-picker')`                                  |

## Detailed Analysis

### Tier 1: `getByRole()` -- Use by Default

The strongest locator. It mirrors how assistive technology and real users perceive the page.

**Pros**

- Resilient to markup refactors (class names, tag changes)
- Enforces accessible markup -- if the locator breaks, your accessibility broke too
- Works across frameworks (React, Vue, Angular, plain HTML)
- Supports filtering by `name`, `level`, `checked`, `pressed`, `expanded`, `selected`

**Cons**

- Requires the element to have a valid ARIA role (implicit or explicit)
- Can match multiple elements when names are duplicated -- scope with chaining

**When it fails**: Custom components with `<div>` soup and no ARIA roles. Fix the component first; add `getByTestId()` only if you cannot change the markup.

---

### Tier 2: `getByLabel()` -- Form Fields

Queries by the associated `<label>` text. This is often the most readable locator for form fields.

**Pros**

- Extremely readable: `getByLabel('Password')` tells you exactly what field
- Works with `<label for="...">`, wrapping `<label>`, and `aria-labelledby`

**Cons**

- Only works for form elements with labels
- Breaks if someone changes label text (but that is usually intentional)

**Use over `getByRole('textbox')`** when the label text is clear and unique. Use `getByRole()` when you need to differentiate between multiple fields with similar labels by role type.

---

### Tier 3: `getByText()` -- Static Content

Finds elements by their visible text content.

**Pros**

- Intuitive for non-interactive text (paragraphs, spans, badges, status messages)
- Supports exact and substring matching

**Cons**

- Fragile if text is dynamic, translated, or duplicated
- Can match parent elements unintentionally -- use `{ exact: true }` or scope the query

**Rule of thumb**: Use `getByText()` for assertions and content verification, not for interactive elements. Interactive elements should use `getByRole()`.

---

### Tier 4: `getByPlaceholder()` -- Inputs Without Labels

Locates by placeholder attribute value.

**Pros**

- Works when labels are missing (search bars, minimal UIs)

**Cons**

- Placeholders disappear when the user types -- poor UX foundation
- Signals missing accessibility (no label)

**Treat as a yellow flag**: If you use this, consider filing a ticket to add a proper label.

---

### Tier 5: `getByTestId()` -- Last Resort

Locates by `data-testid` attribute.

**Pros**

- Fully decoupled from user-facing text and structure
- Stable under UI redesigns

**Cons**

- Invisible to users and assistive technology
- Pollutes production markup (unless stripped in build)
- Tells you nothing about what the element looks like or does

**Use only when**: The component has no semantic role, no label, no text, and you cannot change the markup. Common cases: canvas elements, third-party widgets, complex custom components.

---

### Never Use: Raw CSS Selectors or XPath

```
// DO NOT do this
page.locator('.btn-primary');           // class names change
page.locator('#submit-btn');            // IDs are brittle
page.locator('div > span:nth-child(2)'); // structure changes break this
page.locator('xpath=//div[@class="foo"]'); // unreadable, fragile
```

If you are reaching for a CSS selector, stop. Walk back up the flowchart and find a semantic locator. If none exists, add `data-testid`.

## Real-World Examples

### 1. Buttons

```typescript
// TypeScript
// Standard button
await page.getByRole("button", { name: "Submit" }).click()

// Icon-only button (uses aria-label)
await page.getByRole("button", { name: "Close" }).click()

// Button inside a specific section
await page.getByRole("region", { name: "Billing" }).getByRole("button", { name: "Update" }).click()
```

```javascript
// JavaScript
// Standard button
await page.getByRole("button", { name: "Submit" }).click()

// Icon-only button (uses aria-label)
await page.getByRole("button", { name: "Close" }).click()

// Button inside a specific section
await page.getByRole("region", { name: "Billing" }).getByRole("button", { name: "Update" }).click()
```

---

### 2. Links

```typescript
// TypeScript
// Standard link
await page.getByRole("link", { name: "Sign up" }).click()

// Link inside navigation
await page.getByRole("navigation").getByRole("link", { name: "Pricing" }).click()

// Link with exact match (avoid partial hits)
await page.getByRole("link", { name: "Log in", exact: true }).click()
```

```javascript
// JavaScript
await page.getByRole("link", { name: "Sign up" }).click()

await page.getByRole("navigation").getByRole("link", { name: "Pricing" }).click()

await page.getByRole("link", { name: "Log in", exact: true }).click()
```

---

### 3. Text Inputs

```typescript
// TypeScript
// Input with a visible label -- preferred
await page.getByLabel("Email address").fill("user@example.com")

// When multiple textboxes exist and you need role specificity
await page.getByRole("textbox", { name: "Email address" }).fill("user@example.com")

// Textarea
await page.getByLabel("Message").fill("Hello, world")

// Search input (role = searchbox)
await page.getByRole("searchbox", { name: "Search" }).fill("playwright")
```

```javascript
// JavaScript
await page.getByLabel("Email address").fill("user@example.com")

await page.getByRole("textbox", { name: "Email address" }).fill("user@example.com")

await page.getByLabel("Message").fill("Hello, world")

await page.getByRole("searchbox", { name: "Search" }).fill("playwright")
```

---

### 4. Checkboxes and Radios

```typescript
// TypeScript
// Checkbox
await page.getByRole("checkbox", { name: "Accept terms" }).check()

// Verify checked state
await expect(page.getByRole("checkbox", { name: "Accept terms" })).toBeChecked()

// Radio button
await page.getByRole("radio", { name: "Express shipping" }).check()

// Radio within a group (fieldset with legend)
await page
  .getByRole("group", { name: "Shipping method" })
  .getByRole("radio", { name: "Express" })
  .check()
```

```javascript
// JavaScript
await page.getByRole("checkbox", { name: "Accept terms" }).check()

await expect(page.getByRole("checkbox", { name: "Accept terms" })).toBeChecked()

await page.getByRole("radio", { name: "Express shipping" }).check()

await page
  .getByRole("group", { name: "Shipping method" })
  .getByRole("radio", { name: "Express" })
  .check()
```

---

### 5. Dropdowns and Selects

```typescript
// TypeScript
// Native <select> element
await page.getByLabel("Country").selectOption("Canada")

// Custom combobox (ARIA combobox role)
await page.getByRole("combobox", { name: "Country" }).click()
await page.getByRole("option", { name: "Canada" }).click()

// Listbox pattern
await page.getByRole("combobox", { name: "Font size" }).click()
await page.getByRole("listbox").getByRole("option", { name: "16px" }).click()
```

```javascript
// JavaScript
await page.getByLabel("Country").selectOption("Canada")

await page.getByRole("combobox", { name: "Country" }).click()
await page.getByRole("option", { name: "Canada" }).click()

await page.getByRole("combobox", { name: "Font size" }).click()
await page.getByRole("listbox").getByRole("option", { name: "16px" }).click()
```

---

### 6. Headings

```typescript
// TypeScript
// Specific heading level
await expect(page.getByRole("heading", { name: "Dashboard", level: 1 })).toBeVisible()

// Any heading with that name (when level does not matter)
await expect(page.getByRole("heading", { name: "Recent activity" })).toBeVisible()

// Heading within a section
await page.getByRole("region", { name: "Sidebar" }).getByRole("heading", { name: "Categories" })
```

```javascript
// JavaScript
await expect(page.getByRole("heading", { name: "Dashboard", level: 1 })).toBeVisible()

await expect(page.getByRole("heading", { name: "Recent activity" })).toBeVisible()

await page.getByRole("region", { name: "Sidebar" }).getByRole("heading", { name: "Categories" })
```

---

### 7. Navigation Items

```typescript
// TypeScript
// Link inside the main nav
await page.getByRole("navigation").getByRole("link", { name: "Pricing" }).click()

// When there are multiple navs, narrow by aria-label
await page
  .getByRole("navigation", { name: "Main menu" })
  .getByRole("link", { name: "Pricing" })
  .click()

// Breadcrumb navigation
await page
  .getByRole("navigation", { name: "Breadcrumb" })
  .getByRole("link", { name: "Products" })
  .click()
```

```javascript
// JavaScript
await page.getByRole("navigation").getByRole("link", { name: "Pricing" }).click()

await page
  .getByRole("navigation", { name: "Main menu" })
  .getByRole("link", { name: "Pricing" })
  .click()

await page
  .getByRole("navigation", { name: "Breadcrumb" })
  .getByRole("link", { name: "Products" })
  .click()
```

---

### 8. Table Cells

```typescript
// TypeScript
// Find a cell in a specific row
await page.getByRole("row", { name: /Jane Smith/ }).getByRole("cell", { name: "$120.00" })

// Click an action button in a specific row
await page
  .getByRole("row", { name: /Jane Smith/ })
  .getByRole("button", { name: "Edit" })
  .click()

// Filter rows using .filter() for complex matching
const row = page.getByRole("row").filter({ hasText: "Pending" })
await row.getByRole("button", { name: "Approve" }).click()

// Verify table header exists
await expect(page.getByRole("columnheader", { name: "Status" })).toBeVisible()
```

```javascript
// JavaScript
await page.getByRole("row", { name: /Jane Smith/ }).getByRole("cell", { name: "$120.00" })

await page
  .getByRole("row", { name: /Jane Smith/ })
  .getByRole("button", { name: "Edit" })
  .click()

const row = page.getByRole("row").filter({ hasText: "Pending" })
await row.getByRole("button", { name: "Approve" }).click()

await expect(page.getByRole("columnheader", { name: "Status" })).toBeVisible()
```

---

### 9. Images

```typescript
// TypeScript
// Image with alt text
await expect(page.getByRole("img", { name: "Company logo" })).toBeVisible()

// Alternative: getByAltText (same result, less preferred)
await expect(page.getByAltText("Company logo")).toBeVisible()

// Avatar image inside a card
await page
  .locator("article")
  .filter({ hasText: "Jane Smith" })
  .getByRole("img", { name: "Jane Smith's avatar" })
```

```javascript
// JavaScript
await expect(page.getByRole("img", { name: "Company logo" })).toBeVisible()

await expect(page.getByAltText("Company logo")).toBeVisible()

await page
  .locator("article")
  .filter({ hasText: "Jane Smith" })
  .getByRole("img", { name: "Jane Smith's avatar" })
```

---

### 10. Custom Components (No ARIA Role)

```typescript
// TypeScript
// Third-party color picker with no semantic role
await page.getByTestId("color-picker").click()

// Custom drag-and-drop zone
await page.getByTestId("drop-zone").dispatchEvent("drop", { dataTransfer })

// Canvas-based chart
const chart = page.getByTestId("revenue-chart")
await expect(chart).toBeVisible()
```

```javascript
// JavaScript
await page.getByTestId("color-picker").click()

await page.getByTestId("drop-zone").dispatchEvent("drop", { dataTransfer })

const chart = page.getByTestId("revenue-chart")
await expect(chart).toBeVisible()
```

**Before reaching for `getByTestId`, ask yourself**: Can I add `role` and `aria-label` to this component instead? If yes, do that and use `getByRole()`.

---

### 11. Dynamic Lists

```typescript
// TypeScript
// Filter a list item by text
const item = page.getByRole("listitem").filter({ hasText: "Milk" })
await item.getByRole("button", { name: "Remove" }).click()

// Filter by a child locator
const card = page.locator(".product-card").filter({
  has: page.getByText("Out of stock"),
})
await expect(card).toHaveCount(3)

// Count items in a list
await expect(page.getByRole("listitem")).toHaveCount(5)

// Iterate over list items for complex assertions
for (const item of await page.getByRole("listitem").all()) {
  await expect(item).toContainText("$")
}
```

```javascript
// JavaScript
const item = page.getByRole("listitem").filter({ hasText: "Milk" })
await item.getByRole("button", { name: "Remove" }).click()

const card = page.locator(".product-card").filter({
  has: page.getByText("Out of stock"),
})
await expect(card).toHaveCount(3)

await expect(page.getByRole("listitem")).toHaveCount(5)

for (const item of await page.getByRole("listitem").all()) {
  await expect(item).toContainText("$")
}
```

---

### 12. Modals and Dialogs

```typescript
// TypeScript
// Wait for dialog to appear, then interact within it
const dialog = page.getByRole("dialog", { name: "Confirm deletion" })
await expect(dialog).toBeVisible()
await dialog.getByRole("button", { name: "Delete" }).click()

// Fill a form inside a dialog
const modal = page.getByRole("dialog", { name: "Edit profile" })
await modal.getByLabel("Display name").fill("Jane")
await modal.getByRole("button", { name: "Save" }).click()

// Verify dialog closed
await expect(dialog).toBeHidden()
```

```javascript
// JavaScript
const dialog = page.getByRole("dialog", { name: "Confirm deletion" })
await expect(dialog).toBeVisible()
await dialog.getByRole("button", { name: "Delete" }).click()

const modal = page.getByRole("dialog", { name: "Edit profile" })
await modal.getByLabel("Display name").fill("Jane")
await modal.getByRole("button", { name: "Save" }).click()

await expect(dialog).toBeHidden()
```

## Anti-Patterns to Avoid

| Anti-Pattern                                     | Why It Fails                                            | Use Instead                                                    |
| ------------------------------------------------ | ------------------------------------------------------- | -------------------------------------------------------------- |
| `page.locator('.btn-primary')`                   | Class names change during refactors and redesigns       | `getByRole('button', { name: '...' })`                         |
| `page.locator('#email-input')`                   | IDs are implementation details, not user-visible        | `getByLabel('Email')`                                          |
| `page.locator('div > form > input:first-child')` | Any structural change breaks the selector               | `getByLabel('...')` or `getByRole('textbox', { name: '...' })` |
| `page.locator('[data-testid="submit"]')`         | Raw CSS for test IDs -- use the built-in method         | `getByTestId('submit')`                                        |
| `page.getByText('Submit')` for a button          | Matches any element with that text, not just the button | `getByRole('button', { name: 'Submit' })`                      |
| `page.locator('button').nth(2)`                  | Index-based -- breaks when order changes                | `getByRole('button', { name: '...' })`                         |

## Scoping Strategy: When Multiple Elements Match

When a locator matches more than one element, narrow scope rather than using `nth()`:

```typescript
// BAD: fragile index
page.getByRole("button", { name: "Edit" }).nth(0)

// GOOD: scope to a parent section
page.getByRole("region", { name: "Billing" }).getByRole("button", { name: "Edit" })

// GOOD: scope to a table row
page.getByRole("row", { name: /Order #1234/ }).getByRole("button", { name: "Edit" })

// GOOD: scope with filter
page.locator("article").filter({ hasText: "Draft" }).getByRole("button", { name: "Edit" })
```

## Related

- [Playwright Locators documentation](https://playwright.dev/docs/locators)
- [Playwright Best Practices](https://playwright.dev/docs/best-practices)
- [ARIA Roles reference (MDN)](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles)