FrameLocator on Grafana Labs

frameLocator(selector)

Mon, 21 Sep 2026 15:16:28 +0000

frameLocator(selector)

Returns a FrameLocator for a nested iframe that matches the given selector within this frame. Use this to chain frame locators for nested iframes.

Parameter	Type	Description
selector	string	A selector that resolves to an iframe element (for example `iframe#inner` or `iframe[name="nested"]`).

Returns

Type	Description
FrameLocator	A `FrameLocator` for the matched nested iframe.

Example

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.setContent(`
      <iframe id="outer" srcdoc="<iframe id='inner' srcdoc='<button>Submit</button>'></iframe>"></iframe>
    `);

    // Nested iframes: outer frame, then inner frame, then element
    const button = page.frameLocator('#outer').frameLocator('#inner').locator('button');
    await button.click();
  } finally {
    await page.close();
  }
}

getByAltText(altText[, options])

Mon, 21 Sep 2026 15:16:28 +0000

getByAltText(altText[, options])

Returns a locator for elements with the specified alt text. This method is useful for locating images and other elements that have an alt attribute, making your tests more accessible and user-focused.

Parameter	Type	Default	Description
`altText`	string \| RegExp	-	Required. The alt text 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 alt 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 elements matching the specified alt text.

Examples

Basic alt text matching

Find and click an image by its alt text:

import { browser } from 'k6/browser';

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

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

  try {
    await page.setContent(`
      <iframe id="my_frame" src="https://quickpizza.grafana.com" width="50%" height="50%"></iframe>
    `);

    const logo = page.locator('#my_frame').contentFrame().getByAltText('LOGO');
    await logo.waitFor();

    await logo.click();
    await page.waitForLoadState();
  } finally {
    await page.close();
  }
}

Exact alt text matching

Use exact matching for precise alt text:

import { browser } from 'k6/browser';

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

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

  try {
    await page.setContent(`
      <iframe id="my_frame" src="https://quickpizza.grafana.com" width="50%" height="50%"></iframe>
    `);

    const logo = page.locator('#my_frame').contentFrame().getByAltText('logo', { exact: true });
    await logo.waitFor();

    await logo.click();
    await page.waitForLoadState();
  } finally {
    await page.close();
  }
}

Using regular expressions

Find images using pattern matching:

import { browser } from 'k6/browser';

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

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

  try {
    await page.setContent(`
      <iframe id="my_frame" src="https://quickpizza.grafana.com" width="50%" height="50%"></iframe>
    `);

    const logo = page.locator('#my_frame').contentFrame().getByAltText(/logo/s);
    await logo.waitFor();

    await logo.click();
    await page.waitForLoadState();
  } finally {
    await page.close();
  }
}

Common use cases

Image testing:
- Testing image alt text for accessibility compliance
- Interacting with clickable images/banners
Accessibility testing:
- Ensuring all images have meaningful alt text
- Testing screen reader compatibility
- Validating WCAG compliance
UI interaction:
- Clicking on logo images to navigate home
- Selecting images in galleries or carousels
- Interacting with image-based buttons

Best practices

Use descriptive alt text: When creating tests, ensure your application uses meaningful alt text that describes the image content or function.
Prefer exact matches: Use exact: true when you need precise matching to avoid false positives.
Accessibility-first: Using getByAltText() encourages better accessibility practices by ensuring images have proper alt attributes.
Regular expressions for patterns: Use RegExp for flexible matching when dealing with dynamic or numbered content.
Combine with assertions: Always verify that the located elements behave as expected using assertions.

frameLocator.getByRole() - Locate by ARIA role
frameLocator.getByLabel() - Locate by form labels
frameLocator.getByPlaceholder() - Locate by placeholder text
frameLocator.getByTestId() - Locate by test ID
frameLocator.getByTitle() - Locate by title attribute
frameLocator.getByText() - Locate by visible text

getByLabel(text[, options])

Mon, 21 Sep 2026 15:16:28 +0000

getByLabel(text[, options])

Returns a locator for form controls associated with the specified label text. This method is ideal for interacting with form elements in an accessible and user-focused way, as it mirrors how users typically identify form fields.

