Frame on Grafana Labs

$(selector)

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

$(selector)

Warning
Use locator-based frame.locator(selector) instead.

The method finds an element matching the specified selector within the frame. If no elements match the selector, the return value resolves to null. To wait for an element on the frame, use locator.waitFor([options]).

Returns

Type	Description
`Promise<ElementHandle \| null>`	A Promise that fulfills with the ElementHandle of the selector when a matching element is found or `null`.

$$(selector)

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

$$(selector)

Warning
Use locator-based frame.locator(selector) instead.

The method finds all elements matching the specified selector within the page. If no elements match the selector, the return value resolves to []. The results are returned in DOM order.

Returns

Type	Description
`Promise<ElementHandle[]>`	A Promise that fulfills with the ElementHandle array of the selector when matching elements are found.

check(selector[, options])

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

check(selector[, options])

Warning
Use locator-based locator.check([options]) instead.

This method is used to select an input checkbox.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.force	boolean	`false`	Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`).
options.noWaitAfter	boolean	`false`	If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete.
options.position	object	`null`	A point to use relative to the top left corner of the element. If not supplied, a visible point of the element is used.
options.position.x	number	`0`	The x coordinate.
options.position.y	number	`0`	The y coordinate.
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.
options.trial	boolean	`false`	Setting this to `true` will perform the actionability checks without performing the action.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the check action is finished.

childFrames()

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

childFrames()

This method returns an array of child frames.

Returns

Type	Description
`Frame[]`	An array of Frame objects.

click(selector[, options])

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

click(selector[, options])

Warning
Use locator-based locator.click([options]) instead.

This method clicks on an element matching a selector.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.button	string	`left`	The mouse button (`left`, `middle` or `right`) to use during the action.
options.clickCount	number	`1`	The number of times the action is performed.
options.delay	number	`0`	Milliseconds to wait between `mousedown` and `mouseup`.
options.force	boolean	`false`	Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`). Avoid using `force: true` in `click` actions, as it may mask underlying test design or app issues. It bypasses normal user interaction checks, and elements may not be clickable due to cookie banner interference.
options.modifiers	string[]	`null`	`Alt`, `Control`, `Meta` or `Shift` modifiers keys pressed during the action. If not specified, currently pressed modifiers are used.
options.noWaitAfter	boolean	`false`	If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete.
options.position	object	`null`	A point to use relative to the top left corner of the element. If not supplied, a visible point of the element is used.
options.position.x	number	`0`	The x coordinate.
options.position.y	number	`0`	The y coordinate.
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.
options.trial	boolean	`false`	Setting this to `true` will perform the actionability checks without performing the action. Useful to wait until the element is ready for the action without performing it.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the click action is finished.

content()

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

content()

Gets the HTML content of the frame.

Returns

Type	Description
`Promise<string>`	A Promise that fulfills with the HTML content of the frame as a string value or `null` if the attribute is not present.

dblclick(selector[, options])

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

dblclick(selector[, options])

Warning
Use locator-based locator.dblclick([options]) instead.

Double clicks on an element matching the provided selector.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. The first element will be used if multiple elements match the selector.
options	object	`null`
options.button	string	`left`	The mouse button (`left`, `middle` or `right`) to use during the action.
options.delay	number	`0`	Milliseconds to wait between `mousedown` and `mouseup`.
options.force	boolean	`false`	Bypasses the actionability checks (`visible`, `stable`, `enabled`) if set to `true`.
options.modifiers	string[]	`null`	`Alt`, `Control`, `Meta` or `Shift` modifiers keys pressed during the action. If not specified, currently pressed modifiers are used.
options.noWaitAfter	boolean	`false`	If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete.
options.position	object	`null`	A point to use relative to the top left corner of the element. If not supplied, a visible point of the element is used.
options.position.x	number	`0`	The x coordinate.
options.position.y	number	`0`	The y coordinate.
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.
options.trial	boolean	`false`	Setting this to `true` will perform the actionability checks without performing the action.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the double click action is finished.

dispatchEvent(selector, type, eventInit[, options])

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

dispatchEvent(selector, type, eventInit[, options])

Warning
Use locator-based locator.dispatchEvent(type, eventInit[, options]) instead.

Dispatches HTML DOM event types e.g. 'click'.

