Locators

Playwright Locator Conventions

Apply these locator rules whenever writing or reviewing Playwright code in this project. The priority ladder is strict — drop to a lower tier only when the higher tier is genuinely unavailable.

The Priority Ladder

Choose the highest tier that resolves the target element. Each lower tier is less stable and more likely to break on UI changes.

1. getByTestId('description-input') — preferred. Every interactive element should have a data-testid.
2. getByRole('button', { name: 'Save' }) — semantic role + accessible name.
3. getByLabel('Description') — form field by its label.
4. getByPlaceholder('Search...') — form field by placeholder.
5. getByTitle('Delete') — element by title attribute.
6. Chained: page.getByTestId('panel-edit').getByRole('button', { name: 'Save' }) — narrow scope.
7. Class / id: page.locator('#main-content'), page.locator('.sidebar').
8. getByText('Welcome') / getByAltText('logo') — brittle to copy/asset changes.
9. CSS / XPath: page.locator('div > .item:nth-child(3)'), XPath strings — last resort, must include a comment explaining why no higher tier works.

Data-Testid Naming Convention

Test IDs follow the pattern <descriptiveName>-<controlType>. Apply this convention when requesting test IDs from the app team or when defining locators.

Grid row testids include the record ID so rows are directly addressable without scanning.

Locator Declaration Patterns

Static locators on the page object

Declare locators as readonly properties in the constructor:

export class UserEditPage extends BaseEditPage {
  readonly emailInput: Locator;
  readonly saveButton: Locator;

  constructor(page: Page) {
    super(page);
    this.emailInput = page.getByTestId('email-input');
    this.saveButton = page.getByTestId('save-button');
  }
}

Parameterized locators (arrow functions)

For locators that depend on a runtime value, declare arrow function properties:

readonly rowById = (id: string) => this.page.getByTestId(`usersGrid-row-${id}`);
readonly editButtonById = (id: string) => this.page.getByTestId(`usersGrid-editBtn-${id}`);
readonly cellForRow = (id: string, column: string) =>
  this.rowById(id).locator(`[column="${column}"]`);

Call them in tests:

await usersPage.editButtonById('42').click();
await expect(usersPage.cellForRow('42', 'email')).toHaveText('user@example.com');

Naming locators

Use purpose-specific names, not control-type-only names:

• Good: categoryDropdown, descriptionInput, addUserButton, confirmDeleteModal
• Bad: dropdown1, input, button, modal

Narrowing and Filtering

When a locator resolves to multiple elements, use these patterns instead of CSS index selectors:

// Filter by content
page.getByRole('row').filter({ hasText: 'Active' });

// Filter by child locator
page.getByRole('row').filter({ has: page.getByRole('button', { name: 'Edit' }) });

// Exclude matches
page.getByRole('row').filter({ hasNot: page.getByText('Archived') });

// Positional
page.getByRole('row').first();
page.getByRole('row').last();
page.getByRole('row').nth(2);

// Visibility (resolves 'resolved to N elements' errors when some are hidden)
page.getByRole('button', { name: 'Save' }).filter({ visible: true });

Handling Missing Test IDs

When an element lacks a data-testid:

1. Fall back to the next tier (role, label, etc.).
2. Add a TODO comment with the ticket key so the missing testid is tracked:

// TODO: <PREFIX>-NNNN — Missing data-testid for save button. Request from app team.
this.saveButton = page.getByRole('button', { name: 'Save' });

Never silently use a lower-tier locator and forget about it.

Anti-Patterns

Reject these patterns in code review:

Common Errors and Fixes

• locator.click: Timeout — locator targets the wrong element, an overlay is blocking it, or the page isn't loaded. Take a snapshot with playwright-cli snapshot to verify the testid exists.
• locator resolved to N elements — narrow with .filter({ visible: true }), .first(), or a more specific parent.
• fill: Element is not an input — locator resolved to a wrapper. Chain .locator('input') to drill in.

Quick Reference: Decision Flow

Need to target an element
  ↓
Does it have data-testid?  → YES → getByTestId
  ↓ NO
Does it have a semantic role + accessible name? → YES → getByRole
  ↓ NO
Does it have a label / placeholder / title? → YES → getByLabel / getByPlaceholder / getByTitle
  ↓ NO
Can you target a parent that has a testid and chain? → YES → getByTestId('parent').getByRole(...)
  ↓ NO
Does it have a unique id or class? → YES → page.locator('#id') / page.locator('.class')
  ↓ NO
Does it have unique text? → YES (but brittle) → getByText
  ↓ NO
CSS/XPath as last resort + // comment explaining why
  ↓
Also: add TODO with ticket key for missing testid

Further Reading

• references/locator-recipes.md — copy-paste solutions for tricky scenarios (iframes, shadow DOM, ARIA dialogs)