This is documentation for the next version of Grafana k6 documentation. For the latest stable release, go to the latest version.

JavaScript API

k6/browser

Frame

getByText(text[, options])

Open source

getByText(text[, options])

Returns a locator for elements containing the specified text. This method finds elements by their visible text content, making it ideal for locating user-facing content like buttons, links, headings, and other text elements.

Parameter	Type	Default	Description
`text`	string \| RegExp	-	Required. The text content to search for. Can be a string for exact match or a RegExp for pattern matching.
`options`	object	`null`
`options.exact`	boolean	`false`	Whether to match the text exactly with case sensitivity. When `true`, performs a case-sensitive match.

Returns

Type	Description
Locator	A locator object that can be used to interact with the elements containing the specified text.

Examples

Find and click elements by their visible text:

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const page = await browser.newPage();

  try {
    await page.goto('https://quickpizza.grafana.com/');

    const frame = page.mainFrame();
    await frame.getByText('Pizza, Please!').click();

    const noThanksBtn = frame.getByText('No thanks');
    await noThanksBtn.click();
  } finally {
    await page.close();
  }
}

Text matching behavior

Whitespace normalization: Text matching automatically normalizes whitespace, meaning:

Multiple spaces become single spaces
Line breaks become spaces
Leading and trailing whitespace is ignored

Consider the following DOM structure:

<div>Hello <span>world</span></div>
<div>Hello</div>

You can locate by text substring, exact string, or a regular expression:

// Matches <span>
page.getByText('world');
// Matches first <div>
page.getByText('Hello world');
// Matches second <div>
page.getByText('Hello', { exact: true });
// Matches both <div>s
page.getByText(/Hello/);
// Matches second <div>
page.getByText(/^hello$/i);

Common use cases

Button interactions: Submit, Cancel, Delete, Edit buttons
Navigation: Menu items, breadcrumbs, pagination links
Content verification: Success messages, error messages, headings
Form interactions: Checkbox labels, radio button options
Status indicators: Active, Inactive, Pending states

Best practices

User-focused testing: Using getByText() ensures your tests interact with content as users see it.
Avoid brittle text: Be cautious with exact text that might change frequently (like dates, counts, or user-generated content).
Use meaningful text: Prefer descriptive button text and labels over generic terms like “Click here” or “Button”.
Handle dynamic content: Use regular expressions for text that contains variable parts (timestamps, user names, counts).
Consider accessibility: Text-based selection encourages better accessibility practices in your application.
Internationalization: For multi-language applications, consider using test IDs or roles instead of text for critical interactions.