Parameter	Type	Defaults	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
type	string	`''`	DOM event type e.g. `'click'`.
eventInit	object	`null`	Optional event specific properties. See eventInit for more details.
options	object	`null`
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

eventInit

Since eventInit is event-specific, please refer to the events documentation for the lists of initial properties:

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the event is dispatched.

evaluate(pageFunction[, arg])

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

evaluate(pageFunction[, arg])

Executes JavaScript code in the page and returns the value of the pageFunction invocation.

Parameter	Type	Defaults	Description
pageFunction	function or string		Function to be evaluated in the page context. This can also be a string.
arg	string	`''`	Optional argument to pass to `pageFunction`

Returns

Type	Description
`Promise<any>`	The value of the `pageFunction` invocation.

evaluateHandle(pageFunction[, arg])

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

evaluateHandle(pageFunction[, arg])

Executes JavaScript code in the page and returns the value of the pageFunction invocation as a JSHandle.

The only difference between page.evaluate() and page.evaluateHandle() is that page.evaluateHandle() returns JSHandle.

Parameter	Type	Defaults	Description
pageFunction	function or string		Function to be evaluated in the page context. This can also be a string.
arg	string	`''`	Optional argument to pass to `pageFunction`

Returns

Type	Description
`Promise<JSHandle>`	The JSHandle instance associated with the frame.

fill(selector, value[, options])

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

fill(selector, value[, options])

Warning
Use locator-based locator.fill(value[, options]) instead.

Fill an input, textarea or contenteditable element with the provided value.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
value	string	`''`	Value to fill out for the `input`, `textarea` or `contenteditable` element.
options	object	`null`
options.force	boolean	`false`	Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`).
options.noWaitAfter	boolean	`false`	If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete.
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the element is filled with the value.

focus(selector[, options])

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

focus(selector[, options])

Warning
Use locator-based locator.focus([options]) instead.

This method fetches an element with selector and focuses it.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the element is focused.

frameElement()

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

frameElement()

This method returns the frame’s DOM element as an ElementHandle.

Returns

Type	Description
`Promise<ElementHandle>`	A Promise that fulfills with the ElementHandle of the frame’s DOM element.

frameLocator(selector)

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

frameLocator(selector)

Returns a FrameLocator for the iframe that matches the given selector within this frame. Use this to interact with elements inside nested iframes.

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

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.goto('https://example.com/page-with-nested-iframes');

    // Get the outer frame, then locate a nested iframe inside it
    const mainFrame = page.mainFrame();
    const innerFrame = mainFrame.frameLocator('iframe#inner');
    await innerFrame.locator('button').click();
  } finally {
    await page.close();
  }
}

getAttribute(selector, name[, options])

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

getAttribute(selector, name[, options])

Warning
Use locator-based locator.getAttribute() instead.

Returns the element attribute value for the given attribute name.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
name	string	`''`	Attribute name to get the value for.
options	object	`null`
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Returns

Type	Description
`Promise<string \| null>`	A Promise that fulfills with the value of the attribute. Else, it returns `null`.

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.goto('https://quickpizza.grafana.com');

    const logo = page.mainFrame().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.goto('https://quickpizza.grafana.com');

    const logo = page.mainFrame().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.goto('https://quickpizza.grafana.com');

    const logo = page.mainFrame().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.

frame.getByRole() - Locate by ARIA role
frame.getByLabel() - Locate by form labels
frame.getByPlaceholder() - Locate by placeholder text
frame.getByTestId() - Locate by test ID
frame.getByTitle() - Locate by title attribute
frame.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 {
    await page.setContent(`
      <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">
    `);

    const frame = page.mainFrame();
    const username = frame.getByLabel('Username (hint: default)', { exact: true });
    const password = frame.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 {
    await page.setContent(`
      <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>
    `);

    const frame = page.mainFrame();

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

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

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

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

    // Textarea
    await frame.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.

frame.getByRole() - Locate by ARIA role
frame.getByAltText() - Locate by alt text
frame.getByPlaceholder() - Locate by placeholder text
frame.getByTestId() - Locate by test ID
frame.getByTitle() - Locate by title attribute
frame.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 {
    await page.setContent(`
      <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">
    `);

    const frame = page.mainFrame();
    await frame.getByPlaceholder('First name').fill('First');
    await frame.getByPlaceholder('Last name').fill('Last');
    await frame.getByPlaceholder('dd/mm/yyyy').fill('01/01/1990');

    await frame.getByPlaceholder('your.email@example.com').fill('first.last@example.com');
    await frame.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.

frame.getByRole() - Locate by ARIA role
frame.getByAltText() - Locate by alt text
frame.getByLabel() - Locate by form labels (preferred for accessibility)
frame.getByTestId() - Locate by test ID
frame.getByTitle() - Locate by title attribute
frame.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.goto('https://quickpizza.grafana.com/');

    const frame = page.mainFrame();
    await frame.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.

frame.getByAltText() - Locate by alt text
frame.getByLabel() - Locate by form labels
frame.getByPlaceholder() - Locate by placeholder text
frame.getByTestId() - Locate by test ID
frame.getByText() - Locate by text content
frame.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 {
    await page.setContent(`
      <input type="text" data-testid="username">
      <input type="text" data-testid="email">
      <button data-testid="submit-button">Submit</button>
    `);

    const frame = page.mainFrame();
    await frame.getByTestId('username').fill('FirstLast');
    await frame.getByTestId('email').fill('firstlast@example.com');
    await frame.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.

frame.getByRole() - Locate by ARIA role
frame.getByAltText() - Locate by alt text
frame.getByLabel() - Locate by form labels
frame.getByPlaceholder() - Locate by placeholder text
frame.getByText() - Locate by text content
frame.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.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.

frame.getByRole() - Locate by ARIA role
frame.getByAltText() - Locate by alt text
frame.getByLabel() - Locate by form labels
frame.getByPlaceholder() - Locate by placeholder text
frame.getByTestId() - Locate by test ID
frame.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 {
    await page.setContent(`
      <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">
    `);

    const frame = page.mainFrame();

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

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

    await frame.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.

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

goto(url[, options])

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

goto(url[, options])

Navigates to the specified URL and returns the main resource response.

Navigating to about:blank or navigation to the same URL with a different hash, will succeed and return null.

Parameter	Type	Default	Description
url	string	`''`	URL to navigate frame to. The url should include scheme, e.g. `https://`.
options	object	`null`
options.referer	string	`''`	Referer header value.
options.timeout	number	`30000`	Maximum operation time in milliseconds. Pass `0` to disable the timeout. The default value can be changed via the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. Setting the value to `0` will disable the timeout.
options.waitUntil	string	`load`	When to consider operation to have succeeded. See Events for more details.

