How to Use Text Selector in Playwright – 2025 Guide

How to Use Text Selector in Playwright

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., Login and login both 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();
});
text selector by visible text using getByText() method in playwright

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();
});
Select element by visible text using locator in playwright.

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);
});
Select element by visible text using RegExp in playwright.

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.

Leave a Reply

Your email address will not be published. Required fields are marked *