Selectors

Selectors are the foundation of any test automation framework. They help identify elements on a web page so you can interact with them, like clicking buttons, filling forms, or verifying content. In this tutorial, we’ll cover how to use and choose the right selectors in Playwright.

What Are Selectors?

A selector is a string that tells Playwright how to find a specific element on a webpage. For example, you can use a button’s text, ID, or CSS class to identify it.

Types of Selectors in Playwright

Playwright supports multiple types of selectors, making it easy to find elements in different ways.

1. CSS Selectors

CSS selectors are the most common way to locate elements.

Examples:

await page.click('button'); // Finds a <button> tag
await page.click('#login'); // Finds an element with id="login"
await page.click('.submit-btn'); // Finds an element with class="submit-btn"

Advanced CSS Selectors:

await page.click('input[type="text"]'); // Finds an input with type="text"
await page.click('div > button'); // Finds a button directly inside a <div>

2. Text Selectors

Playwright can locate elements based on their visible text.

Examples:

await page.click('text=Sign In'); // Finds an element containing "Sign In"
await page.click('text=Submit'); // Finds an element containing "Submit"

Partial Match:

Use text= to match elements with exact or partial text.

3. Role Selectors

Role selectors are useful for accessibility testing. They match elements based on their ARIA roles.

Examples:

await page.click('role=button[name="Submit"]'); // Finds a button with accessible name "Submit"
await page.click('role=checkbox'); // Finds a checkbox element

4. XPath Selectors

XPath selectors use an XML-style syntax to locate elements.

Examples:

await page.click('//button[text()="Submit"]'); // Finds a button with text "Submit"
await page.click('//div[@id="main"]'); // Finds a <div> with id="main"

5. Test IDs

Using custom attributes like data-testid is a reliable way to locate elements, especially when the UI changes frequently.

Examples:

await page.click('[data-testid="submit-button"]'); // Finds an element with data-testid="submit-button"

6. Chain Selectors

Playwright allows you to chain multiple selectors to narrow down elements.

Example:

await page.click('div#container >> text=Submit'); // Finds a "Submit" text inside a div with id="container"

7. Custom Selectors

Playwright supports custom selectors for advanced scenarios. You can write JavaScript functions to find elements.

Example:

const elementHandle = await page.$('css=div'); // Custom CSS selector

How to Use Selectors in Playwright

1. Click an Element

await page.click('button#login');

2. Type into an Input Field

await page.fill('input#username', 'myUsername');

3. Verify Element Text

const text = await page.textContent('h1');
console.log(text); // Logs the text inside the <h1> tag

4. Wait for an Element

Sometimes elements take time to load. Use Playwright’s built-in waiting:

await page.waitForSelector('button#submit');

Best Practices for Using Selectors

1. Prefer Stable Selectors:

Use attributes like data-testid or ARIA roles, as they are less likely to change.

2. Avoid Fragile Selectors:

Avoid relying on selectors that are prone to changes, like nth-child or deeply nested CSS paths.

3. Test with Multiple Selectors:

If one selector fails, Playwright allows fallback selectors:

await page.click('button#primary, text=Submit');

4. Use Debugging Tools:

• Use the browser's developer tools to inspect and identify elements.
• Playwright's codegen feature can record selectors automatically:

Common Debugging Tips

1. Highlight the Element:

Use the highlight option during debugging:

await page.click('text=Submit', { highlight: true });

2. Check Selector Validity:

Verify if a selector works:

const isVisible = await page.isVisible('button#submit');
console.log(isVisible); // true or false

3. Playwright Inspector:

Launch the inspector to debug interactively: