Locator on Grafana Labs

all()

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

all()

When multiple elements match the selector, returns an array of Locator, each pointing to their respective element.

Returns

Type	Description
Array< Locator>	An array of `Locator`.

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

  const options = await page.locator('#numbers-options > option').all();
  console.log(`Found ${options.length} options.`);
  
  for (const option of options) {
    console.log('Inner text: ', await option.innerText());
    await option.click();
  }

  await page.close();
}

boundingBox([options])

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

boundingBox([options])

Returns the bounding box of the element. The bounding box is calculated with respect to the position of the Frame of the current element, which is usually the Page’s main frame.

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.

Returns

Type	Description
`Promise<null \| Rect>`	A Promise that fulfills with the bounding box of the element as a Rect. If the element is not visible, the Promise resolves to `null`.

Rect

The Rect object represents the bounding box of an element.

Property	Type	Description
x	`number`	The x-coordinate of the element in pixels.
y	`number`	The y-coordinate of the element in pixels.
width	`number`	The width of the element in pixels.
height	`number`	The height of the element in pixels.

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 textbox = page.locator('#text1');
  const boundingBox = await textbox.boundingBox();
  console.log(`x: ${boundingBox.x}, y: ${boundingBox.y}, width: ${boundingBox.width}, height: ${boundingBox.height}`);

  await page.close();
}

check([options])

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

check([options])

Caution
This feature has known issues. For details, refer to #471 and #475.

Use this method to select an input checkbox.

Parameter	Type	Default	Description
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.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.

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 checkbox = page.locator('#checkbox1');
  await checkbox.check();
}

clear([options])

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

clear([options])

Clears text boxes and input fields (input, textarea or contenteditable elements) of any existing values.

Parameter	Type	Default	Description
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.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 clear action is finished.

Example

import { browser } from 'k6/browser';
import { check } from "https://jslib.k6.io/k6-utils/1.5.0/index.js";

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

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

  await page.goto("https://test.k6.io/my_messages.php", {
    waitUntil: 'networkidle',
  });

  // Fill an input element with some text that we will later clear
  const login = page.locator('input[name="login"]');
  await login.type('admin');

  // Check that the element has been filled with text
  await check(login, {
    'not empty': async lo => await lo.inputValue() != '',
  });

  // Now clear the text from the element
  await login.clear();

  // Check that the element is now empty
  await check(login, {
    empty: async lo => await lo.inputValue() == '',
  });

  await page.close();
}

click([options])

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

click([options])

Caution
This method has known issues. For details, refer to #471 and #474.

Mouse click on the chosen element.

Parameter	Type	Default	Description
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.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 click action is finished.

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

  await page.goto('https://test.k6.io/browser.php');
  const button = page.locator('#counter-button');
  await button.click();
}

When a click action results in a page navigation, remember to work with Promise.all() and page.waitForNavigation() to properly handle the asynchronous operation.

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/');
  const messagesLink = page.locator('a[href="/my_messages.php"]');

  await Promise.all([page.waitForNavigation(), messagesLink.click()]);
}

contentFrame()

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

contentFrame()

This method returns a FrameLocator object pointing to the same iframe as this locator. This is useful when you have a Locator object obtained somewhere, and later on would like to interact with the content inside the frame.

Returns

Type	Description
FrameLocator	The `FrameLocator` pointing to the same`iframe` as this locator.

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="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();
  }
}

count()

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

count()

Returns the number of elements matching the selector. This does not wait for actionability checks (whether the matching elements are visible, stable, and enabled). If the return value from count doesn’t match the expected count, then you should manually retry the API call.

Returns

Type	Description
`Promise<number>`	A promise which resolves with the number of elements matching the selector.

Example

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';
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.goto('https://quickpizza.grafana.com/login');

  const expected = 3;
  let match = false;
  for (let i = 0; i < 5; i++) {
    match = await page.locator('input').count();
    if (match == expected) {
      break;
    }
  }

  expect(match).toEqual(expected);

  await page.close();
}

dblclick([options])

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

dblclick([options])

Caution
This feature has known issues. For details, refer to #471.

Mouse double click on the chosen element.

Parameter	Type	Default	Description
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`	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.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.

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 button = page.locator('#counter-button');
  await button.dblclick();
}

dispatchEvent(type, eventInit, [options])

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

dispatchEvent(type, eventInit, [options])

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

Parameter	Type	Defaults	Description
type	string	`''`	DOM event type e.g. `'click'`.
eventInit	object	`null`	Optional event specific properties. See eventInit 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.

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 once the event is dispatched.

Example

import { browser } from 'k6/browser';

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

  await page.goto('https://test.k6.io/browser.php');
  const button = page.locator('#counter-button');
  await button.dispatchEvent('click');

  await page.close();
}

evaluate(pageFunction[, arg])

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

evaluate(pageFunction[, arg])

Executes JavaScript code in the page, passing the matching element of the locator as the first argument to the pageFunction and arg as the following arguments. It returns the value of the pageFunction invocation.

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

Returns

Type	Description
Promise	The return value of `pageFunction`.

Example

import { browser } from 'k6/browser';
import { check } from 'https://jslib.k6.io/k6-utils/1.5.0/index.js';

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", { waitUntil: "load" });

    await page.getByText('Pizza, Please!').click();

    await check(page, {
      'pizza name': async p => {
        const n = await p.locator('#pizza-name').evaluate((pizzaName, extra) => pizzaName.textContent + extra, ' Super pizza!');
        return n == 'Our recommendation: Super pizza!';
      }
    });
  } finally {
    await page.close();
  }
}

evaluateHandle(pageFunction[, arg])

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

evaluateHandle(pageFunction[, arg])

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

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

Returns

Type	Description
Promise	A JSHandle of the return value of `pageFunction`.

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://quickpizza.grafana.com", { waitUntil: "load" });

    await page.getByText('Pizza, Please!').click();

    const jsHandle = await page.locator('#pizza-name').evaluateHandle((pizzaName) => pizzaName);

    const obj = await jsHandle.evaluateHandle((handle) => {
      return { innerText: handle.innerText };
    });
    console.log(await obj.jsonValue()); // {"innerText":"Our recommendation:"}
  } finally {
    await page.close();
  }
}

fill(value, [options])

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

fill(value, [options])

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

Parameter	Type	Default	Description
value	string	`''`	Value to set 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.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 fill 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 textbox = page.locator('#text1');
  await textbox.fill('hello world!');
}

pressSequentially() - Type text character by character with keyboard events
type() - Type text into an input field

filter(options)

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

Returns a new Locator that matches only elements containing or excluding specified text.

Parameter	Type	Default	Description
options	object	`null`	If not provided, the method behaves like a no-op and returns a locator identical to the original one.
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	A new filtered `Locator` that can be chained with other methods.

Example

import { browser } from 'k6/browser';
import { check } from 'https://jslib.k6.io/k6-utils/1.5.0/index.js';

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

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

  await page.setContent(`
    <ul>
      <li>
        <h3>Product 1</h3>
        <button>Add to cart 1</button>
      </li>
      <li>
        <h3>Product 2</h3>
        <button>Add to cart 2</button>
      </li>
    </ul>
  `);

  // Filter list items that contain "Product 2" text
  const product2Item = page
    .locator('li')
    .filter({ hasText: 'Product 2' })
    .first();

  const product2Text = await product2Item.textContent();
  console.log(product2Text); // Contains "Product 2" and "Add to cart 2"

  // Filter list items that do NOT contain "Product 2" using regex
  const product1Item = page
    .locator('li')
    .filter({ hasNotText: /Product 2/ })
    .first();

  const product1Text = await product1Item.textContent();
  console.log(product1Text); // Contains "Product 1" and "Add to cart 1"

  await page.close();
}

first()

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

first()

Returns a Locator to the first matching element.

Returns

Type	Description
Locator	The first element `Locator` associated with the selector.

Example

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';
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.goto('https://quickpizza.grafana.com');

  await expect(await page.locator('p').first()).toContainText('QuickPizza');

  await page.close();
}

focus([options])

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

focus([options])

Calls focus on the element, if it can be focused on.

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.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the focus 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 textbox = page.locator('#text1');
  await textbox.focus();
}

frameLocator(selector)

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

frameLocator(selector)

Shorthand for locator(selector).contentFrame(). Returns a FrameLocator for the iframe that matches the given selector. Use this to interact with elements inside iframes without calling locator() and contentFrame() separately.

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 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(`
      <div class="widget"><iframe id="my_frame" src="https://quickpizza.grafana.com"></iframe></div>
    `);

    // Shorthand: instead of page.locator('.widget').locator('#my_frame').contentFrame()
    const frame = page.locator('.widget').frameLocator('#my_frame');
    await frame.getByText('Pizza, Please!').click();
  } finally {
    await page.close();
  }
}

getAttribute(name, [options])

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

getAttribute(name, [options])

Returns the element attribute value for the given attribute name.

Parameter	Type	Default	Description
name	string	`''`	Attribute name to get the value for.
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.

Returns

Type	Description
`Promise<string	null>`

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 textbox = page.locator('#text1');
  const attribute = await textbox.getAttribute('onfocus');
  console.log(attribute);
}

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.locator(':root').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.locator(':root').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.locator(':root').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.

locator.getByRole() - Locate by ARIA role
locator.getByLabel() - Locate by form labels
locator.getByPlaceholder() - Locate by placeholder text
locator.getByTestId() - Locate by test ID
locator.getByTitle() - Locate by title attribute
locator.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 locator = page.locator(':root');
    const username = locator.getByLabel('Username (hint: default)', { exact: true });
    const password = locator.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 locator = page.locator(':root');

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

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

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

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

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

locator.getByRole() - Locate by ARIA role
locator.getByAltText() - Locate by alt text
locator.getByPlaceholder() - Locate by placeholder text
locator.getByTestId() - Locate by test ID
locator.getByTitle() - Locate by title attribute
locator.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 locator = page.locator(':root');
    await locator.getByPlaceholder('First name').fill('First');
    await locator.getByPlaceholder('Last name').fill('Last');
    await locator.getByPlaceholder('dd/mm/yyyy').fill('01/01/1990');

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

locator.getByRole() - Locate by ARIA role
locator.getByAltText() - Locate by alt text
locator.getByLabel() - Locate by form labels (preferred for accessibility)
locator.getByTestId() - Locate by test ID
locator.getByTitle() - Locate by title attribute
locator.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 locator = page.locator(':root');
    await locator.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.

locator.getByAltText() - Locate by alt text
locator.getByLabel() - Locate by form labels
locator.getByPlaceholder() - Locate by placeholder text
locator.getByTestId() - Locate by test ID
locator.getByText() - Locate by text content
locator.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 locator = page.locator(':root');
    await locator.getByTestId('username').fill('FirstLast');
    await locator.getByTestId('email').fill('firstlast@example.com');
    await locator.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.

locator.getByRole() - Locate by ARIA role
locator.getByAltText() - Locate by alt text
locator.getByLabel() - Locate by form labels
locator.getByPlaceholder() - Locate by placeholder text
locator.getByText() - Locate by text content
locator.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 locator = page.locator(':root');
    await locator.getByText('Pizza, Please!').click();

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

locator.getByRole() - Locate by ARIA role
locator.getByAltText() - Locate by alt text
locator.getByLabel() - Locate by form labels
locator.getByPlaceholder() - Locate by placeholder text
locator.getByTestId() - Locate by test ID
locator.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 locator = page.locator(':root');

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

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

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

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

hover([options])

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

hover([options])

Caution
This feature has known issues. For details, refer to #471.

Hovers over the element.

Parameter	Type	Default	Description
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.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.

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 offScreenElement = page.locator('#off-screen');
  await offScreenElement.hover();
}

innerHTML([options])

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

innerHTML([options])

Returns the element.innerHTML.

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.

Returns

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

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 offScreen = page.locator('#off-screen');
  console.log(await offScreen.innerHTML());
}

innerText([options])

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

innerText([options])

Returns the element.innerText.

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.

Returns

Type	Description
`Promise<string>`	A Promise that fulfills with the inner text of the element.

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 offScreen = page.locator('#off-screen');
  console.log(await offScreen.innerText()); // Off page div
}

inputValue([options])

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

inputValue([options])

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

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.

Returns

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

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 textInput = page.locator('#text1');
  await textInput.fill('Hello world!');
  console.log(await textInput.inputValue());
}

isChecked([options])

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

isChecked([options])

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

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.

Returns

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

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 checkbox = page.locator('#checkbox1');
  const isChecked = await checkbox.isChecked();
  if (!isChecked) {
    await checkbox.check();
  }
}

isDisabled([options])

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

isDisabled([options])

Checks if the element is disabled.

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.

Returns

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

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 text = page.locator('#input-text-disabled');
  const isDisabled = await text.isDisabled();
  if (isDisabled) {
    console.log('element is disabled');
  }
}

isEditable([options])

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

isEditable([options])

Checks if the element is editable.

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.

Returns

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

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 text = page.locator('#text1');
  const isEditable = await text.isEditable();
  if (isEditable) {
    text.fill('hello world!');
  }
}

isEnabled([options])

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

isEnabled([options])

Checks if the element is enabled.

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.

Returns

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

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 text = page.locator('#text1');
  const isEnabled = await text.isEnabled();
  if (isEnabled) {
    console.log('element is enabled');
  }
}

isHidden()

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

isHidden()

Checks if the element is hidden.

Returns

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

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 text = page.locator('#input-text-hidden');
  const isHidden = await text.isHidden();
  if (isHidden) {  
    console.log('element is hidden');
  }
}

isInViewport([options])

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

isInViewport([options])

Checks whether the element intersects the browser viewport. This matches Playwright’s toBeInViewport semantics.

Parameter	Type	Default	Description
options	object	`null`
options.ratio	number	`0`	The minimum ratio of the element that must be within the viewport for it to count as in viewport, from `0` to `1`. The default of `0` means any visible pixel counts.
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 fulfills with `true` if the element is in the viewport, else `false`.

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/');
  const button = page.locator('button#submit');
  if (await button.isInViewport()) {
    await button.click();
  }
}

isVisible()

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

isVisible()

Checks if the element is visible.

Returns

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

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 text = page.locator('#text1');
  const isVisible = await text.isVisible();
  if (isVisible) {
    console.log('element is visible');
  }
}

last()

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

last()

Returns a Locator to the last matching element.

Returns

Type	Description
Locator	The last element `Locator` associated with the selector.

Example

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';
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.goto('https://quickpizza.grafana.com');

  await expect(await page.locator('p').last()).toContainText('Contribute to QuickPizza');

  await page.close();
}

locator(selector[, options])

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

locator(selector[, options])

The method finds all elements matching the selector and creates a new Locator that matches all of them. This method can be used to further refine the locator by chaining additional selectors.

This allows you to define locators relative to a parent locator, enabling more precise element targeting by creating nested locators.

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	A new chained `Locator` that can be used for further actions.

Example

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';
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(`
      <div>
        <div data-testid="products">
          <div data-category="fruits">
            <div data-product="apple">
              <h3>Apple</h3>
              <button>Add to Cart</button>
              <button>View Details</button>
            </div>
          </div>
          <div data-category="fruits">
            <h3>Orange</h3>
            <button>Add to Cart</button>
            <button>View Details</button>
          </div>
          <div data-category="vegetables">
            <h3>Carrot</h3>
            <button>Add to Cart</button>
            <button>View Details</button>
          </div>
        </div>
      </div>
    `);

    // Use locator.locator to find specific products within the list
    const appleProduct = page.locator('div[data-product="apple"]');
    const addToCartButton = appleProduct.locator('//button[text()="Add to Cart"]');

    // Use locator.locator with options to find specific items
    const fruitsSection = page.locator('div[data-category="fruits"]');
    const orangeButton = fruitsSection.locator('button', { hasText: 'Add to Cart' });

    // Interact with the nested locators
    await addToCartButton.click();
    await orangeButton.click();
  } finally {
    await page.close();
  }
}

nth(number)

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

nth(number)

Returns a Locator to the n-th matching element. The method is zero-based; for example, nth(0) selects the first element.

Returns

Type	Description
Locator	The n-th element `Locator` associated with the selector.

Example

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';
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.goto('https://quickpizza.grafana.com');

  await expect(await page.locator('p').nth(4)).toContainText('QuickPizza Labs.');

  await page.close();
}

press(key, [options])

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

press(key, [options])

Press a single key on the keyboard or a combination of keys.

Parameter	Type	Default	Description
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.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 key is pressed.

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 text = page.locator('#text1');
  await text.press('i');
  await text.press('ArrowLeft');
  await text.press('h');
}

pressSequentially() - Type text character by character with keyboard events
type() - Type text into an input field
fill() - Fill text instantly without keyboard events

pressSequentially(text, [options])

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

pressSequentially(text, [options])

Focuses the element and then sends a keydown, keypress/input, and keyup event for each character in the text.

This method is useful for simulating real user typing behavior when the page has special keyboard event handling, such as input validation, autocomplete, or character counters that trigger on individual key presses. For simple text input without special keyboard handling, use fill() instead, as it’s faster and more reliable.

Parameter	Type	Default	Description
text	string	`''`	Text to type into the focused element character by character.
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.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 into the element.

Examples

Basic usage

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://test.k6.io/browser.php');

    // Type text character by character
    const textInput = page.locator('#text1');
    await textInput.pressSequentially('Hello World');
  } finally {
    await page.close();
  }
}

Typing with delay

This example demonstrates typing text with a delay between keystrokes to simulate realistic user typing speed:

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://test.k6.io/browser.php');

    // Type text with 100ms delay between each character
    const searchInput = page.locator('input[type="text"]');
    await searchInput.pressSequentially('test query', { delay: 100 });
  } finally {
    await page.close();
  }
}

Best practices

Use fill() for simple text input: For form fields without special keyboard handling, use fill() instead as it’s significantly faster and more reliable.
Use pressSequentially() for interactive input: Only use pressSequentially() when testing features that require gradual typing, such as:
- Autocomplete suggestions
- Input validation that triggers per character
- Character counters
- Search-as-you-type functionality
Consider performance: Typing character-by-character is slower than filling text directly. Use this method only when necessary for accurate testing.
Handling special keys: For special keys like Enter, Tab, or Escape, use press() instead.

fill() - Fill text instantly without keyboard events
press() - Press special keys or key combinations
type() - Type text into an input field

selectOption(values, [options])

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

selectOption(values, [options])

Select one or more options which match the values.

Parameter	Type	Default	Description
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. String values are matching both values and labels. 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.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<Array<string>>`	A Promise that fulfills with the selected options as an array of strings.

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 options = page.locator('#numbers-options');
  await options.selectOption('three');
}

