Playwright Locators: How to Find Elements Reliably

What is a locator?

Locator stability matters because UI structure changes often. A selector tied to several container classes can break during harmless redesign work. A locator based on a button’s role and accessible name often expresses user intent more directly.

User-facing and explicit locators

Practical login-form example

The labels identify the fields, and the button role plus name identifies the action. The alert assertion checks an observable result and retries until the message appears or the assertion times out. In a real project, arrange an isolated account and avoid relying on shared credentials.

Strictness, chaining, and filtering

Playwright operations that imply one target are strict. If a locator matches two buttons, a click fails instead of choosing silently. Narrow the intent by chaining within a region or filtering a list item by text or another locator.

This locator first identifies product rows, narrows them to the row containing the product name, and then finds the action inside that row. It avoids depending on the row’s numeric position.

Risks of first, last, and nth

first(), last(), and nth() can be appropriate when position is the behavior being tested. They are risky when used only to silence a strictness error because a new element can change the position without changing the test code. Prefer a unique description of intent.

CSS and XPath considerations

CSS and XPath are not always wrong. They may be necessary for legacy markup, canvas-adjacent elements, or an interface with no useful accessibility or test contract. Keep them short, avoid deep structural chains, and ask whether improving the application’s labels would also improve accessibility.

Use web-first assertions

Assertions such as toBeVisible() and toHaveText() retry against the locator. A one-time check such as expect(await locator.isVisible()).toBe(true) does not provide the same retry behavior. Waiting should be tied to the expected UI state, not an arbitrary timeout.

Common mistakes

• Using a deep CSS path that mirrors the current DOM
• Selecting the first match without explaining why position matters
• Using placeholder text when a stable label is available
• Adding a test ID to every element instead of using user-facing semantics
• Checking visibility once instead of using a retrying assertion
• Forcing an action before understanding why actionability checks fail

Locator-selection checklist

1. Start with the way a user or assistive technology identifies the control.
2. Prefer role and accessible name for interactive elements.
3. Use labels for form fields.
4. Use visible text for meaningful content when wording is part of the contract.
5. Use a deliberate test ID when no dependable user-facing locator exists.
6. Use CSS or XPath carefully when the application provides no better contract.
7. Confirm that the locator identifies one intended target and remains readable.