The page.getByRole() locator reflects how users and assistive technology perceive the page. Here, Assistive technology includes products, equipment, and systems that enhance learning, working, and daily living for differently-abled persons.
For a website, it is possible using ARIA implicit roles or explicit roles or attributes. Here, ARIA stands for Accessible Rich Internet Applications. These attributes or labels help tools like screen readers understand and describe what element user is interacting with, it explain things to people who can't see the screen. It's like telling someone, "This is a button," or "This is a menu," or "This is a checkbox," so that they know how to use it without seeing it. This makes the web more accessible for everyone.
Table of Contents
- Implicit vs Explicit Roles
- Locate by Implicit Roles
- Locate By Explicit Roles
- When to use Role Locator
- Video Tutorial
Implicit vs Explicit Roles
Playwright getByRole() locator is used to locate elements by explicit and implicit accessibility attributes.
Here, implicit means By default. Many semantic elements in HTML have a role; for example,
- <input type="radio"> has the "radio" role.
- <input type="checkbox"> has the "checkbox" role.
- <button> element has an implicit role of button etc.
On the other hand, Non-semantic elements in HTML do not have a role; For example, <div> and <span>. These elements without added semantics return null. The role attribute can provide semantics to such non-semantic elements.
ARIA roles are added to these HTML elements using role="role type" where role type is the name of a role in the ARIA specification. Example
<div role="button" tabindex="0" aria-roledescription="download button">Download</div>
Locate by Implicit Roles
Let's click on Amazon Hello, sign in Account & Lists link first.
Then fill in Email or mobile phone number textbox and click on Continue button.
test('implicit roles', async ({ page }) => {
await page.goto("https://www.amazon.in/");
// click on link
await page.getByRole("link",{name: "Hello, sign in Account & Lists"}).click();
// fill in username
await page.getByRole("textbox",{name: "Email or mobile phone number"}).fill("goswami.tarun77@gmail.com");
// click on continue button
await page.getByRole("button",{name: "Continue"}).click();
})
Locate by Explicit Roles
Example 1
Now, let's fill in search input text box with value "dell laptop".
<input type="text" aria-label="Search Amazon.in">
test('aria-attribute only', async ({ page }) => {
await page.goto("https://www.amazon.in/");
// fill in search box with value laptop
await page.getByRole("textbox",{name: "Search Amazon.in"}).fill("laptop");
})
We have identified it using aria-label attribute value "Search Amazon.in".
Example 2
Now let's click on hamburger menu
<a href="javascript: void(0)" id="nav-hamburger-menu" role="button" aria-label="Open Menu">All</a>
Here it will fail if you will try to use link as role because explicit role is mentioned here which is button.
test('role and aria-attribute example 1', async ({ page }) => {
await page.goto("https://www.amazon.in/");
// This will fail because role is button
// await page.getByRole("link",{name: "Open Menu"}).click();
// This will pass because role is button
await page.getByRole("button",{name: "Open Menu"}).click();
})
Example 3
Let's try final example with amazon logo on sign in page.
<i class="a-icon a-icon-logo" role="img" aria-label="Amazon"></i>
Here role is img and aria-label value is Amazon
test('role and aria-attribute example 2', async ({ page }) => {
await page.goto("https://www.amazon.in/");
// click on link
await page.getByRole("link",{name: "Hello, sign in Account & Lists"}).click();
// Click on Amazon Logo with role img
await page.getByRole("img",{name: "Amazon"}).click();
})
When to use Role Locator
It's important to note that role locators do not replace accessibility audits and conformance tests but rather give early feedback about whether the webpage follows accessibility guidelines.
The playwright team suggests using role locators as your first choice when locating elements because it is the closest way to how users and assistive technology perceive the page.
- Log in to post comments