Page on Grafana Labs

$(selector)

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

page.$(selector)

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

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

Returns

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

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').then((text) => text.type('hello world'));
}

$$(selector)

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

page.$$(selector)

Warning
When possible, use locator-based page.locator(selector) instead.

However, using locators may not always work when selecting an element from a list or table, especially if there isn’t a reliable way to consistently identify a single element (for example, due to changing or non-unique attributes). In such cases, $$ remains useful.

The method finds all elements matching the specified selector within the page. If no elements match the selector, the return value resolves to []. The results are returned in DOM order. This is particularly useful when you want to retrieve a list of elements, and iterate through them to find the one that you need for your test case.

Returns

Type	Description
`Promise<ElementHandle[]>`	A Promise that fulfills with the ElementHandle array of the selector when matching elements are 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/');

  // Retrieve all the td elements.
  const cells = await page.$$('td');
  for (let i = 0; i < cells.length; i++) {
    if ((await cells[i].innerText()) == '/pi.php?decimals=3') {
      // When the element is found, click on it and
      // wait for the navigation.
      await Promise.all([page.waitForNavigation(), cells[i].click()]);
      break;
    }
  }

  // Wait for an important element to load.
  await page.locator('//pre[text()="3.141"]').waitFor();
}

bringToFront()

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

bringToFront()

Activates the browser tab which brings the page in focus to allow actions to be performed onto it.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the page is brought to the front.

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

  // perform other actions that might open up a different tab, taking focus away from the initial page.

  await page.bringToFront();
}

check(selector[, options])

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

check(selector[, options])

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

This method is used to select an input checkbox.

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

Returns

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

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

click(selector[, options])

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

click(selector[, options])

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

This method clicks on an element matching a selector.

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

Returns

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

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

When a click action results in a page navigation, remember to work with 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/');

  await Promise.all([page.waitForNavigation(), page.click('a[href="/my_messages.php"]')]);
}

close()

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

close()

This will close the tab that this page is associated with.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the page is closed.

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');
  await page.close();
}

content()

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

content()

Gets the HTML contents of the page.

Returns

Type	Description
`Promise<string \| null>`	A Promise that fulfills with the HTML content of the page as a string value 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');
  console.log(await page.content()); // HTML content printed in the console
}

context()

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

context()

Gets the BrowserContext that the page belongs to.

Returns

Type	Description
BrowserContext	The `BrowserContext` that the page belongs to.

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');
  console.log(page.context()); // prints {"base_event_emitter":{}}
}

dblclick(selector[, options])

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

dblclick(selector[, options])

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

Mouse double clicks an element matching provided selector.

Parameter	Type	Default	Description
selector	string	`''`	A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used.
options	object	`null`
options.button	string	`left`	The mouse button (`left`, `middle` or `right`) to use during the action.
options.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.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.
options.timeout	number	`30000`	Maximum time in milliseconds. Pass `0` to disable the timeout. Default is overridden by the `setDefaultTimeout` option on BrowserContext or Page.
options.trial	boolean	`false`	Setting this to `true` will perform the actionability checks without performing the action.

Returns

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

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

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

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

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

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

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

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

eventInit

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

Returns

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

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

emulateMedia([options])

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

emulateMedia([options])

This method changes the CSS @media type through the media argument, and/or the 'prefers-colors-scheme' media feature, using the colorScheme argument.

Parameter	Type	Default	Description
options	object	`null`
options.colorScheme	string	`''`	Emulates `'prefers-colors-scheme'` media feature, supported values are `'light'`, `'dark'`, and `'no-preference'`.
options.media	string	`''`	Changes the CSS media type of the page. The only allowed values are `'screen'`, and `'print'`.
options.reducedMotion	string	`''`	Emulates `'prefers-reduced-motion'` media feature, supported values are `'reduce'`, `'no-preference'`.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the media is emulated.

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');
  console.log(await page.evaluate(() => matchMedia('screen').matches)); // true
}

emulateVisionDeficiency(type)

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

emulateVisionDeficiency(type)

This emulates your website with the specified vision deficiency type.

The supported types are:

none: default.
blurredVision: where vision is less precise.
protanopia: the inability to perceive any red light.
deuteranopia: the inability to perceive any green light.
tritanopia: the inability to perceive any blue light.
achromatopsia: the inability to perceive any color except for shades of grey (extremely rare).

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the vision deficiency is emulated.

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');
  await page.emulateVisionDeficiency('blurredVision');
}

evaluate(pageFunction[, arg])

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

evaluate(pageFunction[, arg])

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

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

Returns

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

Example

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

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 dimensions = await page.evaluate(() => {
    const obj = {
      width: document.documentElement.clientWidth,
      height: document.documentElement.clientHeight,
      deviceScaleFactor: window.devicePixelRatio,
    };
    return obj;
  });

  check(dimensions, {
    width: (d) => d.width === 1280,
    height: (d) => d.height === 720,
    scale: (d) => d.deviceScaleFactor === 1,
  });
}

evaluateHandle(pageFunction[, arg])

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

evaluateHandle(pageFunction[, arg])

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

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

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

Returns

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

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 resultHandle = await page.evaluateHandle(() => document.body);
  console.log(resultHandle.jsonValue());
}

fill(selector, value[, options])

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

fill(selector, value[, options])

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

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

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

Returns

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

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

focus(selector[, options])

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

focus(selector[, options])

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

This method fetches an element with selector and focuses it.

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

Returns

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

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

frameLocator(selector)

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

frameLocator(selector)

Returns a FrameLocator for the iframe that matches the given selector. Use this to interact with elements inside iframes without first resolving the iframe element or calling locator.contentFrame().

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

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

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

frames()

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

frames()

Returns an array of Frames on the page.

Returns

Type	Description
Frames[]	An array of `Frames` associated with the page.

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');
  console.log(page.frames());
}

getAttribute(selector, name[, options])

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

getAttribute(selector, name[, options])

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

Returns the element attribute value for the given attribute name.

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

Returns

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

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 attribute = await page.getAttribute('#text1', 'onfocus');
  console.log(attribute); // prints inputTextOnFocus();
}

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

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

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

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

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

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

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

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

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

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

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

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

page.getByAltText() - Locate by alt text
page.getByLabel() - Locate by form labels
page.getByPlaceholder() - Locate by placeholder text
page.getByTestId() - Locate by test ID
page.getByText() - Locate by text content
page.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>
    `);

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

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

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

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

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

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

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

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

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

goBack([options])

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

goBack([options])

Returns the main resource response for the navigation, or null if the navigation is impossible (e.g., when already at the beginning of the session history).

Navigates back in the browser’s session history. This method is safer than using page.evaluate(() => window.history.back()) which can cause race conditions.

Parameter	Type	Default	Description
options	object	`null`
options.timeout	number	`30000`	Maximum operation time in milliseconds. Pass `0` to disable the timeout. The default value can be changed via the methods listed below. Setting the value to `0` will disable the timeout.
options.waitUntil	string	`load`	When to consider operation to have succeeded. See Events for more details.

Methods to Change Default Values

You can change the default value using one of the following methods:

Events

Caution
Avoid using networkidle for testing. This event might never fire on websites with high network activity. Instead, use web assertions to assess when the page is ready

You can set the event to one of the following:

'domcontentloaded' : The DOMContentLoaded event fires.
'load' : The load event fires.
'networkidle' : There are no network connections for at least 500 ms.

Returns

Type	Description
`Promise<Response \| null`	A Promise that fulfills with the Response> instance associated with the page, else `null` if navigation is not possible.

Example

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

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

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

  try {
    // Navigate to first page
    await page.goto('https://test.k6.io/browser.php');
    const url1 = await page.url();
    
    // Navigate to second page
    await page.goto('https://test.k6.io/my_messages.php');
    const url2 = await page.url();
    
    // Go back to first page
    const response = await page.goBack();
    
    // Verify we're back on the first page
    const currentUrl = await page.url();
    check(currentUrl, {
      'went back to first page': (url) => url.includes('browser.php'),
    });
    
    // Verify the response is not null (since navigation was possible)
    check(response, {
      'response is not null': (resp) => resp !== null,
    });
    
    // Attempt to go back again (should return null since we're at the beginning of history)
    const nullResponse = await page.goBack();
    check(nullResponse, {
      'goBack at boundary returns null': (resp) => resp === null,
    });
  } finally {
    await page.close();
  }
}

page.goForward() - Navigate forward in browser history
page.goto() - Navigate to a specific URL
page.reload() - Reload the current page

goForward([options])

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

goForward([options])

Returns the main resource response for the navigation, or null if the navigation is impossible (e.g., when already at the end of the session history).

Navigates forward in the browser session history. This method is safer than page.evaluate(() => window.history.forward()), which can cause race conditions if the page is mid-navigation.

Parameter	Type	Default	Description
options	object	`null`
options.timeout	number	`30000`	Maximum operation time in milliseconds. Pass `0` to disable the timeout. The default value can be changed via the methods listed below. Setting the value to `0` will disable the timeout.
options.waitUntil	string	`load`	When to consider operation to have succeeded. See Events for more details.

Methods to Change Default Values

You can change the default value using one of the following methods:

Events

Caution
Avoid using networkidle for testing. This event might never fire on websites with high network activity. Instead, use web assertions to assess when the page is ready.

You can set the event to one of the following:

'domcontentloaded': The DOMContentLoaded event fires.
'load': The load event fires.
'networkidle': There are no network connections for at least 500 ms.

Returns

Type	Description
`Promise<Response \| null`	A Promise that fulfills with the Response> instance associated with the page, else `null` if navigation is not possible.

Example

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

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

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

  try {
    // Navigate to first page
    await page.goto('https://test.k6.io/browser.php');
    const url1 = await page.url();
    
    // Navigate to second page
    await page.goto('https://test.k6.io/my_messages.php');
    const url2 = await page.url();
    
    // Go back to first page
    await page.goBack();
    
    // Go forward to second page
    const response = await page.goForward();
    
    // Verify we're back on the second page
    const currentUrl = await page.url();
    check(currentUrl, {
      'went forward to second page': (url) => url.includes('my_messages.php'),
    });
    
    // Verify the response is not null (since navigation was possible)
    check(response, {
      'response is not null': (resp) => resp !== null,
    });
    
    // Attempt to go forward again (should return null since we're at the end of history)
    const nullResponse = await page.goForward();
    check(nullResponse, {
      'goForward at boundary returns null': (resp) => resp === null,
    });
  } finally {
    await page.close();
  }
}

page.goBack() - Navigate back in browser history
page.goto() - Navigate to a specific URL
page.reload() - Reload the current page

goto(url[, options])

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

goto(url[, options])

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

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

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

Events

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

Events can be either:

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

Returns

Type	Description
`<Promise<Response \| null>`	The Response> instance associated with the page. Else, it returns `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');
  await page.close();
}