Events

Caution
networkidle is DISCOURAGED. Don’t use this method for testing especially with chatty websites where the event may never fire, rely on web assertions to assess readiness instead.

Events can be either:

'domcontentloaded' - consider operation to be finished when the DOMContentLoaded event is fired.
'load' - consider operation to be finished when the load event is fired.
'networkidle' - Consider operation to be finished when there are no network connections for at least 500 ms.

Returns

Type	Description
`<Promise<Response \| null>`	The Response> instance associated with the frame. Else, it returns `null`.

hover(selector[, options])

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

hover(selector[, options])

Warning
Use locator-based locator.hover([options]) instead.

This method hovers over an element matching selector.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.force	boolean	`false`	Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`).
options.modifiers	string[]	`null`	`Alt`, `Control`, `Meta` or `Shift` modifiers keys pressed during the action. If not specified, currently pressed modifiers are used.
options.noWaitAfter	boolean	`false`	If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete.
options.position	object	`null`	A point to use relative to the top left corner of the element. If not supplied, a visible point of the element is used.
options.position.x	number	`0`	The x coordinate.
options.position.y	number	`0`	The y coordinate.
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.
options.trial	boolean	`false`	Setting this to `true` will perform the actionability checks without performing the action.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the hover action is finished.

innerHTML(selector[, options])

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

innerHTML(selector[, options])

Warning
Use locator-based locator.innerHTML([options]) instead.

Returns the element.innerHTML.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Returns

Type	Description
`Promise<string>`	A Promise that fullfils with the inner HTML of the element.

innerText(selector[, options])

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

innerText(selector[, options])

Warning
Use locator-based locator.innerText([options]) instead.

Returns the element.innerText.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Returns

Type	Description
`Promise<string>`	A Promise that fullfils with the inner text (represents the rendered text content of an element handle and its descendants) of the element.

inputValue(selector[, options])

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

inputValue(selector[, options])

Warning
Use locator-based locator.inputValue([options]) instead.

Returns input.value for the selected input, textarea or select element.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Returns

Type	Description
`Promise<string>`	A Promise that fullfils with the input value of the element.

isChecked(selector[, options])

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

isChecked(selector[, options])

Warning
Use locator-based locator.isChecked([options]) instead.

Checks to see if the checkbox input type is selected or not.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Returns

Type	Description
`Promise<bool>`	A Promise that fullfils with `true` if the checkbox is selected, else `false`.

isDetached()

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

isDetached()

Reports whether the frame is detached from the DOM.

Returns

Type	Description
`bool`	`true` if the frame is detached from the DOM, and `false` otherwise.

isDisabled(selector[, options])

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

isDisabled(selector[, options])

Warning
Use locator-based locator.isDisabled([options]) instead.

Checks if the element is disabled.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Returns

Type	Description
`Promise<bool>`	A Promise that fullfils with `true` if the element is `disabled`, else `false`.

isEditable(selector[, options])

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

isEditable(selector[, options])

Warning
Use locator-based locator.isEditable([options]) instead.

Checks if the element is editable.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Returns

Type	Description
`Promise<bool>`	A Promise that fullfils with `true` if the element is `editable`, else `false`.

isEnabled(selector[, options])

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

isEnabled(selector[, options])

Warning
Use locator-based locator.isEnabled([options]) instead.

Checks if the element is enabled.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Returns

Type	Description
`Promise<bool>`	A Promise that fullfils with `true` if the element is `enabled`, else `false`.

isHidden(selector[, options])

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

isHidden(selector[, options])

Warning
Use locator-based locator.isHidden([options]) instead.

Checks if the element is hidden.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first one will be used.
options	object	`null`
options.strict	boolean	`false`	When `true`, the call requires the selector to resolve to a single element. If the given selector resolves to more than one element, the call throws an exception.

Returns

Type	Description
bool	`true` if the element is `hidden`, `false` otherwise.

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();

  await page.goto('https://test.k6.io/browser.php');
  if (await page.isHidden('#input-text-hidden')) {
    console.log('element is hidden');
  }
}

isVisible(selector[, options])

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

isVisible(selector[, options])

Warning
Use locator-based locator.isVisible([options]) instead.

Checks if the element is visible.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first one will be used.
options	object	`null`
options.strict	boolean	`false`	When `true`, the call requires the selector to resolve to a single element. If the given selector resolves to more than one element, the call throws an exception.

Returns

Type	Description
bool	`true` if the element is `visible`, `false` otherwise.

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();

  await page.goto('https://test.k6.io/browser.php');

  const frames = page.frames();

  if (frames[0].isVisible('#text1')) {
    console.log('element is visible');
  }
}

locator(selector[, options])

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

locator(selector[, options])

The method returns an element 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 `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();

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

    // Get the mainframe of the page
    const frame = page.mainFrame();

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