Parameter	Type	Default	Description
`text`	string \| RegExp	-	Required. The label text 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 label 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 form control associated with the specified label.

Examples

Basic form interaction

Fill form fields using their labels:

import { browser } from 'k6/browser';

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

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

  try {
    const iframeHTML = `
      <label for="username">Username (hint: default)</label>
      <input type="text" id="username" name="username">
      <label for="password">Password (hint: 12345678)</label>
      <input type="password" id="password" name="password">
    `;

    await page.setContent(`
      <iframe id="my_frame" src="data:text/html,${encodeURIComponent(iframeHTML)}"></iframe>
    `);

    const frameLocator = page.locator("#my_frame").contentFrame();
    const username = frameLocator.getByLabel('Username (hint: default)', { exact: true });
    const password = frameLocator.getByLabel(/^Password.*$/);

    await username.fill('default');
    await password.fill('12345678');
  } finally {
    await page.close();
  }
}

Working with different input types

Handle various form control types in various label association patterns:

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 {
    const iframeHTML = `
      <label for="username">Username (hint: default)</label>
      <input type="text" id="username" name="username">
      <span id="password-label">Password (hint: 12345678)</span>
      <input type="password" aria-labelledby="password-label">
      <label for="subscribe">Subscribe to newsletter</label>
      <input type="checkbox" id="subscribe" name="subscribe">
      <label for="email">Email</label>
      <input type="radio" id="email" value="email">
      <label for="sms">Text message</label>
      <input type="radio" id="sms" value="sms">
      <label for="theme">Theme</label>
      <select id="theme" name="theme">
        <option value="light">Light</option>
        <option value="dark">Dark</option>
        <option value="system">System</option>
      </select>
      <textarea aria-label="Comments"></textarea>
    `;

    await page.setContent(`
      <iframe id="my_frame" src="data:text/html,${encodeURIComponent(iframeHTML)}"></iframe>
    `);

    const frameLocator = page.locator("#my_frame").contentFrame();

    // Inputs
    await frameLocator.getByLabel('Username (hint: default)', { exact: true }).fill('default');
    await frameLocator.getByLabel(/^Password.*$/).fill('12345678');

    // Checkbox
    await frameLocator.getByLabel('Subscribe to newsletter').check();

    // Radio button
    await frameLocator.getByLabel('Email', { exact: true }).check();

    // Select dropdown
    await frameLocator.getByLabel('Theme').selectOption('light');

    // Textarea
    await frameLocator.getByLabel('Comments').fill('This is a test comment');
  } finally {
    await page.close();
  }
}

Label association patterns

The getByLabel() method works with several HTML patterns for associating labels with form controls:

Explicit association with for attribute:

<label for="username">Username</label> <input type="text" id="username" name="username" />

ARIA labeling:

<span id="username-label">Username</span> <input type="text" aria-labelledby="username-label" />

ARIA label attribute:

<input type="text" aria-label="Username" />

Common use cases

Form testing: Login forms, registration forms, contact forms
E-commerce: Checkout forms, shipping information, payment details
Settings pages: User preferences, account settings, configuration forms
Accessibility testing: Ensuring proper label association and screen reader compatibility

Best practices

Accessibility-first approach: Using getByLabel() ensures your tests work the same way users with assistive technology interact with forms.
Meaningful labels: Encourage developers to use descriptive, unique label text that clearly identifies the form control’s purpose.
Required field indicators: When testing required fields, include any visual indicators (like asterisks) in your label text matching.
Form validation testing: Use labels to test form validation scenarios, as they provide a stable way to identify fields regardless of styling changes.

frameLocator.getByRole() - Locate by ARIA role
frameLocator.getByAltText() - Locate by alt text
frameLocator.getByPlaceholder() - Locate by placeholder text
frameLocator.getByTestId() - Locate by test ID
frameLocator.getByTitle() - Locate by title attribute
frameLocator.getByText() - Locate by text content

getByPlaceholder(placeholder[, options])

Mon, 21 Sep 2026 15:16:28 +0000

getByPlaceholder(placeholder[, options])