hover(selector[, options])

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

hover(selector[, options])

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

This method hovers over an element matching selector.

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

Returns

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

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

innerHTML(selector[, options])

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

innerHTML(selector[, options])

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

Returns the element.innerHTML.

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

Returns

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

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

innerText(selector[, options])

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

innerText(selector[, options])

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

Returns the element.innerText.

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

Returns

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

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

inputValue(selector[, options])

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

inputValue(selector[, options])

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

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

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

Returns

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

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

isChecked(selector[, options])

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

isChecked(selector[, options])

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

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

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

Returns

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

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

isClosed()

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

isClosed()

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

Checks if the page has been closed.

Returns

Type	Description
`Promise<bool>`	A Promise that fullfils with `true` if the page has been closed, 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');
  await page.close();

  console.log(await page.isClosed());
}

isDisabled(selector[, options])

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

isDisabled(selector[, options])

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

Checks if the element is disabled.

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

Returns

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

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

isEditable(selector[, options])

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

isEditable(selector[, options])

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

Checks if the element is editable.

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

Returns

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

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

isEnabled(selector[, options])

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

isEnabled(selector[, options])

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

Checks if the element is enabled.

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

Returns

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

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

isHidden(selector[, options])

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

isHidden(selector[, options])

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

Checks if the element is hidden.

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

Returns

Type	Description
`Promise<bool>`	A Promise that fullfils 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 isHidden = await page.isHidden('#input-text-hidden');
  if (isHidden) {
    console.log('element is hidden');
  }
}

isVisible(selector[, options])

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

isVisible(selector[, options])

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

Checks if the element is visible.

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

Returns

Type	Description
`Promise<bool>`	A Promise that fullfils 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 isVisible = await page.isVisible('#text1');
  if (isVisible) {
    console.log('element is visible');
  }
}

keyboard

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

keyboard

Returns the Keyboard instance to interact with a virtual keyboard on the page.

Returns

Type	Description
Keyboard	The `Keyboard` instance associated with the page.

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');
  await page.keyboard.press('Tab');
}

locator(selector[, options])

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

locator(selector[, options])

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

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

Returns

Type	Description
Locator	The element `Locator` associated with the page.

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');
  
    // Create a locator with text filtering options
    const submitButton = page.locator('button', { hasText: 'Pizza, Please!' });
    await submitButton.click();
  } finally {
    await page.close();
  }
}

mainFrame()

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

mainFrame()

The page’s main frame. Page is made up of frames in a hierarchical. At the top is mainFrame. A page is guaranteed to have a main frame.

Returns

Type	Description
Frame	The page’s main 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');
  console.log(page.mainFrame());
}

mouse

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

mouse

Returns the Mouse instance to interact with a virtual mouse on the page.

Returns

