ElementHandle on Grafana Labs

$(selector)

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

$(selector)

Warning
Use page.locator(selector[, options]) instead.

Queries the element for the given selector in the ElementHandle’s subtree.

Parameter	Type	Default	Description
selector	`string`		A selector to query the elements for.

Returns

Type	Description
`Promise<null \| ElementHandle>`	A Promise that fulfills with the ElementHandle for the first element found. If no element is found, the Promise resolves to `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 = await page.$('#text1');
  // ...
  await page.close();
}

$$(selector)

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

$$(selector)

Queries the elements for the given selector in the ElementHandle’s subtree. The results are returned in DOM order.

Parameter	Type	Default	Description
selector	`string`		A selector to query the elements for.

Returns

Type	Description
`Promise<null \| ElementHandle[]>`	A Promise that fulfills with an ElementHandle array for the elements found. If no element is found, the Promise resolves to `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 elements = await page.$$('#text1');
  for (const element of elements) {
    // ...
  }

  await page.close();
}

boundingBox()

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

boundingBox()

Warning
Use locator.boundingBox([options]) instead.

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

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 element = await page.$('#text1');
  const boundingBox = await element.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])

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

Use this method to select an input 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.$('#checkbox1');
  await checkbox.check();

  await page.close();
}

click([options])

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

click([options])

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

Mouse click on the chosen element.

Parameter	Type	Default	Description
options	object	`null`	Optional parameters.
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 = await page.$('#counter-button');
  await button.click();

  await page.close();
}

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

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

  await page.close();
}

contentFrame()

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

contentFrame()

Returns the Frame that this element is contained in.

Returns

Type	Description
`Promise<Frame \| null>`	A Promise that resolves to the Frame that this element is contained in

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 element = await page.$('#text1');
  const frame = await element.contentFrame();
  console.log(frame.url());

  await page.close();
}

dblclick([options])

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

dblclick([options])

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

Mouse double clicks on the element.

Parameter	Type	Default	Description
options	object	`null`	Optional parameters.
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 doesn’t 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. Passing `0` disables the timeout. The `setDefaultTimeout` option on BrowserContext or Page can override the default timeout.
options.trial	boolean	`false`	Performs the actionability checks without performing the double click action if set to `true`.

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

  await page.close();
}

dispatchEvent(type, eventInit)

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

dispatchEvent(type, eventInit)

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

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 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 = await page.$('#counter-button');
  await button.dispatchEvent('click');

  await page.close();
}

fill(value, [options])

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

fill(value, [options])

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

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 = await page.$('#text1');
  await textbox.fill('hello world!');

  await page.close();
}

focus()

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

focus()

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

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

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 = await page.$('#text1');
  await textbox.focus();

  await page.close();
}

getAttribute(name)

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

getAttribute(name)

Warning
Use locator.getAttribute(name[, options]) instead.

Returns the element attribute value for the given attribute name.

Parameter	Type	Default	Description
name	string	`''`	Attribute name to get the value for.

Returns

Type	Description
`Promise<string \| null>`	A Promise that fulfills with the string value of the attribute or `null` if the attribute is not present.

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

  await page.close();
}

hover([options])

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

hover([options])

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

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

  await page.close();
}

innerHTML()

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

innerHTML()

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

Returns the element.innerHTML.

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

  await page.close();
}

innerText()

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

innerText()

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

Returns the element’s inner text.

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

  await page.close();
}

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

  await page.close();
}

isChecked()

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

isChecked()

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

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

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

  await page.close();
}

isDisabled()

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

isDisabled()

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

Checks if the element is disabled.

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

  await page.close();
}

isEditable()

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

isEditable()

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

Checks if the element is editable.

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

  await page.close();
}

isEnabled()

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

isEnabled()

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

Checks if the element is enabled.

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

  await page.close();
}

isHidden()

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

isHidden()

Warning
Use locator.isHidden() instead.

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

  await page.close();
}

isVisible()

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

isVisible()

Warning
Use locator.isVisible() instead.

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

  await page.close();
}

ownerFrame

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

ownerFrame

Returns the Frame of the element.

Returns