Returns a locator for input elements with the specified placeholder attribute. This method is useful for locating form fields that use placeholder attribute to provide hints or examples to users about the expected input format.

Parameter	Type	Default	Description
`placeholder`	string \| RegExp	-	Required. The placeholder text 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 placeholder 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 input elements matching the specified placeholder text.

Example

Find and fill inputs by their placeholder 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 {
    const iframeHTML = `
      <input type="text" placeholder="First name">
      <input type="text" placeholder="Last name">
      <input type="text" placeholder="dd/mm/yyyy">
      <input type="text" placeholder="your.email@example.com">
      <input type="text" placeholder="+1 (555) 123-4567">
    `;

    await page.setContent(`
      <iframe id="my_frame" src="data:text/html,${encodeURIComponent(iframeHTML)}"></iframe>
    `);

    const frameLocator = page.locator("#my_frame").contentFrame();
    await frameLocator.getByPlaceholder('First name').fill('First');
    await frameLocator.getByPlaceholder('Last name').fill('Last');
    await frameLocator.getByPlaceholder('dd/mm/yyyy').fill('01/01/1990');

    await frameLocator.getByPlaceholder('your.email@example.com').fill('first.last@example.com');
    await frameLocator.getByPlaceholder('+1 (555) 123-4567').fill('+1 (555) 987-6543');
  } finally {
    await page.close();
  }
}

Common use cases

Form field identification:
- Login and registration forms without explicit labels
- Quick search boxes
- Filter and input controls
- Comment and feedback forms
E-commerce:
- Product search bars
- Quantity input fields
- Promo code entry
- Address and payment information
Interactive applications:
- Chat input fields
- Command input interfaces
- Settings and configuration forms
- Data entry applications

Best practices

Complement, don’t replace labels: Placeholder text should supplement, not replace proper form labels for accessibility.
Use descriptive placeholders: Ensure placeholder text clearly indicates the expected input format or content.
Consider internationalization: When testing multi-language applications, be aware that placeholder text may change.
Accessibility considerations: Remember that placeholder text alone may not be sufficient for users with disabilities.

frameLocator.getByRole() - Locate by ARIA role
frameLocator.getByAltText() - Locate by alt text
frameLocator.getByLabel() - Locate by form labels (preferred for accessibility)
frameLocator.getByTestId() - Locate by test ID
frameLocator.getByTitle() - Locate by title attribute
frameLocator.getByText() - Locate by visible text

getByRole(role[, options])

Mon, 21 Sep 2026 15:16:28 +0000

getByRole(role[, options])

Returns a locator for elements with the specified ARIA role. This is the preferred way to locate elements as it most closely resembles how users and assistive technology perceive the page.

Parameter	Type	Default	Description
`role`	string	-	Required. The ARIA role to search for. For example, `'button'`, `'link'`, `'heading'`, or `'textbox'`.
options	object	`null`
`options.checked`	boolean	`null`	Filter elements by their checked state. Only applicable for roles like `checkbox`, `radio`, `menuitemcheckbox`.
`options.disabled`	boolean	`null`	Filter elements by their disabled state.
`options.exact`	boolean	`false`	Whether to match the accessible name exactly with case sensitivity. When `true`, performs a case-sensitive match.
`options.expanded`	boolean	`null`	Filter elements by their expanded state. Only applicable for roles that support the `aria-expanded` attribute.
`options.includeHidden`	boolean	`false`	Whether to include elements that are normally excluded from the accessibility tree in the search.
`options.level`	number	`null`	Filter headings by their level 1 to 6. Only applicable for `heading` role.
`options.name`	string\|RegExp	`null`	Filter elements by their accessible name. The accessible name is typically the text content, label text, or aria-label attribute.
`options.pressed`	boolean	`null`	Filter elements by their pressed state. Only applicable for roles like `button` with toggle behavior.
`options.selected`	boolean	`null`	Filter elements by their selected state. Only applicable for roles like `option`, `tab`.

Returns

Type	Description
Locator	A locator object that can be used to interact with the elements matching the specified role and options.

Examples

Basic role selection