Type	Description
Mouse	The `Mouse` instance associated with the page.

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');
  await page.mouse.down();
}
```ß

on(event, handler)

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

on(event, handler)

Registers a handler to be called whenever the specified event occurs. This method can also be used to prevent the too many time series error when using the k6 browser module. For more details, refer to Prevent too many time series error.

Parameter	Type	Default	Description
event	string	`''`	Event to attach the handler to. See the supported events.
handler	function	`null`	A function to be called every time the specified event is emitted.

Events

Event	Description
`console`	Emitted every time the console API methods are called from within the page JavaScript context. The arguments passed into the handler are defined by the `ConsoleMessage` class. See the example.
`metric`	Emitted every time a metric is measured and emitted for the page. The arguments passed into the handler are defined by the `MetricMessage` object. See the example.
`request`	Emitted every time a request made by the page. The handler gets a `Request` object that contains information about the request. See the example.
`requestfinished`	Emitted when a network request successfully completes (receives a response). The handler gets a `Request` object that contains information about the completed request. See page.on(“requestfinished”).
`requestfailed`	Emitted when a network request fails to reach the server (DNS errors, connection refused, timeouts, etc.). The handler gets a `Request` object that contains information about the failed request. See page.on(“requestfailed”).
`response`	Emitted every time a response is received by the page. The handler gets a `Response` object that contains information about the response. See the example.

Console event example

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

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

    page.on('console', (msg) => {
      check(msg, {
        assertConsoleMessageType: (msg) => msg.type() == 'log',
        assertConsoleMessageText: (msg) => msg.text() == 'this is a console.log message 42',
        assertConsoleMessageArgs0: (msg) =>
          msg.args()[0].jsonValue() == 'this is a console.log message',
        assertConsoleMessageArgs1: (msg) => msg.args()[1].jsonValue() == 42,
      });
    });

    await page.evaluate(() => console.log('this is a console.log message', 42));
  } finally {
    await page.close(); // required so iteration can end
  }
}

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

  // We first register a handler using page.on('metric'). Calling page.on('metric')
  // multiple times is allowed. The registered handlers will be executed in the
  // order page.on was called.
  page.on('metric', (metric) => {
    // Using metric.tag finds a match between the current metric url and name
    // tags against the supplied regular expression in `url`.
    //
    // At the moment metric.tag is the only method on the metricMessage object.
    metric.tag({
      // This is the new name value that will replace the existing value in the
      // url and name tags when a match is found.
      name: 'test',
      // You can provide multiple matches here.
      matches: [
        {
          url: /^https:\/\/test\.k6\.io\/\?q=[0-9a-z]+$/,
          // When a method is defined it will also need to match on that too. If a
          // method is not provided it will match on all method types.
          method: 'GET',
        },
      ],
    });
  });

  try {
    // This is only for illustrative purposes, the q query param doesn't affect
    // the website.
    await page.goto('https://test.k6.io/?q=abc123');
    await page.goto('https://test.k6.io/?q=def456');
  } finally {
    await page.close();
  }
}

Request and response events 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();

  // registers a handler that logs all requests made by the page
  page.on('request', async (request) => console.log(request.url()));
  // registers a handler that logs all responses received by the page
  page.on('response', async (response) => console.log(response.url()));

  await page.goto('https://quickpizza.grafana.com/', { waitUntil: 'networkidle' });
  await page.close();
}

Output:

INFO[0000] https://quickpizza.grafana.com/                  source=console
INFO[0001] https://quickpizza.grafana.com/api/tools         source=console
INFO[0001] https://quickpizza.grafana.com/images/pizza.png  source=console
...

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

  // Track all completed requests
  const finishedRequests = [];

  page.on('requestfinished', (request) => {
    finishedRequests.push({
      url: request.url(),
      method: request.method(),
      resourceType: request.resourceType(),
    });

    console.log(`✓ Request finished: ${request.method()} ${request.url()}`);
  });

  await page.goto('https://quickpizza.grafana.com/', { waitUntil: 'networkidle' });

  console.log(`Total requests completed: ${finishedRequests.length}`);

  // Log all API requests
  const apiRequests = finishedRequests.filter(r => r.url.includes('/api/'));
  console.log(`API requests: ${apiRequests.length}`);

  await page.close();
}

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

  // Track all failed requests
  const failedRequests = [];

  page.on('requestfailed', (request) => {
    const failure = request.failure();
    failedRequests.push({
      url: request.url(),
      method: request.method(),
      error: failure ? failure.errorText : 'unknown error',
    });

    console.log(`✗ Request failed: ${request.method()} ${request.url()}`);
    if (failure) {
      console.log(`  Error: ${failure.errorText}`);
    }
  });

  try {
    // This will trigger a requestfailed event due to DNS failure
    await page.goto('https://does-not-exist.invalid/');
  } catch (e) {
    // Navigation error expected
  }

  console.log(`Total failed requests: ${failedRequests.length}`);

  await page.close();
}

page.waitForEvent() - Wait for page events with predicate functions
page.waitForRequest() - Wait for HTTP requests with URL pattern matching
page.waitForResponse() - Wait for HTTP responses with URL pattern matching

opener()

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

opener()

Returns the page that opened the current page. The first page that is navigated to will have a null opener.

Returns

Type	Description
null or Page	The `Page` instance. Else, it returns `null`.

Returns

Type	Description
`Promise<Page \| null>`	A Promise that fullfils with the `Page` instance, else `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');
  console.log(await page.opener());
}

press(selector, key[, options])

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

press(selector, key[, options])

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

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

A superset of the key values can be found here.

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

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

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

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

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

Returns

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

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');
  await page.press('#text1', 'Tab');
}

reload([options])

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

reload([options])

This reloads the current page and returns the main resource response.

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

Events

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

Events can be either:

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

Returns

Type	Description
`Promise<Response \| null`	A Promise that fulfills with the Response> instance associated with the page, else `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');
  await page.reload();
}

route(url, handler)

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

route(url, handler)

The method adds a route that allows modifying network requests matching the provided url. The handler is a function taking a Route input that provides functions to continue, fulfill or abort the request. Once routing is enabled, every request matching the url pattern will stall unless one of these functions is called.

When several routes match the given pattern, only the last registered route handler will run, and all others will be skipped.

Parameter	Type	Default	Description
url	string or Regexp	`''`	URL to match during routing.
handler	function( Route)	null	Handler function executed when routing the request.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the route is added to the page.

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

  // Abort all images requests
  await page.route(/(\.png$)|(\.jpg$)/, async function (route) {
    await route.abort();
  });

  // Fulfill request with the following response which
  // changes the quotes displayed on the page
  await page.route(/.*\/quotes$/, async function (route) {
    await route.fulfill({
      body: JSON.stringify({
        quotes: ['"We ❤️ pizza" - k6 team'],
      }),
    });
  });

  // Change the pizza request when the button is clicked
  await page.route(/.*\/pizza$/, async function (route) {
    await route.continue({
      headers: {
        ...route.request().headers(),
        foo: 'bar',
      },
      method: 'POST',
      postData: JSON.stringify({
        maxCaloriesPerSlice: 500,
        mustBeVegetarian: true,
        excludedIngredients: ['Pineapple'],
        excludedTools: ['Knife', 'Scissors'],
        maxNumberOfToppings: 1,
        minNumberOfToppings: 1,
        customName: 'Classic Pizza',
      }),
    });
  });

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

  await page.getByRole('button', { name: 'Pizza, Please!' }).click();

  await page.close();
}

screenshot([options])

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

screenshot([options])

Returns the buffer with the captured screenshot from the browser.

Parameter	Type	Default	Description
options	object	`null`
options.clip	object	`null`	An object which specifies clipping of the resulting image.
options.clip.x	number	`0`	x-coordinate of top-left corner of clip area.
options.clip.y	number	`0`	y-coordinate of top-left corner of clip area.
options.clip.width	number	`0`	Width of clipping area.
options.clip.height	number	`0`	Height of clipping area.
options.fullPage	boolean	`false`	When true, takes a screenshot of the full scrollable page, instead of the currently visible viewport.
options.omitBackground	boolean	`false`	Hides default white background and allows capturing screenshots with transparency. Not applicable to `jpeg` images.
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.quality	number	`0`	The quality of the image, between 0-100; Only applicable to `jpeg` only.
options.type	string	`png`	Specify screenshot type. Acceptable values are `jpeg` and `png`.

Returns

Type	Description
`Promise<Buffer>`	A Promise that fulfills with the Buffer 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');
  await page.screenshot({ path: 'screenshots/browser.png' });
}

selectOption(selector, values[, options])

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

selectOption(selector, values[, options])

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

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

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

Returns

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

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

setChecked(selector, checked[, options])

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

setChecked(selector, checked[, options])

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

Use this method to select 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.
options.strict	boolean	`false`	When `true`, the call requires selector to resolve to a single element. If given selector resolves to more than one element, the call throws an exception.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the set 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');

  await page.setChecked('#checkbox1', true);
  await page.setChecked('#checkbox1', false);

  await page.close();
}

setContent(html[, options])

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

setContent(html[, options])

Sets the supplied HTML string to the current page.

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

Returns

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

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

  const htmlContent = `
    <!doctype html>
    <html>
      <head><meta charset='UTF-8'><title>Test</title></head>
      <body>Test</body>
    </html>
  `;

  await page.setContent(htmlContent);
}

setDefaultNavigationTimeout(timeout)

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

setDefaultNavigationTimeout(timeout)

This setting will change the navigation timeout for the following methods:

Parameter	Type	Default	Description
timeout	number		Timeout in milliseconds.

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

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

setDefaultTimeout(timeout)

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

setDefaultTimeout(timeout)

This setting will change the timeout for all the methods accepting a timeout option.

Parameter	Type	Default	Description
timeout	number		Timeout in milliseconds.

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

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

setExtraHTTPHeaders(headers)

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

setExtraHTTPHeaders(headers)

This sets extra HTTP headers which will be sent with subsequent HTTP requests.

Parameter	Type	Default	Description
headers	Object<string, string>		An object containing the additional HTTP headers. All header values must be strings.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the headers have been set.

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.setExtraHTTPHeaders({ foo: 'bar' });
  const url = await page.goto('https://test.k6.io/browser.php');

  console.log(url.request().headers().foo); // prints bar
}

setInputFiles(selector, file[, options])

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

setInputFiles(selector, file[, options])

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

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

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

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the file has been 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>`);

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

Local File Example

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

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

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

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

  try {
    // In this example we create a simple web page with an upload input field.
    // Usually, you would use page.goto to navigate to a page with a file input field.
    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>`);

    // 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 page.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;
}

setViewportSize(viewportSize)

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

setViewportSize(viewportSize)

This will update the page’s width and height.

Parameter	Type	Description
viewportSize	Object	An object containing the additional HTTP headers. All header values must be strings.
viewportSize.width	number	Page width in pixels.
viewportSize.height	number	Page height in pixels.

Returns

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

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.setViewportSize({
    width: 640,
    height: 480,
  });
  await page.goto('https://test.k6.io/browser.php');
}

tap(selector[, options])

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

tap(selector[, options])

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

Tap the first element that matches the selector.

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

Returns

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

Example

import { browser } from 'k6/browser';

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

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

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

textContent(selector[, options])

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

textContent(selector[, options])

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

Returns the element.textContent.

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

Returns

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

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

throttleCPU(cpuProfile)

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

throttleCPU(cpuProfile)

Throttles the CPU in Chrome/Chromium to slow it down by the specified rate in cpuProfile.

Parameter	Type	Default	Description
cpuProfile	CPUProfile	`null`	This is a mandatory parameter.
cpuProfile.rate	number	`1`	rate as a slowdown factor (1 is no throttle, 2 is 2x slowdown, etc).

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the CPU has been throttled to the specified rate.

Example

import { browser } from 'k6/browser';

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

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

  try {
    await page.throttleCPU({ rate: 4 });

    await page.goto('https://test.k6.io/', { waitUntil: 'networkidle' });
  } finally {
    await page.close();
  }
}

throttleNetwork(networkProfile)

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

throttleNetwork(networkProfile)

Throttles the network in Chrome/Chromium to slow it down by the specified fields in the networkProfile object.

Parameter	Type	Default	Description
networkProfile	NetworkProfile	`null`	This is a mandatory parameter.
networkProfile.latency	number	`0`	Minimum latency from request sent to response headers received (ms).
networkProfile.download	number	`-1`	Maximal aggregated download throughput (bytes/sec). `-1` disables download throttling.
networkProfile.upload	number	`-1`	Maximal aggregated upload throughput (bytes/sec). `-1` disables upload throttling.

To work with the most commonly tested network profiles, import networkProfiles from the browser module. There are three profiles available:

Name	Notes
`'No Throttling'`	No throttling, which is the default before applying any network throttling. This can be used to remove the network throttling.
`'Fast 3G'`	Emulates a typical fast 3G connection
`'Slow 3G'`	Emulates a typical slow 3G connection

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the network has been throttled to the specified rate.

Example

import { browser, networkProfiles } from 'k6/browser';

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

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

  try {
    await page.throttleNetwork(networkProfiles['Slow 3G']);

    await page.goto('https://test.k6.io/', { waitUntil: 'networkidle' });
  } finally {
    await page.close();
  }
}

title()

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

title()

Returns the page’s title.

Returns

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

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');
  console.log(await page.title());
}

touchscreen

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

touchscreen

Returns the Touchscreen instance to interact with a virtual touchscreen on the page.

Returns

Type	Description
Touchscreen	The `Touchscreen` instance associated with the page.

type(selector, text[, options])

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

type(selector, text[, options])

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

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

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

Returns

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

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

uncheck(selector[, options])

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

uncheck(selector[, options])

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

This method is used to unselect an input checkbox.

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

Returns

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

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

unroute(url)

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

unroute(url)

The method removes all routes for the url, that were previously added with page.route.

Parameter	Type	Default	Description
url	string or Regexp	`''`	The exact URL that was used in the `page.route(url, handler)` call.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the route(s) is(are) removed from the page.

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

  // Abort all image requests
  await page.route(/(\.png$)|(\.jpg$)/, async function (route) {
    await route.abort();
  });

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

  await page.getByRole('button', { name: 'Pizza, Please!' }).click();

  // Stop aborting all image requests
  await page.unroute(/(\.png$)|(\.jpg$)/)

  await page.close();
}

unrouteAll()

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

unrouteAll()

The method removes all routes created with page.route.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when all routes are removed from the page.

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

  // Abort all image requests
  await page.route(/(\.png$)|(\.jpg$)/, async function (route) {
    await route.abort();
  });

  // Fulfill request with the following response which
  // changes the quotes displayed on the page
  await page.route(/.*\/quotes$/, async function (route) {
    await route.fulfill({
      body: JSON.stringify({
        quotes: ['"We ❤️ pizza" - k6 team'],
      }),
    });
  });

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

  await page.getByRole('button', { name: 'Pizza, Please!' }).click();

  // Stop aborting all image requests and fulfilling quote requests
  await page.unrouteAll()

  await page.close();
}

url()

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

url()

Returns the page’s URL.

Returns

Type	Description
string	The page’s URL.

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');
  console.log(page.url());
}

viewportSize()

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

viewportSize()

Returns the page’s size (width and height).

Returns

Type	Description
Object	An object containing the page’s width and height.

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.setViewportSize({
    width: 640,
    height: 480,
  });
  await page.goto('https://test.k6.io/browser.php');

  console.log(page.viewportSize());
}

waitForEvent(event[, optionsOrPredicate])

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

waitForEvent(event[, optionsOrPredicate])

Waits for the specified event to be emitted. This is a generic method that can wait for any page event such as console, request, or response.

Parameter	Type	Default	Description
event	string	-	Required. Event name. Supported events: `console`, `request`, `response`.
optionsOrPredicate	function \| object	`null`	Either a predicate function or an options object. If a function, it will be used as the predicate.
options.predicate	function	`null`	A function that returns `true` when the expected event is received. The event object is passed as argument.
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	A Promise that fulfills with the event data when the event is emitted. The return type depends on the event: ConsoleMessage for `console`, Request for `request`, Response for `response`.

Examples

Wait for console message

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 {
    // Set up the wait before triggering the action
    const consolePromise = page.waitForEvent('console');

    // Trigger action that causes a console message
    await page.evaluate(() => console.log('hello from page'));

    const msg = await consolePromise;
    console.log(`Console message: ${msg.text()}`);
  } finally {
    await page.close();
  }
}

Wait for response with predicate

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

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/');

    // Wait for a specific response using a predicate function
    const responsePromise = page.waitForEvent('response', (res) =>
      res.url().includes('/api/pizza')
    );

    await page.getByRole('button', { name: /pizza/i }).click();

    const response = await responsePromise;

    check(response, {
      'response status is 200': (r) => r.status() === 200,
    });
  } finally {
    await page.close();
  }
}

Best practices

Set up promise before trigger: Always set up the waitForEvent promise before triggering the action that causes the event:

// Correct
const eventPromise = page.waitForEvent('console');
await page.evaluate(() => console.log('test'));
const msg = await eventPromise;

// Incorrect - may miss the event
await page.evaluate(() => console.log('test'));
const msg = await page.waitForEvent('console');

Use specific methods when available: For common use cases, prefer the more specific methods like waitForRequest or waitForResponse which provide URL pattern matching.

page.on() - Subscribe to page events
page.waitForRequest() - Wait for HTTP requests with URL pattern matching
page.waitForResponse() - Wait for HTTP responses with URL pattern matching

waitForFunction(pageFunction, options[, arg])

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

waitForFunction(pageFunction, options[, arg])

Returns when the pageFunction returns a truthy value.

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

Returns

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

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.evaluate(() => {
      setTimeout(() => {
        const el = document.createElement('h1');
        el.innerHTML = 'Hello';
        document.body.appendChild(el);
      }, 1000);
    });

    const ok = await page.waitForFunction("document.querySelector('h1')", {
      polling: 'mutation',
      timeout: 2000,
    });
    await check(ok, {
      'waitForFunction successfully resolved': async (ok) =>
          await ok.innerHTML() == 'Hello'
    });
  } finally {
    await page.close();
  }
}

waitForLoadState(state[, options])

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

waitForLoadState(state[, options])

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

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

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

Events

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

Events can be either:

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

Returns

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

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 () {
  let page = await browser.newPage();

  try {
    await page.goto('https://test.k6.io/my_messages.php');

    await page.locator('input[name="login"]').type('admin');
    await page.locator('input[name="password"]').type('123');

    const submitButton = page.locator('input[type="submit"]');
    await submitButton.click();

    await page.waitForLoadState('networkidle'); // waits until the `networkidle` event

    await check(page.locator('h2'), {
      'header': async h2 => await h2.textContent() == 'Welcome, admin!'
    });
  } finally {
    await page.close();
  }
}

waitForNavigation([options])

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

waitForNavigation([options])

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

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

When to use the url option

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

Events

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

Events can be either:

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

Returns

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

Examples

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

    await page.locator('input[name="login"]').type('admin');
    await page.locator('input[name="password"]').type('123');

    const submitButton = page.locator('input[type="submit"]');

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

    await check(page.locator('h2'), {
      header: async (h2) => (await h2.textContent()) == 'Welcome, admin!',
    });
  } finally {
    await page.close();
  }
}

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

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

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

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

waitForRequest(urlPattern[, options])

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

waitForRequest(urlPattern[, options])

Waits for an HTTP request that matches the specified URL pattern. This method is particularly useful for waiting for requests to be initiated before proceeding with the test, such as verifying that form submissions or API calls are triggered.

Parameter	Type	Default	Description
urlPattern	string \| RegExp	-	Required. URL or URL pattern to match against requests. Can be an exact URL string, a regular expression, or an empty string to match any request.
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< Request>	A Promise that fulfills with the Request object when a URL matches and the request is initiated.

Examples

Wait for API request

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

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/');

    // Test waitForRequest with user interaction
    const pizzaRequestPromise = page.waitForRequest('https://quickpizza.grafana.com/api/pizza');

    await page.getByRole('button', { name: /pizza/i }).click();

    const pizzaRequest = await pizzaRequestPromise;

    // Check that the pizza API request was initiated
    check(pizzaRequest, {
      'pizza API URL is correct': (r) => r.url() === 'https://quickpizza.grafana.com/api/pizza',
      'pizza API method is POST': (r) => r.method() === 'POST',
    });
  } finally {
    await page.close();
  }
}

Best practices

Use appropriate patterns: Choose the right matching method based on your needs:
- Exact strings for known, static API endpoints
- RegExp for pattern-based matching and dynamic URLs
Set up promise before trigger: Always set up the waitForRequest promise before triggering the action that causes the request:

// Correct
const requestPromise = page.waitForRequest('/api/data');
await page.click('#submit');
const request = await requestPromise;

// Incorrect - may miss the request
await page.click('#submit');
const request = await page.waitForRequest('/api/data');

Verify request content: After waiting for the request, verify that the request URL, method, and headers match your expectations.

page.on() - Subscribe to page events
page.waitForEvent() - Wait for page events with predicate functions
page.waitForLoadState() - Wait for load states
page.waitForNavigation() - Wait for navigation events
page.waitForResponse() - Wait for HTTP responses
page.waitForURL() - Wait for URL changes
Request - Request object methods and properties

waitForResponse(urlPattern[, options])

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

waitForResponse(urlPattern[, options])

Waits for an HTTP response that matches the specified URL pattern. This method is particularly useful for waiting for responses from AJAX/fetch requests, API calls, or specific resources to be loaded before proceeding with the test.

Parameter	Type	Default	Description
urlPattern	string \| RegExp	-	Required. URL or URL pattern to match against responses. Can be an exact URL string, a regular expression, or an empty string to match any response.
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< Response>	A Promise that fulfills with the Response object when a URL matches and the response is received.

Examples

Wait for API response

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

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/');

    // Test waitForResponse with user interaction
    const pizzaResponsePromise = page.waitForResponse('https://quickpizza.grafana.com/api/pizza');

    await page.getByRole('button', { name: /pizza/i }).click();

    const pizzaResponse = await pizzaResponsePromise;

    // Check that the pizza API call was successful
    check(pizzaResponse, {
      'pizza API status is 200': (r) => r.status() === 200,
      'pizza API URL is correct': (r) => r.url() === 'https://quickpizza.grafana.com/api/pizza',
    });
  } finally {
    await page.close();
  }
}

Best practices

Use appropriate patterns: Choose the right matching method based on your needs:
- Exact strings for known, static API endpoints
- RegExp for pattern-based matching and dynamic URLs
Set up promise before trigger: Always set up the waitForResponse promise before triggering the action that causes the request:

// Correct
const responsePromise = page.waitForResponse('/api/data');
await page.click('#submit');
const response = await responsePromise;

// Incorrect - may miss the response
await page.click('#submit');
const response = await page.waitForResponse('/api/data');

Verify response content: After waiting for the response, verify that the response status and content match your expectations.

page.on() - Subscribe to page events
page.waitForEvent() - Wait for page events with predicate functions
page.waitForLoadState() - Wait for load states
page.waitForNavigation() - Wait for navigation events
page.waitForRequest() - Wait for HTTP requests
page.waitForURL() - Wait for URL changes
Response - Response object methods and properties

waitForSelector(selector[, options])

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

waitForSelector(selector[, options])

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

Returns when element specified by selector satisfies state option.

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

Element states

Element states can be either:

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

Returns

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

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');
  await page.waitForSelector('#text1');
}

waitForTimeout(timeout)

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

waitForTimeout(timeout)

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

Waits for the given timeout in milliseconds.

Returns

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

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');
  await page.waitForTimeout(5000);
}

waitForURL(url[, options])

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

waitForURL(url[, options])

Waits for the page to navigate to the specified URL. This method is useful for ensuring that navigation to a particular URL has completed before proceeding with the test. This is especially useful if there are multiple redirects before hitting the end destination.

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

Events

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

Events can be either:

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

Returns

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

Examples

import { browser } from 'k6/browser';

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

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

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

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

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

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

Valid usage patterns for waitForURL

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

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

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

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

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

Best practices

Use appropriate matching: Choose the right matching method based on your needs:
- Exact strings for known, static URLs
- RegExp for pattern-based matching and complex URL validation
Handle dynamic content: For URLs with dynamic parts (IDs, timestamps), use regular expression patterns instead of exact matches.
Set appropriate timeouts: Adjust timeouts based on expected navigation time and network conditions.
Verify final state: After waiting for URL, verify that the page content matches your expectations.

Common use cases

Form submissions: Verify redirects after successful form submission
Authentication flows: Wait for login/logout redirects
E-commerce: Track progression through shopping and checkout flows
SPAs: Handle client-side routing changes
API redirects: Wait for server-side redirects after API calls

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

workers()

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

workers()

This method returns an array of the dedicated WebWorkers associated with the page.

Returns

Type	Description
WebWorkers[]	Array of `WebWorkers` associated with the page.

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');
  console.log(page.workers());
}