Text Content Selectors

What are Text Content Selectors?

Text content selectors target elements based on their visible text content. This is particularly useful for buttons, links, headers, and other elements where the visible text is a reliable identifier.

Using getByText is effective because:

It targets what the user actually sees on the screen
It's resilient to implementation changes (as long as the text remains the same)
It's ideal for buttons, links, and other interactive elements with display text
It captures the user's perspective of the interface

Form with Text Content Elements

This form demonstrates elements that can be targeted by their visible text content.

Complete the form below to see text-based selectors in action.

Personal Information

Email Address

Full Name

Contact Preferences

View our Privacy Policy or Terms of Service

Account Type

Basic Plan

For individual users

Free tier with limited features

Premium Plan

For power users

$9.99/month with full access

Enterprise Plan

For teams and businesses

Custom pricing with dedicated support

Communication Preferences

Marketing Emails

Weekly Digest

Product Updates

Text Content Selectors JSON Configuration

Copy this JSON configuration to test the form with TesterUtilities extension. It uses getByText selectors to target elements by their visible text content.

{
  "url": "(https://pawel-albert.github.io/utilities-for-testing-extension/text-form.html|file:///.*text-form.html)",
  "formData": {
    "registrationForm": {
      "type": "form",
      "timeout": 5000,
      "fields": {
        "email": {
          "selector": "Email Address",
          "queryType": "label",
          "type": "input",
          "data": "test.user@example.com",
          "dataType": "static"
        },
        "fullName": {
          "selector": "Full Name",
          "queryType": "label",
          "type": "input",
          "data": "John Doe",
          "dataType": "static"
        },
        "emailUpdates": {
          "selector": "Email Updates",
          "queryType": "text",
          "type": "click",
          "data": null,
          "dataType": null
        },
        "premiumPlan": {
          "selector": "Premium Plan",
          "queryType": "text",
          "type": "click",
          "data": null,
          "dataType": null
        },
        "weeklyDigestToggle": {
          "selector": "OFF",
          "queryType": "text",
          "queryOptions": {
            "exact": true
          },
          "type": "click",
          "data": null,
          "dataType": null
        }
      },
      "submit": {
        "selector": "Create Account",
        "queryType": "text",
        "type": "click",
        "data": null,
        "dataType": null
      }
    }
  }
}

How Text Content Selectors Work

In the TesterUtilities extension, text content selectors use the getByText function, which finds elements containing the specified text content.

// Example of how getByText works:
function getByText(document, text, options = {}) {
  const { exact = false, selector = '*', index = 0 } = options;
  
  // Find all elements matching the optional selector
  const elements = Array.from(document.querySelectorAll(selector));
  
  // Filter elements by their text content
  const matchingElements = elements.filter(element => {
    // Get visible text content (excluding hidden children)
    const elementText = element.textContent.trim();
    
    // Match based on exact or partial text
    return exact 
      ? elementText === text 
      : elementText.includes(text);
  });
  
  // If index is provided, return the element at that index
  return matchingElements[index] || null;
}

Important Notes About Text Content Selectors

Partial vs. Exact Matching: By default, text matching is partial. Set exact: true for exact matches (useful for short or common text).
Handling Ambiguity: When multiple elements contain the same text, use the index parameter to specify which one to target (0-based).
Ideal Use Cases: Text selectors are best for buttons, links, headings, and other elements with unique visible text.
Limitation: Text selectors may not work well with internationalized applications where text changes based on locale.

When to Use Text Selectors

Text selectors are particularly useful for:

Buttons and links with descriptive text
Menu items and navigation elements
Headers and section titles
Error messages and notifications
Custom UI components without standard HTML semantics