name()

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

name()

This method returns the name of the frame.

Returns

Type	Description
`string`	The name of the frame.

page()

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

page()

This method returns the parent Page object of the Frame.

Returns

Type	Description
`Page`	The parent page object of the frame.

parentFrame()

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

parentFrame()

This method returns the parent Frame object of the current frame.

Returns

Type	Description
`Frame \| null`	The parent frame object of the frame. Or `null` if the frame has no parent (main frame).

press(selector, key[, options])

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

press(selector, key[, options])

Warning
Use locator-based locator.press() instead.

Focuses the element, and then uses keyboard.down(key) and keyboard.up(key).

A superset of the key values can be found here.

Following modification shortcuts are also supported: Shift, Control, Alt, Meta, ShiftLeft.

Holding down Shift will type the text that corresponds to the key in the upper case.

If key is a single character, it is case-sensitive, so the values a and A will generate different respective texts.

Shortcuts such as key: "Control+o" or key: "Control+Shift+T" are supported as well. When specified with the modifier, modifier is pressed and being held while the subsequent key is being pressed.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
key	string	`''`	Name of the key to press or a character to generate, such as `ArrowLeft` or `a`. A superset of the key values can be found here.
options	object	`null`
options.delay	number	`0`	Milliseconds to wait between `keydown` and `keyup`.
options.noWaitAfter	boolean	`false`	If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete.
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Returns

