Last updated on July 5th, 2025 at 05:22 am
Playwright supports many element locators, but selecting elements by their visible text is one of the most intuitive and reliable methods. Whether you’re interacting with buttons, links, or labels, using a text selector will help create readable and maintainable test scripts.
In this guide, you’ll learn:
- What is a text selector in Playwright
- How to use getByText, locator, and text= syntax
- Best practices and edge cases
- Examples of different scenarios
If you’re new to Playwright, check out our complete Playwright automation tutorial to get started.
What Is a Text Selector in Playwright?
A text selector in Playwright allows you to locate elements based on the visible text content of the page. This is especially useful when working with dynamic UI where class names or IDs are unpredictable.
Basic syntax to locate an element by text
await page.getByText('Create new account');OR
page.locator('text=Create new account');The playwright will parse the text string and find an element with matching visible text.
Three ways to select an element by Text in Playwright
In Playwright, you can select elements by visible text using three different methods. This guide will walk you through each approach step by step.
1. Text Selector: Using page.getByText()
This method is part of the newer testing library-style API. You can use the getByText() method in Playwright to locate an element based on its visible text content on the page. It searches for elements with the exact or similar visible text.
Syntax:
page.getByText('Create new account').click();Features:
- Case-insensitive matching (e.g.,
Loginandloginboth work) - Ignores hidden elements by default
- Returns the first visible match
- Supports RegExp for flexible matching
Example:
const { test, expect } = require('@playwright/test');
test('Example: Select element by visible text using getByText() method.', async ({ page }) => {
await page.goto('https://www.facebook.com/');
//Select element by visible text.
const crtAccBtn = page.getByText('Create new account');
//Click on element
await crtAccBtn.click();
});
When to Use:
- Writing clean and readable tests
- Targeting common UI elements like buttons or labels
2. Text Selector: Using locator(‘text=…’) (Classic CSS/Selector Style)
This is Playwright’s built-in selector engine for matching text. It enables advanced control and chaining, particularly when combined with other filters.
Syntax:
await page.locator('text=Create new account').click();Features:
- Works well with other CSS locators (e.g., inside div, button)
- Can be combined with .nth(), .first(), .last(), .filter() for refined selection
- Can scope within parent elements
Example:
const { test, expect } = require('@playwright/test');
test('Example: Select element by visible text using locator.', async ({ page }) => {
await page.goto('https://www.facebook.com/');
//Select element by visible text using locator
const crtAccBtn = page.locator('text=Create new account');
//Click on element
await crtAccBtn.click();
});
When to Use:
- Combining text selectors with complex DOM traversal
- Interacting with nested elements or needing to scope the selection
- Using chaining for precise control
3. Using Regular Expressions for Partial Text Match
If the text you’re trying to match is partial, case-variant, or dynamic, you can use a RegExp directly in getByText or locator. You need to use the /i flag with the text string as below.
Syntax with getByText():
await page.getByText(/Log/i).click(); // Matches "Login", "Log out", etc.Features:
- Allows fuzzy or partial matches
- Ideal for testing internationalized content or dynamic strings
- Case-insensitive when /i flag is used
Example:
const { test, expect } = require('@playwright/test');
test('Example: Select element by visible text using RegExp.', async ({ page }) => {
await page.goto('https://www.facebook.com/');
//Select element by visible text using RegExp
const crtAccBtn = page.getByText(/Create new/i);
//Click on element
await crtAccBtn.click();
await page.waitForTimeout(10000);
});
When to Use:
- Dealing with partial, variable, or translated text
- Text is generated dynamically at runtime
- Exact match is too rigid
Each of these methods has its strengths. Use getByText() for clean readability, locator(‘text=…’) for more chaining and CSS-style control, and RegExp when matching isn’t straightforward.
Common Pitfalls & How to Avoid Them
1. Text is inside a hidden element
Text selectors skip hidden elements. Use .first() or better CSS scoping to refine the selection.
2. Multiple elements with the same text
Use nth(index), first(), or use the hasText filter.
3. Text dynamically changes
Prefer regex or use data attributes when text is unstable.
Best Practices for Using Text Selectors
- Prefer text selectors for buttons, links, labels
- Use regex or hasText for partial or dynamic text
- Combine with getByRole, getByLabel, or getByTestId when available
- Don’t rely on text for elements with changing content (e.g., timers)
Frequently Asked Questions (FAQs)
1. How do I find an element by text in Playwright?
You can use page.getByText(‘text’) or locator(‘text=…’) to find elements based on visible content.
2. What’s the difference between getByText and locator(‘text=…’)?
getByText is part of the testing-library API with enhanced readability, while locator(‘text=…’) offers more low-level control.
3. Does the Playwright’s text selector work with hidden elements?
No, by default, it skips hidden elements unless explicitly scoped.
Final Words
Using the text selector in Playwright simplifies test writing and improves readability. With methods like getByText() and text= locators, you can create robust and maintainable test scripts that mirror real user actions.
Hi, I’m Aravind, a seasoned Automation Test Engineer with 17+ years of industry experience. I specialize in tools like Selenium, JMeter, Appium, and Excel automation. Through this blog, I share practical tutorials, tips, and real-world insights to help testers and developers sharpen their automation skills.
