# 🎯 Mastering getByRole in Playwright: Write Reliable and Accessible Tests
When writing UI tests, choosing the right selector can make or break your test suite. Fragile selectors like class names or IDs often lead to flaky tests that break with minor UI changes. That’s where `getByRole` comes in—a powerful, accessibility-first query method that helps you write **robust, readable, and maintainable tests**.
In this post, we’ll explore how `getByRole` works, why it’s better than traditional selectors, and how to use it effectively in your Playwright tests.
---
## 🔍 What is `getByRole`?
`getByRole` is a query method from the Testing Library family, integrated into Playwright via `@playwright/experimental-ct-*` packages. It allows you to select elements based on their ARIA roles, which describe the purpose of an element in the UI.
## âś… Why Use `getByRole`?
Here are some compelling reasons to use `getByRole`:
* **Accessibility-first**: Encourages semantic HTML and accessible components.
* **Resilient to UI changes**: Doesn’t break when class names or IDs change.
* **Readable**: Clearly communicates the intent of the test.
* **Built-in filtering**: Supports options like `name`, `level`, and `hidden`.
## 🧪 Basic Usage
Here’s a simple example using Playwright Component Testing with React:
```typescript
import { test, expect } from '@playwright/experimental-ct-react';
import LoginForm from './LoginForm';
test('should submit login form', async ({ mount }) => {
const component = await mount();
const usernameInput = component.getByRole('textbox', { name: 'Username' });
const passwordInput = component.getByRole('textbox', { name: 'Password' });
const submitButton = component.getByRole('button', { name: 'Login' });
await usernameInput.fill('gunasekaran');
await passwordInput.fill('securepassword');
await submitButton.click();
await expect(component).toContainText('Welcome, gunasekaran!'
```
## Did you know the `name` parameter can come from **multiple sources**, not just visible text?. here are the list of scenarios that name can handle.
1. **Visible text**
```html
await page.getByRole('button', { name: 'Submit' }).click();
```
2. `aria-label`
```html
await page.getByRole('button', { name: 'Submit Form' }).click();
```
3. `aria-labelledby`
```html
await page.getByRole('textbox', { name: 'Username' }).fill('admin');
```
4. **Alt text for images**
```html
await page.getByRole('img', { name: 'Company Logo' }).click();
```
| **DOM Example** | **Accessible Name** | **Playwright Locator** | **Note** |
| --- | --- | --- | --- |
| `` | `"Submit"` | `page.getByRole('button', { name: 'Submit' })` | Simple button with visible text. |
| `` | `"Submit form"` | `page.getByRole('button', { name: 'Submit form' })` | button tag contains nested label tag. both can be concatenated in the name and used for identifying |
| `` | `"Username"` | `page.getByRole('textbox', { name: 'Username' })` | Label references input using `aria-labelledby`. |
| `` | `"Save Changes"` | `page.getByRole('button', { name: 'Save Changes' })` | `aria-label` provides accessible name, visible text not required. |
| `` | `"Company Logo"` | `page.getByRole('img', { name: 'Company Logo' })` | `alt` attribute used for accessible name. |
| `
Accept Terms
` | `"Accept Terms"` | `page.getByRole('checkbox', { name: 'Accept Terms', checked: true })` | Checkbox with text inside div, state can be filtered. |
| `
` | `"Welcome User"`
`"greeting"` —> wrong | `page.getByRole('heading', { name: 'Welcome User' })` | Dont get confused with name attribute
`name` **attribute ≠accessible name** in Playwright. |
There are html elements that has implicit role so it won’t have the role attribute manually but still can be identified using role
### âś… Implicit ARIA Roles in Native HTML Elements
| **Implicit ARIA Role** | **HTML Elements** |
| --- | --- |
| `link` | ``, `` |
| `button` | `
await page.getByRole('img', { name: 'Company Logo' }).click();
```
| **DOM Example** | **Accessible Name** | **Playwright Locator** | **Note** |
| --- | --- | --- | --- |
| `` | `"Submit"` | `page.getByRole('button', { name: 'Submit' })` | Simple button with visible text. |
| `` | `"Submit form"` | `page.getByRole('button', { name: 'Submit form' })` | button tag contains nested label tag. both can be concatenated in the name and used for identifying |
| `` | `"Username"` | `page.getByRole('textbox', { name: 'Username' })` | Label references input using `aria-labelledby`. |
| `` | `"Save Changes"` | `page.getByRole('button', { name: 'Save Changes' })` | `aria-label` provides accessible name, visible text not required. |
| `