Skip to content

testdino-hq/playwright-skill / core

playwright-core

Verified

Battle-tested Playwright patterns for writing and debugging reliable E2E, API, component, visual, accessibility, and security tests. Use when you need locator strategy, assertions, fixtures, network mocking, auth flows, trace debugging, or framework recipes for React, Next.js, Vue, and Angular. TypeScript and JavaScript.

FileKindSize
SKILL.mdskill md5.9 KB
accessibility.mdmarkdown55.4 KB
angular.mdmarkdown39.3 KB
api-testing.mdmarkdown51.7 KB
assertions-and-waiting.mdmarkdown28.5 KB
auth-flows.mdmarkdown36.1 KB
authentication.mdmarkdown49.4 KB
browser-apis.mdmarkdown24.2 KB
browser-extensions.mdmarkdown13.5 KB
canvas-and-webgl.mdmarkdown18.6 KB
clock-and-time-mocking.mdmarkdown17.9 KB
common-pitfalls.mdmarkdown43.9 KB
component-testing.mdmarkdown22.1 KB
configuration.mdmarkdown21.9 KB
crud-testing.mdmarkdown31.3 KB
debugging.mdmarkdown29.6 KB
drag-and-drop.mdmarkdown31.7 KB
dynamic-test-selection.mdmarkdown9.8 KB
electron-testing.mdmarkdown20.7 KB
error-and-edge-cases.mdmarkdown39.4 KB
error-index.mdmarkdown61.7 KB
file-operations.mdmarkdown25.1 KB
file-upload-download.mdmarkdown31.5 KB
fixtures-and-hooks.mdmarkdown33.6 KB
flaky-tests.mdmarkdown34.7 KB
forms-and-validation.mdmarkdown38.0 KB
i18n-and-localization.mdmarkdown23.0 KB
iframes-and-shadow-dom.mdmarkdown20.6 KB
locator-strategy.mdmarkdown19.1 KB
locators.mdmarkdown33.2 KB
mobile-and-responsive.mdmarkdown56.8 KB
multi-context-and-popups.mdmarkdown22.7 KB
multi-user-and-collaboration.mdmarkdown18.6 KB
network-mocking.mdmarkdown45.3 KB
nextjs.mdmarkdown35.4 KB
performance-testing.mdmarkdown21.4 KB
react.mdmarkdown38.3 KB
search-and-filter.mdmarkdown43.6 KB
security-testing.mdmarkdown23.4 KB
service-workers-and-pwa.mdmarkdown18.7 KB
test-agents.mdmarkdown6.0 KB
test-architecture.mdmarkdown23.6 KB
test-data-management.mdmarkdown35.1 KB
test-organization.mdmarkdown29.5 KB
third-party-integrations.mdmarkdown28.4 KB
trace-analysis.mdmarkdown11.1 KB
visual-regression.mdmarkdown37.6 KB
vue.mdmarkdown38.2 KB
webmcp-testing.mdmarkdown10.4 KB
websockets-and-realtime.mdmarkdown21.1 KB
when-to-mock.mdmarkdown25.7 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('.legacy-widget button')                // 8. CSS/XPath (last resort)
```

## Recent Locator Helpers (Playwright 1.59+)

> Playwright 1.60 also adds a `description` option to `getByRole()` for disambiguating controls with the same name — see [Role-Based Locators](#disambiguating-by-accessible-description-description-playwright-160) below.

Playwright 1.59 added two useful locator-discovery helpers:

- Interactive locator picking for debugging and exploration
- `locator.normalize()` for rewriting brittle selectors toward Playwright best practices

Use these during debugging, refactors, and authoring. Do not treat them as a substitute for thinking through the most user-facing locator yourself. The best production locator is still usually `getByRole()`, `getByLabel()`, or `getByTestId()` when semantics are unavailable.

### `page.pickLocator()` For Interactive Discovery

**Use when**: You are exploring a page, debugging a selector, or migrating a legacy suite and want Playwright to suggest a locator for the element under your cursor.
**Avoid when**: Writing final production tests without review. Treat the picked locator as a starting point, not the final answer.

**TypeScript**
```typescript
import { test } from '@playwright/test';

test('pick a locator during debugging', async ({ page }) => {
  await page.goto('/checkout');

  const picked = await page.pickLocator();
  console.log(picked);

  await page.cancelPickLocator();
});
```

**JavaScript**
```javascript
const { test } = require('@playwright/test');