setChecked(checked[, options])

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

setChecked(checked[, options])

Use this method to select or 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.

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 checkbox = await page.locator('#checkbox1');
  await checkbox.setChecked(true);
  await checkbox.setChecked(false);

  await page.close();
}

tap([options])

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

tap([options])

Caution
This feature has known issues. For details, refer to #436 and #471.

Tap on the chosen element.

Parameter	Type	Default	Description
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.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 default async function () {
  const page = await browser.newPage({
    hasTouch: true,
  });

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

textContent([options])

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

textContent([options])

Returns the element.textContent.

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.

Returns

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

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 options = page.locator('#checkbox1');
  console.log(await options.textContent());
}

type(text, [options])

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

type(text, [options])

Type in the text into the input field.

Parameter	Type	Default	Description
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.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 type 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 text = page.locator('#text1');
  await text.type('hello world!');
}

pressSequentially() - Type text character by character with keyboard events
press() - Press special keys or key combinations
fill() - Fill text instantly without keyboard events

uncheck([options])

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

uncheck([options])

Caution
This feature has known issues. For details, refer to #471.

Unselect the input checkbox.

Parameter	Type	Default	Description
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.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 uncheck 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 checkbox = page.locator('#checkbox1');
  await checkbox.check();
  await checkbox.uncheck();
}

