Playwright Get By Role

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

1. Implicit vs Explicit Roles
2. Locate by Implicit Roles
3. Locate By Explicit Roles
4. When to use Role Locator
5. 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.