Type	Description
`Promise<void>`	A Promise that fullfils when the press action is finished.

selectOption(selector, values[, options])

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

selectOption(selector, values[, options])

Warning
Use locator-based locator.selectOption() instead.

Selects one or more options which match the values from a <select> element.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
values	string or string[] or object	`''`	If the `select` has the multiple attribute, all matching options are selected, otherwise only the first option matching one of the passed options is selected. Object can be made up of keys with `value`, `label` or `index`.
options	object	`null`
options.force	boolean	`false`	Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`).
options.noWaitAfter	boolean	`false`	If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete.
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Returns

Type	Description
`Promise<string[]>`	A Promise that fulfills with the list of the selected options.

setChecked(selector, checked[, options])

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

setChecked(selector, checked[, options])

Warning
Use locator.setChecked(checked [, options]) instead.

Use this method to select on unselect an input or radio checkbox.

Parameter	Type	Default	Description
options	object	`null`	Optional parameters.
options.force	boolean	`false`	Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`).
options.noWaitAfter	boolean	`false`	If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete.
options.position	object	`null`	A point to use relative to the top left corner of the element. If not supplied, a visible point of the element is used.
options.position.x	number	`0`	The x coordinate.
options.position.y	number	`0`	The y coordinate.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.
options.trial	boolean	`false`	Setting this to `true` will perform the actionability checks without performing the action.
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the check action is finished.

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();
  await page.goto('https://test.k6.io/browser.php');

  const frame = page.mainFrame();
  await frame.setChecked('#checkbox1', true);
  await frame.setChecked('#checkbox1', false);

  await page.close();
}

setContent(html[, options])

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

setContent(html[, options])

Sets the supplied HTML string to the current frame.

Parameter	Type	Default	Description
html	string	`''`	HTML markup to assign to the page.
options	object	`null`
options.timeout	number	`30000`	Maximum operation time in milliseconds. Pass `0` to disable the timeout. The default value can be changed via the browserContext.setDefaultNavigationTimeout(timeout), browserContext.setDefaultTimeout(timeout), page.setDefaultNavigationTimeout(timeout) or page.setDefaultTimeout(timeout) methods. Setting the value to `0` will disable the timeout.
options.waitUntil	string	`load`	When to consider operation to have succeeded. See Events for more details.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the page has been set with the supplied HTML.

setInputFiles(selector, file[, options])

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

setInputFiles(selector, file[, options])

Sets the file input element’s value to the specified files.

To work with local files on the file system, use the experimental fs module to load and read the file contents.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
file	object	`null`	This is a required parameter.
file.name	string	`''`	The name of the file. For example, `file.txt`.
file.mimeType	string	`''`	The type of the file content. For example, `text/plain`.
file.buffer	ArrayBuffer	`[]`	Base64 encoded content of the file.
options	object	`null`	This is an optional parameter.
options.noWaitAfter	boolean	`false`	If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Inline File Example

import { browser } from 'k6/browser';
import encoding from 'k6/encoding';

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

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

  try {
    // In this example we create a simple web page with an upload input field.
    // Usually, you would use page.goto to navigate to a page with a file input field.
    await page.setContent(`
      <html>
        <head></head>
        <body>
            <!-- Simple file upload form -->
            <form method="POST" action="/upload" enctype="multipart/form-data">
                <input type="file" id="upload" multiple />
                <input type="submit" value="Send" />
            </form>
        </body>
      </html>`);

    const frame = page.mainFrame();

    // The file is set to the input element with the id "upload".
    frame.setInputFiles('input[id="upload"]', {
      name: 'file.txt',
      mimetype: 'text/plain',
      buffer: encoding.b64encode('hello world'),
    });
  } finally {
    await page.close();
  }
}

Local File Example

import { browser } from 'k6/browser';
import encoding from 'k6/encoding';
import { open } from 'k6/experimental/fs';

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

