Find elements by role

A test must find the element first

Before a test can click a button, it must find the button. A locator describes how to find an element. You make a locator on the page, and then you act on it or check it.

The best locator is getByRole. It finds an element by its role. The browser gives a role to every element. A <button> has the role button. An <a href> has the role link. An <h1> has the role heading. A text box has the role textbox, and a check box has the role checkbox.

page.getByRole('button', { name: 'Add' })

The second argument is a list of options. The most useful option is name. It is the accessible name of the element: for a button or a link, the text on it. For a form field, the text of its label. The name option finds the text anywhere inside the accessible name, and it does not care about capital letters. Add exact: true when the name must match in full.

Why roles are the best choice

People who use a screen reader find elements by role and name. A test that finds elements the same way checks that the page works for them. It also keeps working when the developers change the CSS classes or the layout, because those are not part of the role or the name.

Element	Role	Example
<button>	button	getByRole('button', { name: 'Add' })
<a href>	link	getByRole('link', { name: 'Completed' })
<input type="text">	textbox	getByRole('textbox', { name: 'New todo' })
<input type="checkbox">	checkbox	getByRole('checkbox', { name: 'Buy milk' })
<h1> to <h6>	heading	getByRole('heading', { level: 1 })

Act on the element

A locator does nothing until you call a method on it.

• fill('text') clears a text box and types the text.
• click() clicks the element.
• check() ticks a checkbox. It does nothing when the box is ticked already.

You do not have to wait for the page to load before you act. A locator keeps looking for the element, and an action waits until the element is ready. Lesson 7 explains this.

Your turn

Write three tests for the todo app. Each test opens the app with await page.goto('/').