test('pick a locator during debugging', async ({ page }) => {
  await page.goto('/checkout');

  const picked = await page.pickLocator();
  console.log(picked);

  await page.cancelPickLocator();
});
```

Review the suggested locator before keeping it. Prefer rewriting it to `getByRole()` or another semantic locator if that makes the test clearer.

### `locator.visible()` For Visible-Only Matching (Playwright 1.63+)

`locator.visible()` returns a locator narrowed to visible elements only. It replaces the `:visible` CSS pseudo-class, which was Playwright-specific syntax that only worked inside `locator()` strings and could not be chained onto a semantic locator.

```javascript
await page.locator('button').visible().click();
```

**Use it for genuinely duplicated UI**, not to paper over strict-mode violations. A responsive layout that renders both a desktop nav and a mobile nav, hiding one by media query, is the real case: both match `getByRole('link', { name: 'Settings' })`, exactly one is visible, and `.visible()` says so directly.

```javascript
// Responsive layout renders both navs; only one is visible at this viewport
await page.getByRole('link', { name: 'Settings' }).visible().click();
```

**When it is the wrong tool**: if two visible elements match, `.visible()` does not help and you still get a strict-mode violation. Scope with chaining or `filter()` instead — see [Locator Chaining and Filtering](#locator-chaining-and-filtering). And if an element is hidden because the app has not finished rendering, `.visible()` narrows the match at query time rather than waiting for the right one to appear; assert on the expected element instead.

### `locator.within()` For Combining Two Locators (Playwright 1.64+)

**Use when**: You already hold two locators, a target and a container, and want "this button, within that dialog" without rewriting either.
**Avoid when**: A plain chain reads just as well: `dialog.getByRole('button', { name: 'Save' })` is still the default.

**Before 1.64** you could only scope by chaining from the container: `container.getByRole(...)`. That forces you to build the target from the container, so a reusable target locator (from a page object, a fixture, or a helper) had to be re-declared for each container it lived in.

**1.64** adds `target.within(container)`, which reads in the natural order and reuses both locators as they are:

```javascript
const saveButton = page.getByRole('button', { name: 'Save' });
const dialog = page.getByTestId('settings-dialog');

await saveButton.within(dialog).click();
```

**Column-like queries**: relative parts such as `nth()` or `first()` are resolved **inside each parent separately**. That turns "the third cell of every row" into one locator instead of a loop:

```javascript
// The third cell of every row, not the third cell in the whole table
const thirdColumn = page.getByRole('cell').nth(2).within(page.getByRole('row'));
await expect(thirdColumn).toHaveText(['Apple', 'Banana', 'Cherry']);
```

Compare `page.getByRole('row').getByRole('cell').nth(2)`, which picks the third cell across the whole result set. When you mean "per row", use `within()`.

### `page.getByRef()` For Aria Snapshot Refs (Playwright 1.64+)

`page.ariaSnapshot({ mode: 'ai' })` labels each element with a short ref such as `e2`. `page.getByRef('e2')` turns that ref back into a locator. This is the bridge between an agent that reads the snapshot and test code that acts on it.

```javascript
const snapshot = await page.ariaSnapshot({ mode: 'ai' });
// ... an agent picks "e2" from the snapshot ...
await page.getByRef('e2').click();
```

Refs are tied to one snapshot of one page state. Use them inside agent loops and exploration scripts; in committed tests, rewrite the target as `getByRole()` so the test survives a re-render.

### `locator.normalize()` For Refactors

**Use when**: You inherit brittle CSS/XPath-heavy locators and want Playwright to suggest a more idiomatic form during cleanup work.
**Avoid when**: You have not yet thought through the element's semantics. A normalized locator can still be less clear than a hand-written role or label locator.

**TypeScript**
```typescript
import { test } from '@playwright/test';

test('normalize a legacy locator', async ({ page }) => {
  await page.goto('/settings');

  const legacy = page.locator('.settings-panel button.save');
  const normalized = await legacy.normalize();

  console.log(normalized);
});
```

**JavaScript**
```javascript
const { test } = require('@playwright/test');

test('normalize a legacy locator', async ({ page }) => {
  await page.goto('/settings');

  const legacy = page.locator('.settings-panel button.save');
  const normalized = await legacy.normalize();

  console.log(normalized);
});
```

Use `normalize()` as a refactoring assistant. The final test should still reflect user intent, not just "whatever selector Playwright could derive."

## 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();
});
```

#### Disambiguating by accessible description (`description`, Playwright 1.60+)

When two controls share the same accessible name but differ by their accessible *description* (`aria-describedby` / `aria-description`), Playwright 1.60's `description` option on `getByRole()` (and the other `getBy*` roles) targets the right one without falling back to CSS.

**TypeScript**
```typescript
// Two "Delete" buttons, distinguished by their helper text / aria-describedby
await page
  .getByRole('button', { name: 'Delete', description: 'Permanently removes this project' })
  .click();

// Pair it with `exact` for tight matching
await page.getByRole('link', {
  name: 'Download',
  description: 'PDF, 2.3 MB',
  exact: true,
}).click();
```

**JavaScript**
```javascript
await page
  .getByRole('button', { name: 'Delete', description: 'Permanently removes this project' })
  .click();
```

Reach for `description` only when `name` + `role` (and `exact`) can't disambiguate — it's a precise tool, not a default.

### 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();

  // Scope a CSS container, then chain a semantic locator (preferred over `>>` selector chaining)
  await page.locator('.sidebar').getByRole('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').getByRole('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();

  // `css:light=` (non-piercing) is undocumented and listed as removed in the 1.58 notes, though 1.64
  // still parses it; prefer scoping from a light-DOM parent
});
```

**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; discouraged 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: 471kUpdated 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: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated 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