Roles and accessible names

Every element has a role

getByRole() doesn't read tags. It reads the role the browser gives each element, mostly from its tag and attributes:

  • <a href> is a link. Without href it has no role, however it looks.
  • <input type="number"> is a spinbutton, type="search" a searchbox, <select> a combobox.
  • <section> is a region only when it has a name. <nav> is navigation.
  • A role attribute replaces the default: <input type="checkbox" role="switch"> is a switch.

Where the name comes from

The browser takes the first of these that exists:

  1. aria-labelledby: the text of the elements it points to, joined in order
  2. aria-label
  3. a <label>, for form fields
  4. the text inside, for buttons, links and headings
  5. title, and placeholder for inputs, as a last resort

Text hidden with CSS but kept for screen readers is part of the name. Text inside aria-hidden="true" is not.

// <button aria-label="Close dialog">×</button>
await page.getByRole('button', { name: 'Close dialog' }).click();

// getByLabel() reads <label>, aria-label and aria-labelledby
await page.getByLabel('Close dialog').click();

With aria-labelledby, the two locators differ. getByRole() matches the whole joined name. getByLabel() matches the text of each labelling element on its own, so it finds a field by any one of its labels, but never by the full name.

Assert the role and the name

When you found an element some other way, check what assistive technology will announce:

const toggle = page.getByLabel('Dark mode');

await expect(toggle).toHaveRole('switch');
await expect(toggle).toHaveAccessibleName('Dark mode');

Filter by state

page.getByRole('checkbox', { checked: true });     // ticked
page.getByRole('button', { disabled: true });      // can't be used
page.getByRole('checkbox', { includeHidden: true }); // also the hidden ones

Role locators skip hidden elements unless you pass includeHidden: true. That is usually what you want: a user can't see or use them either.

See the tree yourself

In Chrome DevTools, the Accessibility pane of the Elements panel shows any element's role and name. In a test, log await locator.ariaSnapshot(). The "Pick locator" button in UI mode and codegen suggests a role locator for anything you click.

1. Not everything is what it looks like

Desk lamp, $24

Order: 1 × Desk lamp · Gift wrap: off

2. Names you can't see

Your trial ends in 3 days.

Flaky tests, explained

Why a test passes nine times and fails the tenth.

Reading the Trace Viewer

A failed run, step by step, from snapshots to network.

Locators that last

Choosing locators that survive a redesign.

Contact details

WorkHome
Phone
Email

Discount

3. Notifications

Advanced
4 notification types on