Locators over brittle selectors

Locators are the central piece of Playwright's auto-waiting and retry-ability: a locator describes how to find elements on the page at any moment, and every action performs a fresh DOM lookup, so a re-render between a hover and a click still acts on the current element. Prioritize the built-in user-facing locators: page.getByRole() locates by explicit and implicit accessibility attributes and reflects how users and assistive technology perceive the page — pass the accessible name so the locator pinpoints the exact element, as in page.getByRole('button', { name: 'Sign in' }) — alongside page.getByText(), page.getByLabel(), page.getByPlaceholder(), page.getByAltText(), page.getByTitle(), and page.getByTestId() for the data-testid attribute, which can be configured. All locator-creating methods also exist on the Locator and FrameLocator classes, so locators chain to narrow matches, including inside frames. Use the code generator to produce a locator, then edit it as needed. Scope: Playwright. Reviewed October 4, 2026.