// Declare the location of the file on the local filesystem.
let file;
(async function () {
  file = await open('/abs/path/to/file.txt');
})();

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

  try {
    // In this example we create a simple web page with an upload input field.
    // Usually, you would use page.goto to navigate to a page with a file input field.
    await page.setContent(`
      <html>
        <head></head>
        <body>
            <!-- Simple file upload form -->
            <form method="POST" action="/upload" enctype="multipart/form-data">
                <input type="file" id="upload" multiple />
                <input type="submit" value="Send" />
            </form>
        </body>
      </html>`);

    const frame = page.mainFrame();

    // Read the whole file content into a buffer.
    const buffer = await readAll(file);

    // The file is set to the input element with the id "upload".
    frame.setInputFiles({
      name: 'file.txt',
      mimetype: 'text/plain',
      buffer: encoding.b64encode(buffer),
    });
  } finally {
    await page.close();
  }
}

// readAll will read the whole of the file from the local filesystem into a
// buffer.
async function readAll(file) {
  const fileInfo = await file.stat();
  const buffer = new Uint8Array(fileInfo.size);

  const bytesRead = await file.read(buffer);
  if (bytesRead !== fileInfo.size) {
    throw new Error('unexpected number of bytes read');
  }

  return buffer;
}

tap(selector[, options])

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

tap(selector[, options])

Tap the first element that matches the selector.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.force	boolean	`false`	Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`).
options.modifiers	string[]	`null`	`Alt`, `Control`, `Meta` or `Shift` modifiers keys pressed during the action. If not specified, currently pressed modifiers are used.
options.noWaitAfter	boolean	`false`	If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete.
options.position	object	`null`	A point to use relative to the top left corner of the element. If not supplied, a visible point of the element is used.
options.position.x	number	`0`	The x coordinate.
options.position.y	number	`0`	The y coordinate.
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.
options.trial	boolean	`false`	Setting this to `true` will perform the actionability checks without performing the action.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the tap action is finished.

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({
    hasTouch: true,
  });

  await page.goto('https://test.k6.io/browser.php');
  const frame = page.mainFrame();
  await frame.tap("#numbers-options");
}

textContent(selector[, options])

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

textContent(selector[, options])

Warning
Use locator-based locator.textContent([options]) instead.

Returns the element.textContent.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Returns

Type	Description
`Promise<string \| null>`	A Promise that fulfills with the text content of the selector or `null`.

title()

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

title()

Returns the frame’s title.

Returns

Type	Description
`Promise<string>`	A Promise that fulfills with the frame’s title.

type(selector, text[, options])

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

type(selector, text[, options])

Warning
Use locator-based locator.type() instead.

Type the text in the first element found that matches the selector.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
text	string	`''`	A text to type into a focused element.
options	object	`null`
options.delay	number	`0`	Milliseconds to wait between key presses. Defaults to `0`.
options.noWaitAfter	boolean	`false`	If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete.
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the text has been typed.

uncheck(selector[, options])

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

uncheck(selector[, options])

Warning
Use locator-based locator.uncheck([options]) instead.

This method is used to unselect an input checkbox.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.force	boolean	`false`	Setting this to `true` will bypass the actionability checks (`visible`, `stable`, `enabled`).
options.noWaitAfter	boolean	`false`	If set to `true` and a navigation occurs from performing this action, it will not wait for it to complete.
options.position	object	`null`	A point to use relative to the top left corner of the element. If not supplied, a visible point of the element is used.
options.position.x	number	`0`	The x coordinate.
options.position.y	number	`0`	The y coordinate.
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.
options.trial	boolean	`false`	Setting this to `true` will perform the actionability checks without performing the action.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the checkbox is unchecked.

url()

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

url()

Returns the frame’s URL.

Returns

Type	Description
string	The frame’s URL.

waitForFunction(pageFunction, options[, arg])

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

waitForFunction(pageFunction, options[, arg])

Returns when the pageFunction returns a truthy value.

Parameter	Type	Default	Description
pageFunction	function		Function to be evaluated in the page context.
options	object	`null`
options.polling	number, `raf`, or `mutation`	`raf`	If `polling` is `'raf'`, then `pageFunction` is constantly executed in `requestAnimationFrame` callback. If `polling` is `'mutation'`, then `pageFunction` is executed on each change to the DOM tree. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.
arg	any	`''`	Optional argument to pass to `pageFunction`

Returns

Type	Description
Promise< JSHandle>	The `JSHandle` instance associated with the page.

waitForLoadState(state[, options])

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

waitForLoadState(state[, options])

Caution
This method has known issues. For details, refer to #880.

This waits for the given load state to be reached. It will immediately unblock if that lifecycle event has already been received.

Parameter	Type	Default	Description
state	string	`load`	Optional load state to wait for. See Events for more details.
options	object	`null`
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Events

Caution
networkidle is DISCOURAGED. Don’t use this method for testing especially with chatty websites where the event may never fire, rely on web assertions to assess readiness instead.

Events can be either:

'domcontentloaded' - consider operation to be finished when the DOMContentLoaded event is fired.
'load' - consider operation to be finished when the load event is fired.
'networkidle' - Consider operation to be finished when there are no network connections for at least 500 ms.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the load state is reached.

waitForNavigation([options])

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

waitForNavigation([options])

Waits for the given navigation lifecycle event to occur and returns the main resource response.

Parameter	Type	Default	Description
options	object	`null`
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.
options.url	string\|RegExp	`null`	URL or URL pattern to match the navigation URL against. Useful when frame navigation performs multiple redirects and you need to wait until a final destination within the frame is reached.
options.waitUntil	string	`load`	When to consider operation to have succeeded. See Events for more details.

When to use the url option

Use options.url when frame navigation passes through several intermediate pages (e.g., third‑party authentication or consent flows) before settling on a final URL. Matching the final URL or a regex pattern helps you reliably wait for the intended destination inside the frame. However, opt to work with waitForURL instead since it mitigates the risk of race conditions better than waitForNavigation.

Events

Caution
networkidle is DISCOURAGED. Don’t use this method for testing especially with chatty websites where the event may never fire, rely on web assertions to assess readiness instead.

Events can be either:

'domcontentloaded' - consider operation to be finished when the DOMContentLoaded event is fired.
'load' - consider operation to be finished when the load event is fired.
'networkidle' - Consider operation to be finished when there are no network connections for at least 500 ms.

Returns

Type	Description
Promise<null \| Response>	The `Response` instance associated with the frame. Else, it returns `null`

Examples

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 src="https://quickpizza.grafana.com/test.k6.io/" width="50%" height="50%"></iframe>
    `);

    // Retreive the frame of the iframe
    const iframeElement = await page.$('iframe');
    const frame = await iframeElement.contentFrame();

    // Wait for navigation to a specific URL
    await Promise.all([
      frame.click('a[href="/my_messages.php"]'),
      frame.waitForNavigation({ url: 'https://quickpizza.grafana.com/my_messages.php' }),
    ]);

    await frame.goto('https://quickpizza.grafana.com/test.k6.io/');

    // Wait for navigation using URL pattern with RegExp
    await Promise.all([
      frame.click('a[href="/browser.php"]'),
      frame.waitForNavigation({ url: /\/browser\.php$/ }),
    ]);
  } finally {
    await page.close();
  }
}

