Skip to content

zebbern/claude-code-guide / skills/playwright/core

playwright-core

Verified

Battle-tested Playwright patterns for E2E, API, component, visual, accessibility, and security testing. Covers locators, assertions, fixtures, network mocking, auth flows, debugging, and framework recipes for React, Next.js, Vue, and Angular. TypeScript and JavaScript.

FileKindSize
SKILL.mdskill md7.6 KB
accessibility.mdmarkdown53.2 KB
angular.mdmarkdown40.7 KB
api-testing.mdmarkdown51.4 KB
assertions-and-waiting.mdmarkdown26.8 KB
auth-flows.mdmarkdown32.6 KB
authentication.mdmarkdown48.7 KB
browser-apis.mdmarkdown24.0 KB
browser-extensions.mdmarkdown14.6 KB
canvas-and-webgl.mdmarkdown19.8 KB
clock-and-time-mocking.mdmarkdown19.5 KB
common-pitfalls.mdmarkdown44.4 KB
component-testing.mdmarkdown46.4 KB
configuration.mdmarkdown25.0 KB
crud-testing.mdmarkdown31.1 KB
debugging.mdmarkdown26.5 KB
drag-and-drop.mdmarkdown28.7 KB
electron-testing.mdmarkdown22.4 KB
error-and-edge-cases.mdmarkdown39.2 KB
error-index.mdmarkdown58.2 KB
file-operations.mdmarkdown26.1 KB
file-upload-download.mdmarkdown29.6 KB
fixtures-and-hooks.mdmarkdown32.9 KB
flaky-tests.mdmarkdown31.0 KB
forms-and-validation.mdmarkdown39.1 KB
i18n-and-localization.mdmarkdown24.4 KB
iframes-and-shadow-dom.mdmarkdown20.5 KB
locator-strategy.mdmarkdown20.1 KB
locators.mdmarkdown28.3 KB
mobile-and-responsive.mdmarkdown58.2 KB
multi-context-and-popups.mdmarkdown22.3 KB
multi-user-and-collaboration.mdmarkdown20.0 KB
network-mocking.mdmarkdown44.8 KB
nextjs.mdmarkdown36.1 KB
performance-testing.mdmarkdown23.0 KB
react.mdmarkdown38.6 KB
search-and-filter.mdmarkdown43.2 KB
security-testing.mdmarkdown25.2 KB
service-workers-and-pwa.mdmarkdown20.3 KB
test-architecture.mdmarkdown24.5 KB
test-data-management.mdmarkdown35.7 KB
test-organization.mdmarkdown30.5 KB
third-party-integrations.mdmarkdown30.4 KB
visual-regression.mdmarkdown35.4 KB
vue.mdmarkdown38.6 KB
websockets-and-realtime.mdmarkdown20.8 KB
when-to-mock.mdmarkdown28.0 KB

locators.md

View on GitHub
# Locators

> **When to use**: Every time you need to find an element on the page. Start here before reaching for CSS or XPath.
> **Prerequisites**: [core/configuration.md](configuration.md)

## Quick Reference

```typescript
// Priority order — use the first one that works:
page.getByRole("button", { name: "Submit" }) // 1. Role (default)
page.getByLabel("Email address") // 2. Label (form fields)
page.getByText("Welcome back") // 3. Text (non-interactive)
page.getByPlaceholder("Search...") // 4. Placeholder
page.getByAltText("Company logo") // 5. Alt text (images)
page.getByTitle("Close dialog") // 6. Title attribute
page.getByTestId("checkout-summary") // 7. Test ID (last semantic option)
page.locator("css=.legacy-widget >> internal:role=button") // 8. CSS/XPath (last resort)
```

## Patterns

### Role-Based Locators (Default Choice)

**Use when**: Always. This is your starting point for every element.
**Avoid when**: The element has no ARIA role and adding one is outside your control.