waitFor([options])

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

waitFor([options])

Wait for the element to be in a particular state e.g. visible.

Parameter	Type	Default	Description
options	object	`null`
options.state	string	`visible`	Can be `attached`, `detached`, `visible` or `hidden`.
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 once the element is in the desired state.

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 text = page.locator('#input-text-hidden');
  await text.waitFor({
    state: 'hidden',
  });
}

Locator on Grafana Labs

all()

all()

Returns

Example

boundingBox([options])

boundingBox([options])

Returns

Rect

Example

check([options])

check([options])

Returns

Example

clear([options])

clear([options])

Returns

Example

click([options])

click([options])

Returns

Examples

contentFrame()

contentFrame()

Returns

Example

count()

count()

Returns

Example

dblclick([options])

dblclick([options])

Returns

Example

dispatchEvent(type, eventInit, [options])

dispatchEvent(type, eventInit, [options])

eventInit

Returns

Example

evaluate(pageFunction[, arg])

evaluate(pageFunction[, arg])

Returns

Example

evaluateHandle(pageFunction[, arg])

evaluateHandle(pageFunction[, arg])

Returns

Example

fill(value, [options])

fill(value, [options])

Returns

Example

Related

filter(options)

filter(options)

Returns

Example

first()

first()

Returns

Example

focus([options])

focus([options])

Returns

Example

frameLocator(selector)

frameLocator(selector)

Returns

Example

getAttribute(name, [options])

getAttribute(name, [options])

Returns

Example

getByAltText(altText[, options])

getByAltText(altText[, options])

Returns

Examples

Basic alt text matching

Exact alt text matching

Using regular expressions

Common use cases