waitForSelector(selector[, options])

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

waitForSelector(selector[, options])

Note
Use web assertions that assert visibility or a locator-based locator.waitFor([options]) instead.

Returns when element specified by selector satisfies state option.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.state	string	`visible`	Can be either `attached`, `detached`, `visible`, `hidden` See Element states for more details.
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.

Element states

Element states can be either:

'attached' - wait for element to be present in DOM.
'detached' - wait for element to not be present in DOM.
'visible' - wait for element to have non-empty bounding box and no visibility:hidden.
'hidden' - wait for element to be either detached from DOM, or have an empty bounding box or visibility:hidden.

Returns

Type	Description
`Promise<ElementHandle \| null>`	A Promise that fulfills with the ElementHandle when a matching element is found, or `null` if the element is not found.

waitForTimeout(timeout)

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

waitForTimeout(timeout)

Note
Never wait for timeout in production, use this only for debugging. Tests that wait for time are inherently flaky. Use Locator actions and web assertions that wait automatically.

Waits for the given timeout in milliseconds.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the timeout is reached.

waitForURL(url[, options])

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

waitForURL(url[, options])

Waits for the frame to navigate to the specified URL. This method is useful for ensuring that navigation within a specific frame (such as an iframe) to a particular URL has completed before proceeding with the test. This is especially useful if there are multiple redirects before hitting the end destination.

