Flaky tests, explained
Why a test passes nine times and fails the tenth.
Role locators see the page the way a screen reader does. Elements that look the same can have different roles, and a name can come from text you never see.
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.role attribute replaces the default: <input type="checkbox" role="switch"> is a switch.The browser takes the first of these that exists:
aria-labelledby: the text of the elements it points to, joined in orderaria-label<label>, for form fieldstitle, and placeholder for inputs, as a last resortText 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.
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');page.getByRole('checkbox', { checked: true }); // ticked
page.getByRole('button', { disabled: true }); // can't be used
page.getByRole('checkbox', { includeHidden: true }); // also the hidden onesRole locators skip hidden elements unless you pass includeHidden: true. That is usually what you want: a user can't see or use them either.
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.
Why a test passes nine times and fails the tenth.
A failed run, step by step, from snapshots to network.
Choosing locators that survive a redesign.
| Work | Home | |
|---|---|---|
| Phone | ||
Read the guide: Playwright locators: a practical guide with exercises