Type	Description
`Promise<Frame \| null>`	A Promise that fulfills with the Frame of the element, or `null` if the element is not attached to a frame.

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 element = await page.$('#text1');
  const frame = await element.ownerFrame();
  console.log(frame.url());

  await page.close();
}

press(key, [options])

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

press(key, [options])

Warning
Use locator.press(key[, options]) instead.

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

  await page.close();
}

screenshot([options])

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

screenshot([options])

Takes a screenshot of the element.

Parameter	Type	Default	Description
options	object	`null`
options.path	string	`''`	The file path to save the image to. The screenshot type will be inferred from file extension. If `path` is a relative path, then it is resolved relative to the current working directory. If no path is provided, the image won’t be saved to the disk.
options.format	string	`png`	Specify screenshot type. Acceptable values are `jpeg` and `png`.
options.omitBackground	boolean	`false`	Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images.
options.quality	number	`100`	The quality of the image, between 0-100; Only applicable to `jpeg` only.
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<ArrayBuffer \| null>`	The ArrayBuffer with the captured screenshot.

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 element = await page.$(".header");
  const screenshot = await element.screenshot({
    path: 'header.png'
  });

  await page.close();
}

scrollIntoViewIfNeeded([options])

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

scrollIntoViewIfNeeded([options])

Scrolls the element into view if needed.

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 resolves when the element is scrolled into view.

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 element = await page.$(".header");
  await element.scrollIntoViewIfNeeded();

  await page.close();
}

selectOption(values, [options])

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

selectOption(values, [options])

Warning
Use locator.selectOption(values[, options]) instead.

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

  await page.close();
}

selectText(values, [options])

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

selectText(values, [options])

Selects the text of 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.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 is selected.

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 element = await page.$('h1');
  await element.selectText();

  await page.close();
}

setChecked(checked[, options])

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

setChecked(checked[, options])

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

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, the script won’t 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.$('#checkbox1');
  await checkbox.setChecked(true);
  await checkbox.setChecked(false);

  await page.close();
}

setInputFiles(file[, options])

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

setInputFiles(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
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.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the file is set.

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 eh = await page.$('input[id="upload"]');

    // The file is set to the input element with the id "upload".
    await eh.setInputFiles({
      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 eh = await page.$('input[id="upload"]');

    // 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".
    await eh.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(options)

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

tap(options)

Warning
Use locator.tap([options]) instead.

Taps 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.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 el = await page.$("#numbers-options");
  await el.tap();
}

textContent()

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

textContent()

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

Returns the element’s text content.

Returns

Type	Description
`Promise<string \| null>`	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 = await page.$('#checkbox1');
  console.log(await options.textContent());

  await page.close();
}

type(text, [options])

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

type(text, [options])

Warning
Use locator.type([options]) instead.

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 = await page.$('#text1');
  await text.type('hello world!');

  await page.close();
}

uncheck([options])

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

uncheck([options])

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

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

  await page.close();
}

waitForElementState(state[, options])

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

waitForElementState(state[, options])

Waits for the element to reach the specified state.

Parameter	Type	Default	Description
state	string		The state to wait for. This can be one of `visible`, `hidden`, `stable`, `enabled`, `disabled`, or `editable`.
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 reaches the specified state or the timeout is reached.

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 element = await page.$('#text1');
  await element.waitForElementState('visible');

  await page.close();
}

waitForSelector(selector[, options])

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

waitForSelector(selector[, options])

Warning
Use locator.waitFor([options]) instead.

Waits for the element to be present in the DOM and to be visible.

Parameter	Type	Default	Description
selector	string		A selector to query the element.
options	object	`null`	Optional settings.
options.state	string	`visible`	The state to wait for. This can be one of `visible`, `hidden`, `stable`, `enabled`, `disabled`, or `editable`.
options.strict	boolean	`false`	If set to `true`, the method will throw an error if the element is not found.
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<ElementHandle \| null>`	A Promise that fulfills with the ElementHandle when the element is found.

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 element = await page.$(".header");
  const el = await element.waitForSelector(".title");
  // ... do something with the element

  await page.close();
}