Playwright Locators

In this guide, we’ll explore all possible ways to locate elements in Playwright, including the fastest strategies to get elements, and how to work with elements inside an iframe.

1. Fastest Element Locator Methods

For speed and simplicity, using direct locators such as CSS selectors or ID selectors is the fastest way to get elements.

// Fastest way: CSS selectors
const homeLink = page.locator('nav a.home');
await homeLink.click();

// Fastest way: ID selectors
const aboutLink = page.locator('#about-link');
await aboutLink.click();

If your element has an ID, always prefer the #id selector as it's the most optimized. For other elements, CSS selectors like class names .class-name or attributes are also highly efficient.

2. Text Locators

You can locate elements based on visible text. These are slower compared to direct selectors but useful when IDs or classes are unavailable.

// Select element by exact text
const servicesLink = page.locator('text=Services');
await expect(servicesLink).toBeVisible();

// Select element by partial text
const contactLink = page.locator('text=Contact');
await expect(contactLink).toHaveAttribute('href', '/contact');

3. Attribute Locators

Attribute locators are another efficient way to get elements when you have specific data attributes, like data-*, name, type, or others.

// Locate by custom data attribute
const contactButton = page.locator('[data-testid="contact-button"]');
await contactButton.click();

// Locate by type attribute
const menuButton = page.locator('button[data-role="menu-button"]');
await menuButton.click();

4. XPath Locators

Use XPath when you need to find elements that cannot be easily accessed through CSS or text selectors. It is less performant but very flexible.

// Select by XPath
const aboutLink = page.locator('//nav/a[text()="About"]');
await aboutLink.click();

// XPath by attribute
const servicesLink = page.locator('//a[@href="/services"]');
await servicesLink.click();

5. ARIA Role Locators (Accessibility)

Playwright allows locating elements by their ARIA roles, which helps in working with accessibility-related locators.

// Locate button by ARIA role and name
const menuButton = page.locator('role=button[name="Menu"]');
await menuButton.click();

6. Nth-child Locators

To target specific elements within a repeated set, use nth() to access the right instance of an element.

// Select the second navigation item
const secondNavItem = page.locator('nav a').nth(1);
await expect(secondNavItem).toHaveText('About');

7. Working with Iframes

Playwright allows you to interact with elements inside an iframe using the frameLocator() method.

// Access iframe by its selector
const iframe = page.frameLocator('iframe#my-frame');

// Now interact with elements inside the iframe
const iframeButton = iframe.locator('button#inside-frame');
await iframeButton.click();

8. Get Elements by Text (Contains & Exact Match)

Playwright provides methods to get elements by text with both exact and partial matching.

// Exact match for element text
const homeLink = page.getByText('Home', { exact: true });
await homeLink.click();

// Partial match for element text
const aboutLink = page.getByText('Abou');
await aboutLink.click();

9. Get Elements by Label

Use getByLabel to locate elements associated with a label. This is useful for input fields, like a search bar.

// Locate search input by its associated label
const searchInput = page.getByLabel('Search');
await searchInput.fill('Playwright');

10. Get Elements by Placeholder

The getByPlaceholder method lets you select input elements by their placeholder text.

// Locate input by its placeholder
const emailInput = page.getByPlaceholder('Email Address');
await emailInput.fill('example@example.com');

11. Get Elements by Role

Locating elements by ARIA roles helps in making your tests more accessible. Use getByRole for this.

// Locate element by role
const submitButton = page.getByRole('button', { name: 'Submit' });
await submitButton.click();

12. Get Elements by Test ID

Using data-testid attributes can be a robust way to select elements in tests.

// Locate element by data-testid
const saveButton = page.locator('[data-testid="save-button"]');
await saveButton.click();

13. Chaining Locators

You can chain locators to refine your selection process, targeting nested elements directly.

// Locate nested element by chaining
const nestedElement = page.locator('div.container').locator('span.highlight');
await expect(nestedElement).toBeVisible();

14. Using Locators with Filters

Filters can help to narrow down the results when selecting elements, making your tests more precise.

// Filter elements by attributes
const filteredLinks = page.locator('a').filter({ hasText: 'Home' });
await expect(filteredLinks).toHaveCount(1);