Find and click a button by its role:

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.setContent(`
      <iframe id="my_frame" src="https://quickpizza.grafana.com" width="50%" height="50%"></iframe>
    `);

    const frameLocator = page.locator('#my_frame').contentFrame();
    await frameLocator.getByRole('button', { name: 'Pizza, Please!' }).click();
  } finally {
    page.close();
  }
}

Complete ARIA roles reference

The following roles are supported and can be used with getByRole(), organized by category:

Widgets & Inputs

button - Buttons and clickable elements
checkbox - Checkable boxes that can be on/off
combobox - Editable drop-down menu combining input and list box
listbox - Container for selectable list options
menu - Menu of actions or navigation
menubar - Container for top-level menus
menuitem - Option within a menu
menuitemcheckbox - Checkable menu item
menuitemradio - Mutually exclusive menu item
meter - Scalar measurement within a known range
option - Selectable option in a list box or combo box
progressbar - Progress indicator of an operation
radio - Single-select option in a group
radiogroup - Grouping of related radio buttons
scrollbar - Control for scrolling content
searchbox - Text field for search input
separator - Divider that separates content or controls
slider - Adjustable value control within a range
spinbutton - Numeric input with increment/decrement controls
status - Advisory status information (non-alert)
switch - On/off toggle control
tab - A tab in a tabbed interface
tablist - Container for a set of tabs
tabpanel - Content panel associated with a tab
textbox - Input field for free-form text
timer - Running time display that updates
toolbar - Group of interactive controls
tooltip - Contextual help popup
tree - Hierarchical list of items
treeitem - Item in a tree

Tables & Grids

table - Tabular data with rows and columns.
rowgroup - Section that groups rows. For example, thead, tbody, tfoot.
row - A row of cells within a table or grid.
rowheader - Header cell for a row.
columnheader - Header cell for a column.
cell - Data cell in a table.
grid - Interactive, tabular widget, such as a spreadsheet.
gridcell - Cell within a grid.
treegrid - Tree-structured grid with expandable rows.

Document Structure & Semantics

article - Self-contained composition (article)
blockquote - Quotation from another source
caption - Caption for a figure, table, or media
code - Fragment of computer code
definition - Definition of a term
deletion - Content removed from a document
directory - List of references
document - Standalone document content
emphasis - Content with emphatic stress
feed - Stream of articles or entries
figure - Figure with optional caption
generic - Generic container with no specific semantics
img - Image treated as a single graphic
insertion - Content added to a document
link - Hyperlink to another location
list - List of items
listitem - A single item within a list
mark - Highlighted or marked content
marquee - Scrolling region of text
math - Mathematical expression
note - An aside or annotation
none - No semantic role; remove semantics
paragraph - Paragraph of text
presentation - Presentational only; ignore semantics
strong - Content of strong importance
subscript - Subscripted text
superscript - Superscripted text
term - A term being defined
time - A time or date

Landmarks & Regions

banner - Site header landmark
complementary - Complementary content (sidebar)
contentinfo - Page footer information
form - Region containing a form
main - Main content landmark
navigation - Navigation region of links
region - Generic region of the page
search - Search region
application - Application container widget

Usage Examples by Category

Form Testing:

// Text inputs
await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
await page.getByRole('searchbox', { name: 'Search products' }).fill('laptop');

// Selections
await page.getByRole('checkbox', { name: 'Agree to terms' }).check();
await page.getByRole('radio', { name: 'Standard shipping' }).check();
await page.getByRole('combobox', { name: 'Country' }).selectOption('US');

// Interactive controls
await page.getByRole('slider', { name: 'Volume' }).fill('75');
await page.getByRole('switch', { name: 'Enable notifications' }).click();

Navigation Testing:

// Tabs
await page.getByRole('tab', { name: 'Overview' }).click();
await expect(page.getByRole('tabpanel', { name: 'Overview' })).toBeVisible();

Content Verification:

// Structure
await expect(page.getByRole('article')).toHaveCount(5);
await expect(page.getByRole('heading', { level: 1 })).toHaveText('Welcome');

// Status and feedback
await expect(page.getByRole('alert')).toHaveText('Form submitted successfully');
await expect(page.getByRole('status')).toHaveText('3 items selected');

Best practices

Prefer role-based selection: getByRole() is the preferred method for locating elements as it closely mirrors how users and assistive technology interact with your page.
Use accessible names: Always try to use the name option to make your tests more specific and reliable.
Consider accessibility: Using getByRole() encourages better accessibility practices in your application by ensuring elements have proper ARIA roles.

frameLocator.getByAltText() - Locate by alt text
frameLocator.getByLabel() - Locate by form labels
frameLocator.getByPlaceholder() - Locate by placeholder text
frameLocator.getByTestId() - Locate by test ID
frameLocator.getByText() - Locate by text content
frameLocator.getByTitle() - Locate by title attribute

getByTestId(testId)

Mon, 21 Sep 2026 15:16:28 +0000

getByTestId(testId)

Returns a locator for elements with the specified test ID attribute. This method is designed for robust test automation by locating elements using dedicated test identifiers that are independent of the visual appearance or content changes. Currently it can only work with the data-testid attribute.

Parameter	Type	Default	Description
`testId`	string \| RegExp	-	Required. The test ID value to search for. Searches for the `data-testid` attribute. Can be a string for exact match or a RegExp for pattern matching.

Returns

Type	Description
Locator	A locator object that can be used to interact with the elements matching the specified test ID.

Examples

Basic test ID usage

Locate and interact with elements using test IDs:

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 {
    const iframeHTML = `
      <input type="text" data-testid="username">
      <input type="text" data-testid="email">
      <button data-testid="submit-button">Submit</button>
    `;

    await page.setContent(`
      <iframe id="my_frame" src="data:text/html,${encodeURIComponent(iframeHTML)}"></iframe>
    `);

    const frameLocator = page.locator("#my_frame").contentFrame();
    await frameLocator.getByTestId('username').fill('FirstLast');
    await frameLocator.getByTestId('email').fill('firstlast@example.com');
    await frameLocator.getByTestId('submit-button').click();
  } finally {
    await page.close();
  }
}

Best practices

Stable identifiers: Use meaningful, stable test IDs that won’t change with refactoring or content updates.
Hierarchical naming: Use consistent naming conventions like user-profile-edit-btn.
Avoid duplicates: Ensure test IDs are unique within the page to prevent ambiguity.
Strategic placement: Add test IDs to key interactive elements and components that are frequently tested.
Team coordination: Establish test ID conventions with your development team to ensure consistency.

frameLocator.getByRole() - Locate by ARIA role
frameLocator.getByAltText() - Locate by alt text
frameLocator.getByLabel() - Locate by form labels
frameLocator.getByPlaceholder() - Locate by placeholder text
frameLocator.getByText() - Locate by text content
frameLocator.getByTitle() - Locate by title attribute

getByText(text[, options])

Mon, 21 Sep 2026 15:16:28 +0000

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.setContent(`
      <iframe id="my_frame" src="https://quickpizza.grafana.com" width="50%" height="50%"></iframe>
    `);

    const frameLocator = page.locator('#my_frame').contentFrame();
    await frameLocator.getByText('Pizza, Please!').click();

    const noThanksBtn = frameLocator.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.

frameLocator.getByRole() - Locate by ARIA role
frameLocator.getByAltText() - Locate by alt text
frameLocator.getByLabel() - Locate by form labels
frameLocator.getByPlaceholder() - Locate by placeholder text
frameLocator.getByTestId() - Locate by test ID
frameLocator.getByTitle() - Locate by title attribute

getByTitle(title[, options])

Mon, 21 Sep 2026 15:16:28 +0000

getByTitle(title[, options])

Returns a locator for elements with the specified title attribute. This method is useful for locating elements that use the title attribute to provide additional information, tooltips, or accessibility context.

Parameter	Type	Default	Description
`title`	string \| RegExp	-	Required. The title text 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 title 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 matching the specified title attribute.

Examples

