Playwright Selector Helper

page.locator() accepts any CSS or XPath selector and is the most flexible — but also the most brittle. getByRole() targets elements by their ARIA role and accessible name, which is how screen readers and keyboard users navigate. Playwright's documentation recommends preferring getByRole, getByLabel, and getByText because they are resilient to structural changes in the HTML and simultaneously verify your app's accessibility.

Use getByRole() whenever the element has a meaningful ARIA role and accessible name — buttons, links, form controls, headings. Fall back to getByTestId() only for elements that have no stable semantic meaning from a user perspective (e.g., a container div or a custom widget with no accessible label). Add data-testid attributes deliberately rather than sprinkling them across every element.

By default Playwright looks for data-testid. You can change this in playwright.config.ts: set use: { testIdAttribute: 'data-cy' } to match Cypress conventions, or any other attribute your codebase uses. getByTestId() will then match that attribute instead. This is useful when migrating test suites from other frameworks.

Without exact: true, getByText('Submit') will match any element whose text content includes the word 'Submit' — such as 'Submit your form' or 'Please Submit'. With exact: true, it performs a case-sensitive, full-string match. This is useful when multiple elements on the page contain similar text and you need to target one specific element precisely.

Chain locators with .locator() to scope queries: page.locator('#sidebar').getByRole('link') finds links only inside #sidebar. For iframes, use page.frameLocator('iframe[name=checkout]').getByRole('button', { name: 'Pay' }). This avoids false matches from elsewhere in the page and is much more maintainable than using complex CSS descendant selectors.

Prefer user-visible locators (role, label, placeholder, text) over implementation details (CSS classes, XPath). Avoid nth-child or index-based selectors which break on DOM reorder. Use data-testid for custom components that lack semantic roles. Keep selectors in Page Object Model classes so they are centrally maintained. Enable Playwright's built-in retry and waitFor to handle async rendering without adding manual timeouts.