Parameter	Type	Default	Description
url	string\|RegExp	-	Required. URL or URL pattern to match against. The method will wait until the frame navigates to a URL that matches this parameter.
options	object	`null`
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.
options.waitUntil	string	`load`	When to consider operation to have succeeded. See Events for more details.

Events

Caution
networkidle is DISCOURAGED. Don’t use this method for testing especially with chatty websites where the event may never fire, rely on web assertions to assess readiness instead.

Events can be either:

'domcontentloaded' - consider operation to be finished when the DOMContentLoaded event is fired.
'load' - consider operation to be finished when the load event is fired.
'networkidle' - Consider operation to be finished when there are no network connections for at least 500 ms.

Returns

Type	Description
Promise	A Promise that resolves when the frame has navigated to the specified URL and the specified load state has been reached.

Examples

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 src="https://quickpizza.grafana.com/test.k6.io/" width="50%" height="50%"></iframe>
    `);

    const iframeElement = await page.$('iframe');
    const iframeContent = await iframeElement.contentFrame();

    // Wait for navigation to a specific URL
    await Promise.all([
      iframeContent.click('a[href="/my_messages.php"]'),
      iframeContent.waitForURL('https://quickpizza.grafana.com/my_messages.php'),
    ]);

    await iframeContent.goto('https://quickpizza.grafana.com/test.k6.io/');

    // Wait for navigation using URL pattern with RegExp
    await Promise.all([
      iframeContent.click('a[href="/browser.php"]'),
      iframeContent.waitForURL(/\/browser\.php$/),
    ]);
  } finally {
    await page.close();
  }
}

Valid usage patterns for waitForURL

Use one of the following patterns to coordinate the action that triggers navigation with waiting for the final URL.

await Promise.all([
  frame.waitForURL('https://quickpizza.grafana.com/my_messages.php'),
  frame.locator('a[href="/my_messages.php"]').click(),
]);

const navPromise = frame.waitForURL('https://quickpizza.grafana.com/my_messages.php');
await frame.locator('a[href="/my_messages.php"]').click();
await navPromise;

Unlike waitForNavigation, waitForURL will first check whether it is already on the page with the given URL before proceeding to wait. If it is already there and the waitUntil condition has also been met, it will return straight away. This means that it is safe to do this:

await frame.locator('a[href="/my_messages.php"]').click();
await frame.waitForURL('https://quickpizza.grafana.com/my_messages.php');

Best practices

Verify frame existence: Frames can be created, destroyed, or replaced during page navigation. Always verify frame existence before calling waitForURL().
Use appropriate selectors: Use frame selectors that are stable and unique.
Handle cross-origin scenarios: Be aware of limitations when working with cross-origin iframes.
Combine with content verification: After URL change, verify that the expected content is present.
Consider frame timing: Frame navigation may happen after page navigation, so allow appropriate time.

Common use cases

Payment processing: Waiting for payment iframe redirects
Social media embeds: Handling navigation in embedded social content
OAuth flows: Managing authentication within iframes
Multi-frame applications: Coordinating navigation across multiple frames
Embedded widgets: Testing third-party widget navigation

frame.waitForNavigation() - Wait for frame navigation events
frame.waitForLoadState() - Wait for load states

Frame on Grafana Labs

$(selector)

$(selector)

Returns

$$(selector)

$$(selector)

Returns

check(selector[, options])

check(selector[, options])

Returns

childFrames()

childFrames()

Returns

click(selector[, options])

click(selector[, options])

Returns

content()

content()

Returns

dblclick(selector[, options])

dblclick(selector[, options])

Returns

dispatchEvent(selector, type, eventInit[, options])

dispatchEvent(selector, type, eventInit[, options])

eventInit

Returns

evaluate(pageFunction[, arg])

evaluate(pageFunction[, arg])

Returns

evaluateHandle(pageFunction[, arg])

evaluateHandle(pageFunction[, arg])

Returns

fill(selector, value[, options])

fill(selector, value[, options])

Returns

focus(selector[, options])

focus(selector[, options])

Returns

frameElement()

frameElement()

Returns

frameLocator(selector)

frameLocator(selector)

Returns

Example

getAttribute(selector, name[, options])

getAttribute(selector, name[, options])

Returns

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