Find and interact with elements by their title attribute:

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 {
    const iframeHTML = `
      <button title="Hello World">Hi</button>
      <select title="Favorite Color">
        <option value="Red">Red</option>
        <option value="Green">Green</option>
        <option value="Blue">Blue</option>
      </select>
      <input type="checkbox" title="Check me">
    `;

    await page.setContent(`
      <iframe id="my_frame" src="data:text/html,${encodeURIComponent(iframeHTML)}"></iframe>
    `);

    const frameLocator = page.locator("#my_frame").contentFrame();

    await frameLocator.getByTitle('Hello World').click();

    await frameLocator.getByTitle('Favorite Color').selectOption('Red');

    await frameLocator.getByTitle('Check me').check();
  } finally {
    await page.close();
  }
}

Common use cases

User interface controls:
- Toolbar buttons and action items
- Navigation controls (previous/next, pagination)
- Media player controls
- Menu and drop-down triggers
Informational elements:
- Help icons and tooltips
- Status indicators and badges
- Progress indicators
- Warning and error messages
Accessibility support:
- Screen reader descriptions
- Alternative text for complex elements
- Context-sensitive help
- Form field explanations

Best practices

Meaningful titles: Ensure title attributes provide clear, helpful information about the element’s purpose or content.
Accessibility compliance: Use titles to enhance accessibility, especially for elements that might not have clear visual labels.
Avoid redundancy: Don’t duplicate visible text in the title attribute unless providing additional context.
Dynamic content: When testing applications with changing title content, use flexible matching patterns or regular expressions.
Tooltip testing: Remember that title attributes often create tooltips on hover, which can be useful for UI testing.
Internationalization: Consider that title text may change in different language versions of your application.

frameLocator.getByRole() - Locate by ARIA role
frameLocator.getByAltText() - Locate by alt text
frameLocator.getByLabel() - Locate by form labels
frameLocator.getByPlaceholder() - Locate by placeholder text
frameLocator.getByTestId() - Locate by test ID
frameLocator.getByText() - Locate by visible text

locator(selector[, options])

Mon, 21 Sep 2026 15:16:28 +0000

locator(selector[, options])

The method returns an element’s Locator. Locators resolve to the element when the action takes place, which means locators can span over navigations where the underlying DOM changes.

Parameter	Type	Default	Description
selector	string	`''`	A selector to use when resolving a DOM element.
options	object	`null`
options.hasText	string or RegExp	`null`	Matches only elements that contain the specified text. String or regular expression. Optional.
options.hasNotText	string or RegExp	`null`	Matches only elements that do not contain the specified text. String or regular expression. Optional.

Returns

Type	Description
Locator	The element’s `Locator` associated with the frame.

Example

import { browser } from 'k6/browser';

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

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

  await page.setContent(`<iframe src='https://quickpizza.grafana.com'></iframe>`);

  // Get a locator for an iframe element
  const frameLocator = page.locator('iframe').contentFrame();

  // Create a locator within the frame with text filtering options
  const submitButton = frameLocator.locator('button', { hasText: 'Pizza, Please!' });
  await submitButton.click();
}

FrameLocator on Grafana Labs

frameLocator(selector)

frameLocator(selector)

Returns

Example

getByAltText(altText[, options])

getByAltText(altText[, options])

Returns

Examples

Basic alt text matching

Exact alt text matching

Using regular expressions

Common use cases

Best practices

Related

getByLabel(text[, options])

getByLabel(text[, options])

Returns

Examples

Basic form interaction

Working with different input types

Label association patterns

Common use cases

Best practices

Related

getByPlaceholder(placeholder[, options])

getByPlaceholder(placeholder[, options])

Returns

Example

Common use cases

Best practices

Related

getByRole(role[, options])

getByRole(role[, options])

Returns

Examples

Basic role selection

Complete ARIA roles reference

Widgets & Inputs

Tables & Grids

Document Structure & Semantics

Landmarks & Regions

Usage Examples by Category

Best practices

Related

getByTestId(testId)

getByTestId(testId)

Returns

Examples

Basic test ID usage

Best practices

Related

getByText(text[, options])

getByText(text[, options])

Returns

Examples

Text matching behavior

Common use cases

Best practices

Related

getByTitle(title[, options])

getByTitle(title[, options])

Returns

Examples

Common use cases

Best practices

Related

locator(selector[, options])

locator(selector[, options])

Returns

Example