Role-based locators mirror how assistive technology sees your page. They survive refactors, class renames, and component library swaps.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("role-based locators cover most UI elements", async ({ page }) => {
  await page.goto("/dashboard")

  // Buttons — matches <button>, <input type="submit">, role="button"
  await page.getByRole("button", { name: "Save changes" }).click()

  // Links — matches <a href>
  await page.getByRole("link", { name: "View profile" }).click()

  // Headings — use level to target specific h1-h6
  await expect(page.getByRole("heading", { name: "Dashboard", level: 1 })).toBeVisible()

  // Text inputs — match by accessible name (label association)
  await page.getByRole("textbox", { name: "Email" }).fill("user@example.com")

  // Checkboxes and radios
  await page.getByRole("checkbox", { name: "Remember me" }).check()
  await page.getByRole("radio", { name: "Monthly billing" }).click()

  // Dropdowns — <select> elements
  await page.getByRole("combobox", { name: "Country" }).selectOption("US")

  // Navigation landmarks
  const nav = page.getByRole("navigation", { name: "Main" })
  await expect(nav.getByRole("link", { name: "Settings" })).toBeVisible()

  // Tables
  const table = page.getByRole("table", { name: "Recent orders" })
  await expect(table.getByRole("row")).toHaveCount(5)

  // Dialogs
  const dialog = page.getByRole("dialog", { name: "Confirm deletion" })
  await dialog.getByRole("button", { name: "Delete" }).click()

  // Exact matching — prevents "Log" from matching "Log out"
  await page.getByRole("button", { name: "Log", exact: true }).click()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("role-based locators cover most UI elements", async ({ page }) => {
  await page.goto("/dashboard")

  await page.getByRole("button", { name: "Save changes" }).click()
  await page.getByRole("link", { name: "View profile" }).click()
  await expect(page.getByRole("heading", { name: "Dashboard", level: 1 })).toBeVisible()
  await page.getByRole("textbox", { name: "Email" }).fill("user@example.com")
  await page.getByRole("checkbox", { name: "Remember me" }).check()
  await page.getByRole("radio", { name: "Monthly billing" }).click()
  await page.getByRole("combobox", { name: "Country" }).selectOption("US")

  const nav = page.getByRole("navigation", { name: "Main" })
  await expect(nav.getByRole("link", { name: "Settings" })).toBeVisible()

  const dialog = page.getByRole("dialog", { name: "Confirm deletion" })
  await dialog.getByRole("button", { name: "Delete" }).click()

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

### Label-Based Locators

**Use when**: Targeting form fields that have associated `<label>` elements or `aria-label`.
**Avoid when**: The element is not a form control. Use `getByRole` with the accessible name instead — it covers labels too.

`getByLabel` is a shortcut for form fields. It matches `<label for="">`, wrapping `<label>`, and `aria-label` / `aria-labelledby`.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("fill a registration form using labels", async ({ page }) => {
  await page.goto("/register")

  await page.getByLabel("First name").fill("Jane")
  await page.getByLabel("Last name").fill("Doe")
  await page.getByLabel("Email address").fill("jane@example.com")
  await page.getByLabel("Password", { exact: true }).fill("s3cure!Pass")
  await page.getByLabel("Confirm password").fill("s3cure!Pass")
  await page.getByLabel("I agree to the terms").check()

  await page.getByRole("button", { name: "Create account" }).click()
  await expect(page.getByRole("heading", { name: "Welcome" })).toBeVisible()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("fill a registration form using labels", async ({ page }) => {
  await page.goto("/register")

  await page.getByLabel("First name").fill("Jane")
  await page.getByLabel("Last name").fill("Doe")
  await page.getByLabel("Email address").fill("jane@example.com")
  await page.getByLabel("Password", { exact: true }).fill("s3cure!Pass")
  await page.getByLabel("Confirm password").fill("s3cure!Pass")
  await page.getByLabel("I agree to the terms").check()

  await page.getByRole("button", { name: "Create account" }).click()
  await expect(page.getByRole("heading", { name: "Welcome" })).toBeVisible()
})
```

### Text-Based Locators

**Use when**: Targeting non-interactive content — status messages, paragraphs, banners, labels outside forms.
**Avoid when**: The element is a button, link, heading, or form field. Use `getByRole` instead.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("verify text content on the page", async ({ page }) => {
  await page.goto("/order/confirmation")

  // Substring match (default)
  await expect(page.getByText("Order confirmed")).toBeVisible()

  // Exact match — use when substring hits multiple elements
  await expect(page.getByText("Order #12345", { exact: true })).toBeVisible()

  // Regex match — for dynamic content patterns
  await expect(page.getByText(/Order #\d+/)).toBeVisible()

  // DO NOT use getByText for buttons or links:
  // Bad:  page.getByText('Submit')
  // Good: page.getByRole('button', { name: 'Submit' })
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("verify text content on the page", async ({ page }) => {
  await page.goto("/order/confirmation")

  await expect(page.getByText("Order confirmed")).toBeVisible()
  await expect(page.getByText("Order #12345", { exact: true })).toBeVisible()
  await expect(page.getByText(/Order #\d+/)).toBeVisible()
})
```

### Test ID Locators

**Use when**: No semantic locator works — the element has no accessible role, label, or stable text. Common with custom canvas-rendered components, complex data grids, or third-party widgets.
**Avoid when**: Any semantic locator (`getByRole`, `getByLabel`, `getByText`) can identify the element. Test IDs are invisible to users and assistive technology.

Configure the attribute name once in `playwright.config`:

**TypeScript**

```typescript
// playwright.config.ts
import { defineConfig } from "@playwright/test"

export default defineConfig({
  use: {
    testIdAttribute: "data-testid", // default; change to match your codebase
  },
})
```

```typescript
import { test, expect } from "@playwright/test"

test("interact with a custom widget using test IDs", async ({ page }) => {
  await page.goto("/analytics")

  // Only when the chart component exposes no accessible roles
  const chart = page.getByTestId("revenue-chart")
  await expect(chart).toBeVisible()
  await chart.click({ position: { x: 150, y: 75 } })

  await expect(page.getByTestId("chart-tooltip")).toContainText("$12,400")
})
```

**JavaScript**

```javascript
// playwright.config.js
const { defineConfig } = require("@playwright/test")

module.exports = defineConfig({
  use: {
    testIdAttribute: "data-testid",
  },
})
```

```javascript
const { test, expect } = require("@playwright/test")

test("interact with a custom widget using test IDs", async ({ page }) => {
  await page.goto("/analytics")

  const chart = page.getByTestId("revenue-chart")
  await expect(chart).toBeVisible()
  await chart.click({ position: { x: 150, y: 75 } })

  await expect(page.getByTestId("chart-tooltip")).toContainText("$12,400")
})
```

### CSS/XPath — Last Resort

**Use when**: You have zero control over the markup, no test IDs, no accessible names, and no way to add them. Legacy apps with generated class names and no semantic HTML.
**Avoid when**: Any other locator type works. Always.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("legacy app with no semantic markup", async ({ page }) => {
  await page.goto("/legacy-admin")

  // CSS — prefer short, structural selectors over fragile class chains
  await page.locator('table.report-grid td:has-text("Overdue")').first().click()

  // XPath — only when CSS cannot express the query (e.g., text + ancestor traversal)
  await page.locator('xpath=//td[contains(text(),"Overdue")]/ancestor::tr//button').click()

  // Combine CSS with Playwright pseudo-selectors for resilience
  await page.locator('.sidebar >> role=button[name="Expand"]').click()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("legacy app with no semantic markup", async ({ page }) => {
  await page.goto("/legacy-admin")

  await page.locator('table.report-grid td:has-text("Overdue")').first().click()
  await page.locator('xpath=//td[contains(text(),"Overdue")]/ancestor::tr//button').click()
  await page.locator('.sidebar >> role=button[name="Expand"]').click()
})
```

### Locator Chaining and Filtering

**Use when**: A single locator matches multiple elements and you need to narrow down by context, content, or position.
**Avoid when**: A direct `getByRole` with `name` already uniquely identifies the element.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("chaining and filtering locators", async ({ page }) => {
  await page.goto("/products")

  // Chain: scope a locator within another
  const productCard = page.getByRole("listitem").filter({ hasText: "Running Shoes" })
  await productCard.getByRole("button", { name: "Add to cart" }).click()

  // Filter by child locator — more precise than hasText
  const row = page.getByRole("row").filter({
    has: page.getByRole("cell", { name: "Premium Plan" }),
  })
  await row.getByRole("button", { name: "Upgrade" }).click()

  // Filter with hasNot — exclude elements containing a child
  const availableItems = page.getByRole("listitem").filter({
    hasNot: page.getByText("Sold out"),
  })
  await expect(availableItems).toHaveCount(3)

  // Filter with hasNotText — exclude by text content
  const nonFeatured = page.getByRole("listitem").filter({
    hasNotText: "Featured",
  })

  // Positional: nth, first, last — use sparingly, only when order is stable
  const thirdItem = page.getByRole("listitem").nth(2) // 0-indexed
  const firstItem = page.getByRole("listitem").first()
  const lastItem = page.getByRole("listitem").last()

  // Combining multiple filters
  const activeAdminRow = page
    .getByRole("row")
    .filter({ has: page.getByRole("cell", { name: "Admin" }) })
    .filter({ has: page.getByText("Active") })
  await expect(activeAdminRow).toHaveCount(1)
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("chaining and filtering locators", async ({ page }) => {
  await page.goto("/products")

  const productCard = page.getByRole("listitem").filter({ hasText: "Running Shoes" })
  await productCard.getByRole("button", { name: "Add to cart" }).click()

  const row = page.getByRole("row").filter({
    has: page.getByRole("cell", { name: "Premium Plan" }),
  })
  await row.getByRole("button", { name: "Upgrade" }).click()

  const availableItems = page.getByRole("listitem").filter({
    hasNot: page.getByText("Sold out"),
  })
  await expect(availableItems).toHaveCount(3)

  const thirdItem = page.getByRole("listitem").nth(2)
  const firstItem = page.getByRole("listitem").first()
  const lastItem = page.getByRole("listitem").last()

  const activeAdminRow = page
    .getByRole("row")
    .filter({ has: page.getByRole("cell", { name: "Admin" }) })
    .filter({ has: page.getByText("Active") })
  await expect(activeAdminRow).toHaveCount(1)
})
```

### Frame Locators

**Use when**: Interacting with content inside `<iframe>` or `<frame>` elements — payment widgets, embedded editors, third-party widgets.
**Avoid when**: The content is in the main frame or a Shadow DOM (use piercing instead).

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("interact with content inside an iframe", async ({ page }) => {
  await page.goto("/checkout")

  // Locate the iframe, then use normal locators inside it
  const paymentFrame = page.frameLocator('iframe[title="Payment"]')
  await paymentFrame.getByLabel("Card number").fill("4242424242424242")
  await paymentFrame.getByLabel("Expiration").fill("12/28")
  await paymentFrame.getByLabel("CVC").fill("123")
  await paymentFrame.getByRole("button", { name: "Pay" }).click()

  // Nested iframes — chain frameLocator calls
  const nestedFrame = page.frameLocator("#outer-frame").frameLocator("#inner-frame")
  await expect(nestedFrame.getByText("Payment confirmed")).toBeVisible()

  // Frame by nth index — when no better selector exists
  const secondFrame = page.frameLocator("iframe").nth(1)
  await expect(secondFrame.getByRole("heading")).toBeVisible()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("interact with content inside an iframe", async ({ page }) => {
  await page.goto("/checkout")

  const paymentFrame = page.frameLocator('iframe[title="Payment"]')
  await paymentFrame.getByLabel("Card number").fill("4242424242424242")
  await paymentFrame.getByLabel("Expiration").fill("12/28")
  await paymentFrame.getByLabel("CVC").fill("123")
  await paymentFrame.getByRole("button", { name: "Pay" }).click()

  const nestedFrame = page.frameLocator("#outer-frame").frameLocator("#inner-frame")
  await expect(nestedFrame.getByText("Payment confirmed")).toBeVisible()

  const secondFrame = page.frameLocator("iframe").nth(1)
  await expect(secondFrame.getByRole("heading")).toBeVisible()
})
```

### Shadow DOM Piercing

**Use when**: Targeting elements inside web components that use Shadow DOM (custom elements, design system components, Salesforce Lightning).
**Avoid when**: The element is in a regular DOM or iframe.

Playwright pierces open Shadow DOM automatically with `locator()`. The `getByRole` / `getByText` family also pierces shadow roots by default.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("interact with Shadow DOM elements", async ({ page }) => {
  await page.goto("/design-system-demo")

  // getByRole automatically pierces open Shadow DOM — just use it normally
  await page.getByRole("button", { name: "Toggle menu" }).click()

  // locator() with CSS also pierces shadow roots by default
  await page.locator("my-dropdown").getByRole("option", { name: "Settings" }).click()

  // Chain into nested shadow DOMs
  await page.locator("my-app").locator("my-sidebar").getByRole("link", { name: "Profile" }).click()

  // If you explicitly need non-piercing behavior (rare), use css=light/
  // await page.locator('css:light=.outer-only').click();
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("interact with Shadow DOM elements", async ({ page }) => {
  await page.goto("/design-system-demo")

  await page.getByRole("button", { name: "Toggle menu" }).click()
  await page.locator("my-dropdown").getByRole("option", { name: "Settings" }).click()

  await page.locator("my-app").locator("my-sidebar").getByRole("link", { name: "Profile" }).click()
})
```

### Dynamic Content — Waiting for Elements

**Use when**: Elements appear after API calls, animations, lazy loading, or route transitions.
**Avoid when**: The element is already on the page. Playwright auto-waits on actions, so explicit waits are rarely needed.

Never use `page.waitForTimeout()`. Use auto-waiting assertions or explicit event waits.

**TypeScript**

```typescript
import { test, expect } from "@playwright/test"

test("handle dynamic content without manual waits", async ({ page }) => {
  await page.goto("/search")

  // Auto-waiting: actions like click(), fill() wait for the element automatically
  await page.getByRole("textbox", { name: "Search" }).fill("playwright")
  await page.getByRole("button", { name: "Search" }).click()

  // Web-first assertion: auto-retries until timeout (default 5s)
  await expect(page.getByRole("listitem")).toHaveCount(10)

  // Wait for a specific element to appear after an async operation
  await expect(page.getByRole("heading", { name: "Results" })).toBeVisible()

  // Wait for loading indicators to disappear
  await expect(page.getByRole("progressbar")).toBeHidden()

  // Wait for network-dependent content: wait for response then assert
  const responsePromise = page.waitForResponse("**/api/search*")
  await page.getByRole("button", { name: "Load more" }).click()
  await responsePromise
  await expect(page.getByRole("listitem")).toHaveCount(20)

  // Wait for URL change after navigation
  await page.getByRole("link", { name: "First result" }).click()
  await page.waitForURL("**/results/**")
  await expect(page.getByRole("heading", { level: 1 })).toBeVisible()
})
```

**JavaScript**

```javascript
const { test, expect } = require("@playwright/test")

test("handle dynamic content without manual waits", async ({ page }) => {
  await page.goto("/search")

  await page.getByRole("textbox", { name: "Search" }).fill("playwright")
  await page.getByRole("button", { name: "Search" }).click()

  await expect(page.getByRole("listitem")).toHaveCount(10)
  await expect(page.getByRole("heading", { name: "Results" })).toBeVisible()
  await expect(page.getByRole("progressbar")).toBeHidden()

  const responsePromise = page.waitForResponse("**/api/search*")
  await page.getByRole("button", { name: "Load more" }).click()
  await responsePromise
  await expect(page.getByRole("listitem")).toHaveCount(20)

  await page.getByRole("link", { name: "First result" }).click()
  await page.waitForURL("**/results/**")
  await expect(page.getByRole("heading", { level: 1 })).toBeVisible()
})
```

## Decision Guide

| Element Type       | Recommended Locator                            | Example                                                 | Why                                                            |
| ------------------ | ---------------------------------------------- | ------------------------------------------------------- | -------------------------------------------------------------- |
| Button             | `getByRole('button', { name })`                | `getByRole('button', { name: 'Submit' })`               | Matches `<button>`, `<input type="submit">`, `role="button"`   |
| Link               | `getByRole('link', { name })`                  | `getByRole('link', { name: 'Home' })`                   | Matches any `<a href>` regardless of styling                   |
| Text input         | `getByRole('textbox', { name })`               | `getByRole('textbox', { name: 'Email' })`               | Matches by accessible name (label)                             |
| Password input     | `getByLabel()`                                 | `getByLabel('Password')`                                | Password fields have no distinct role; label is the best match |
| Checkbox           | `getByRole('checkbox', { name })`              | `getByRole('checkbox', { name: 'Agree' })`              | Also use `.check()` / `.uncheck()` instead of `.click()`       |
| Radio button       | `getByRole('radio', { name })`                 | `getByRole('radio', { name: 'Express' })`               | Group radios with `getByRole('radiogroup')`                    |
| Select/dropdown    | `getByRole('combobox', { name })`              | `getByRole('combobox', { name: 'Country' })`            | Native `<select>` maps to combobox role                        |
| Custom dropdown    | `getByRole('listbox')` + `getByRole('option')` | Click trigger, then `getByRole('option', { name })`     | ARIA listbox pattern for custom dropdowns                      |
| Heading            | `getByRole('heading', { name, level })`        | `getByRole('heading', { name: 'Dashboard', level: 2 })` | Use `level` to distinguish h1-h6                               |
| Table              | `getByRole('table', { name })`                 | `getByRole('table', { name: 'Users' })`                 | Chain with `getByRole('row')`, `getByRole('cell')`             |
| Table row          | `getByRole('row').filter({ has })`             | `.filter({ has: getByRole('cell', { name: 'Jane' }) })` | Filter rows by cell content                                    |
| Navigation         | `getByRole('navigation', { name })`            | `getByRole('navigation', { name: 'Main' })`             | Matches `<nav>` with `aria-label`                              |
| Dialog/modal       | `getByRole('dialog', { name })`                | `getByRole('dialog', { name: 'Confirm' })`              | Scope all dialog interactions under this                       |
| Tab                | `getByRole('tab', { name })`                   | `getByRole('tab', { name: 'Settings' })`                | Use with `getByRole('tabpanel')`                               |
| Image              | `getByAltText()`                               | `getByAltText('User avatar')`                           | Matches the `alt` attribute                                    |
| Form field (any)   | `getByLabel()`                                 | `getByLabel('Date of birth')`                           | Fallback when role is ambiguous (date pickers, custom inputs)  |
| Static text        | `getByText()`                                  | `getByText('No results found')`                         | Non-interactive content only                                   |
| No semantic markup | `getByTestId()`                                | `getByTestId('sparkline-chart')`                        | Last semantic option before CSS                                |
| Iframe content     | `frameLocator()` then any locator              | `frameLocator('#payment').getByLabel('Card')`           | Required for cross-frame access                                |
| Shadow DOM         | `getByRole()` / `locator()`                    | Works automatically                                     | Playwright pierces open shadow roots by default                |

## Anti-Patterns

| Don't Do This                                               | Problem                                                                | Do This Instead                                                                 |
| ----------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `page.locator('.btn-primary')`                              | Breaks when CSS classes change (renames, CSS modules, Tailwind)        | `page.getByRole('button', { name: 'Save' })`                                    |
| `page.locator('#submit-btn')`                               | IDs are implementation details; often auto-generated                   | `page.getByRole('button', { name: 'Submit' })`                                  |
| `page.locator('div > span:nth-child(3)')`                   | Breaks on any DOM restructure                                          | `page.getByText('Expected content')` or `getByTestId()`                         |
| `page.locator('xpath=//div[@class="form"]//input[2]')`      | Fragile, unreadable, position-dependent                                | `page.getByLabel('Last name')`                                                  |
| `page.getByText('Submit')` for a button                     | Text locators don't assert the element is interactive                  | `page.getByRole('button', { name: 'Submit' })`                                  |
| `page.locator('.item').nth(0)` on dynamic lists             | Index changes when items are added/removed/reordered                   | `.filter({ hasText: 'Specific item' })`                                         |
| `page.getByText('Aceptar')` hardcoded i18n text             | Fails when locale changes                                              | `page.getByRole('button', { name: /accept/i })` or `getByTestId('confirm-btn')` |
| `await page.waitForTimeout(3000)`                           | Arbitrary delay; too slow in fast environments, too short in slow ones | `await expect(locator).toBeVisible()`                                           |
| `page.locator('.card').locator('.card-title').locator('a')` | Deep CSS chaining breaks on any structural change                      | `page.getByRole('link', { name: 'Card title text' })`                           |
| `page.$('selector')` (ElementHandle API)                    | Returns a snapshot, not auto-waiting; deprecated pattern               | `page.locator('selector')` — locators are lazy and auto-wait                    |
| `page.locator('text=Click here')`                           | Legacy text selector syntax                                            | `page.getByText('Click here')` or `getByRole` with name                         |
| Multiple locators for one element in sequence               | Each `locator()` call in a chain restarts the search                   | Store as variable: `const btn = page.getByRole('button', { name: 'Save' })`     |

## Troubleshooting

### "strict mode violation" — locator matches multiple elements

**Cause**: Your locator is not specific enough and Playwright refuses to pick one for you.

```typescript
// Error: locator.click: strict mode violation, getByRole('button') resolved to 5 elements
await page.getByRole("button").click() // Too broad

// Fix 1: Add a name filter
await page.getByRole("button", { name: "Save" }).click()

// Fix 2: Scope within a parent
await page.getByRole("dialog").getByRole("button", { name: "Save" }).click()

// Fix 3: Use exact matching when names are substrings of each other
await page.getByRole("button", { name: "Save", exact: true }).click()

// Fix 4: Use filter to narrow down
await page.getByRole("button").filter({ hasText: "Save draft" }).click()

// Debug: see what matched
console.log(await page.getByRole("button").all()) // list all matches
```

### Element exists but locator times out

**Cause**: The element is inside an iframe, Shadow DOM, or is obscured/hidden.

```typescript
// Check if element is inside an iframe
const frame = page.frameLocator("iframe")
await frame.getByRole("button", { name: "Submit" }).click()

// Check if element is in a Shadow DOM — getByRole pierces automatically,
// but page.$() and CSS selectors may not. Switch to getByRole.

// Check if element is hidden (display: none, visibility: hidden, opacity: 0)
// Use toBeVisible() to confirm, or toBeAttached() if hidden is expected
await expect(page.getByRole("button", { name: "Submit" })).toBeAttached()
```

### `getByRole` doesn't find the element

**Cause**: The element's implicit ARIA role doesn't match what you expect, or it has no role.

```typescript
// Debug: inspect the accessibility tree
const snapshot = await page.accessibility.snapshot()
console.log(JSON.stringify(snapshot, null, 2))

// Common mismatches:
// - <div onclick="..."> has no button role → add role="button" or use <button>
// - <input type="text"> with no label has no accessible name → add <label> or aria-label
// - <a> without href has no link role → add href or role="link"

// Fallback chain: try getByLabel → getByText → getByTestId → locator()
```

## Related

- [core/locator-strategy.md](locator-strategy.md) — deep-dive decision framework for choosing locator strategies at the project level
- [core/assertions-and-waiting.md](assertions-and-waiting.md) — pair locators with web-first assertions
- [pom/page-object-model.md](../pom/page-object-model.md) — encapsulate locators in page objects
- [core/iframes-and-shadow-dom.md](iframes-and-shadow-dom.md) — advanced iframe and Shadow DOM patterns
- [core/i18n-and-localization.md](i18n-and-localization.md) — locator strategies for internationalized apps
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall