k6/browser on Grafana Labs

BrowserContext

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

BrowserContext

BrowserContexts provide a way to operate multiple independent sessions, with separate pages, cache, and cookies. A default BrowserContext is created when a browser is launched.

The browser module API is used to create a new BrowserContext.

If a page opens another page, e.g. with a window.open call, the popup will belong to the parent page’s BrowserContext.

Method	Description
addCookies()	Adds cookies into the `BrowserContext`.
addInitScript()	Adds a script that will be evaluated on page creation, frame attached or a navigation occurs.
clearCookies()	Clear the `BrowserContext`’s cookies.
clearPermissions()	Clears all permission overrides for the `BrowserContext`.
cookies()	Returns a list of cookies from the `BrowserContext`.
close()	Close the `BrowserContext` and all its pages.
grantPermissions(permissions[, options])	Grants specified permissions to the `BrowserContext`.
newPage()	Uses the `BrowserContext` to create a new Page and returns it.
pages()	Returns a list of pages that belongs to the `BrowserContext`.
setDefaultNavigationTimeout(timeout)	Sets the default navigation timeout in milliseconds.
setDefaultTimeout(timeout)	Sets the default maximum timeout for all methods accepting a timeout option in milliseconds.
setGeolocation(geolocation)	Sets the `BrowserContext`’s geolocation.
setOffline(offline)	Toggles the `BrowserContext`’s connectivity on/off.
waitForEvent(event[, optionsOrPredicate])	Waits for the event to fire and passes its value into the predicate function.

Chromium

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

Chromium

chromium is a browser type that you can import from the browser module ('k6/browser'). It lets your test attach to a Chromium-based browser that is already running, instead of one that k6 launches and manages for you.

Use it when the browser lifecycle isn’t k6’s to manage, for example when the browser runs in a separate container or when a third-party provider hands you a browser session. Everything else stays the same: the returned browser exposes the same browser module API as a k6-managed browser.

Method	Description
connectOverCDP(wsEndpoint)	Attaches to an existing Chromium-based browser over the Chrome DevTools Protocol (CDP) and returns the Browser.

ConsoleMessage

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

ConsoleMessage

Supported APIs

Method	Description
args()	List of arguments passed to a `console` function call.
page()	The page that produced this console message.
text()	The text of the console message.
type()	The type of the console message. For example: `log`, or `debug`.

MetricMessage

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

MetricMessage

A MetricMessage object allows tagging of metrics that are measured and emitted for the page.

MetricMessage objects are dispatched by the page when a handler is registered with page.on(‘metric’). For each metric that is measured and emitted for the page, the k6 browser module delivers a MetricMessage object to the registered handlers, allowing them to pattern match and tag metrics.

tag

The tag method matches the given matches with the current metric’s url and name tags. When a match is found, it will use name to replace the existing URL and name tag values.

Doing this helps group metrics with different URL and name tags that, in fact, reference the same resource, allowing for correlation over time and reducing the cardinality of the metrics.

Parameter	Type	Description
tagMatch	object	The tagMatch object and its properties that are used for matching metrics. Required.
tagMatch.name	string	The name value that replaces the current metric’s URL and name tag values, if a match is found. Required, and must not be an empty string.
tagMatch.matches	object[]	An array of objects containing the matchers which will be used to match against the current metric’s URL and name tags. Required.
tagMatch.matches.url	RegExp	The regular expression used to find matches in the current metric’s URL and name tags. Required.
tagMatch.matches.method	string?	Used to match the metric’s method tag. Valid values are `'GET'`, `'POST'`, `'PUT'`, `'DELETE'`, `'PATCH'`, `'OPTIONS'`, `'HEAD'`, `'TRACE'` and `'CONNECT'`. It’s optional, and when it’s not set it will group all metrics regardless of the method tag.

Example Usage

// First we need to register a handler with `page.on('metric')`.
page.on('metric', (metric) => {
  // It will find a match between the current metric url and name tags against
  // the supplied regular expression in `url`.
  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',
      },
    ],
  });
});

ElementHandle

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

ElementHandle

Method	Description
$(selector)	Queries the element for the given selector.
$$(selector)	Queries the elements for the given selector.
boundingBox()	Returns the bounding box of the element.
check([options])	Checks the element if it is a `checkbox` or `radio` button.
click([options])	Clicks on the element.
contentFrame()	Returns the Frame of the element.
dblclick([options])	Double clicks on the element.
dispatchEvent(type[, eventInit])	Dispatches an event to the element.
fill(value[, options])	Fills the specified value into the element.
focus()	Focuses on the element.
getAttribute(name)	Returns the specified attribute of the element.
hover([options])	Hovers over the element.
innerHTML()	Returns the inner HTML of the element.
innerText()	Returns the inner text of the element.
inputValue([options])	Returns the value of the input element.
isChecked()	Checks if the `checkbox` input type is selected.
isDisabled()	Checks if the element is `disabled`.
isEditable()	Checks if the element is `editable`.
isEnabled()	Checks if the element is `enabled`.
isHidden()	Checks if the element is `hidden`.
isVisible()	Checks if the element is `visible`.
ownerFrame()	Returns the Frame of the element.
press(key[, options])	Focuses on the element and presses a single key or a combination of keys using the virtual keyboard.
screenshot([options])	Takes a screenshot of the element.
scrollIntoViewIfNeeded([options])	Scrolls the element into view if needed.
selectOption(values[, options])	Selects the `select` element’s one or more options which match the values.
selectText([options])	Selects the text of the element.
setChecked(checked[, options])	Sets the `checkbox` or `radio` input element’s value to the specified checked or unchecked state.
setInputFiles(file[, options])	Sets the file input element’s value to the specified files.
tap(options)	Taps the element.
textContent()	Returns the text content of the element.
type(text[, options])	Focuses on the element and types the specified text into the element using the virtual keyboard.
uncheck([options])	Unchecks the element if it is a `checkbox` or `radio` button.
waitForElementState(state[, options])	Waits for the element to reach the specified state.
waitForSelector(selector[, options])	Waits for the element to be present in the DOM and to be visible.

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

  // Goto front page, find login link and click it
  try {
    await page.goto('https://test.k6.io/');
    const messagesLink = await page.$('a[href="/my_messages.php"]');

    await Promise.all([page.waitForNavigation(), messagesLink.click()]);
    // Enter login credentials and login
    const login = await page.$('input[name="login"]');
    await login.type('admin');
    const password = await page.$('input[name="password"]');
    await password.type('123');

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

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

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

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 {
    // Inject page content
    await page.setContent(`
          <div class="visible">Hello world</div>
          <div style="display:none" class="hidden"></div>
          <div class="editable" editable>Edit me</div>
          <input type="checkbox" enabled class="enabled">
          <input type="checkbox" disabled class="disabled">
          <input type="checkbox" checked class="checked">
          <input type="checkbox" class="unchecked">
    `);

    // Check state
    await check(page, {
      'is visible': async p => {
        const e = await p.$('.visible');
        return e.isVisible();
      },
      'is hidden': async p => {
        const e = await p.$('.hidden');
        return e.isHidden();
      },
      'is editable': async p => {
        const e = await p.$('.editable');
        return e.isEditable();
      },
      'is enabled': async p => {
        const e = await p.$('.enabled');
        return e.isEnabled();
      },
      'is disabled': async p => {
        const e = await p.$('.disabled');
        return e.isDisabled();
      },
      'is checked': async p => {
        const e = await p.$('.checked');
        return e.isChecked();
      },
      'is unchecked': async p => {
        const e = await p.$('.unchecked');
        return await e.isChecked() === false;
      },
    });
  } finally {
    await page.close();
  }
}

Frame

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

Frame

Frame represents a single frame in a browser window. It can be a top-level frame or an iframe. Frames are used to organize content in a browser window. Frames can be nested, and each frame has its own document and window objects.

Method	Description
$(selector)	Finds an element matching the specified `selector` within the frame.
$$(selector)	Finds all elements matching the specified `selector` within the frame.
check(selector[, options])	Select the input checkbox.
childFrames()	Returns an array of child frames.
click(selector[, options])	Clicks on an element matching a `selector`.
content()	Gets the HTML contents of the frame.
dblclick(selector[, options])	Double click on an element matching the provided `selector`.
dispatchEvent(selector, type, eventInit[, options])	Dispatches HTML DOM event types e.g. `'click'`
evaluate(pageFunction[, arg])	Returns the value of the `pageFunction` invocation.
evaluateHandle(pageFunction[, arg])	Returns the value of the `pageFunction` invocation as a JSHandle.
fill(selector, value[, options])	Fill an `input`, `textarea` or `contenteditable` element with the provided value.
focus(selector[, options])	Fetches an element with `selector` and focuses on it.
frameElement()	Returns the `frame`’s `element`.
frameLocator(selector)	Returns a FrameLocator for the nested iframe matching the given `selector`.
getAttribute(selector, name[, options])	Returns the element attribute value for the given attribute name.
getByAltText(altText[, options])	Returns a locator for elements with the specified `alt` attribute text.
getByLabel(text[, options])	Returns a locator for form controls with the specified label text.
getByPlaceholder(placeholder[, options])	Returns a locator for input elements with the specified `placeholder` attribute text.
getByRole(role[, options])	Returns a locator for elements with the specified ARIA role.
getByTestId(testId)	Returns a locator for elements with the specified `data-testid` attribute.
getByText(text[, options])	Returns a locator for elements containing the specified text.
getByTitle(title[, options])	Returns a locator for elements with the specified `title` attribute.
goto(url[, options])	Navigates to the specified `url`.
hover(selector[, options])	Hovers over an element matching `selector`.
innerHTML(selector[, options])	Returns the `element.innerHTML`.
innerText(selector[, options])	Returns the `element.innerText`.
inputValue(selector[, options])	Returns `input.value` for the selected `input`, `textarea` or `select` element.
isChecked(selector[, options])	Checks to see if the `checkbox` `input` type is selected or not.
isDetached()	Returns `true` if the frame is detached from the DOM.
isDisabled(selector[, options])	Checks if the element is `disabled`.
isEditable(selector[, options])	Checks if the element is `editable`.
isEnabled(selector[, options])	Checks if the element is `enabled`.
isHidden(selector[, options])	Checks if the matched element is `hidden`.
isVisible(selector[, options])	Checks if the matched element is `visible`.
locator(selector[, options])	Returns a Locator for the given `selector`.
name()	Returns the name of the frame.
page()	Returns the page containing the frame.
parentFrame()	Returns the parent frame, if any.
press(selector, key[, options])	Focuses the element, and then presses the given `key` on the Keyboard.
selectOption(selector, values[, options])	Selects one or more options which match the values from a `<select>` element.
setContent(html[, options])	Sets the supplied HTML string to the current frame.
setInputFiles(selector, file[, options])	Sets the file input element’s value to the specified files.
setChecked(selector, checked[, options])	Sets the `checkbox` or `radio` input element’s value to the specified checked or unchecked state.
tap(selector[, options])	Taps the first element that matches the `selector`.
textContent(selector[, options])	Returns the `element.textContent`.
title()	Returns the title of the frame.
type(selector, text[, options])	Types the `text` in the first element found that matches the `selector`.
uncheck(selector[, options])	Unchecks an input `checkbox` element.
url()	Returns the `frame`’s URL.
waitForFunction(pageFunction, options[, arg])	Returns when the `pageFunction` returns a truthy value.
waitForLoadState(state[, options])	Waits for the given load `state` to be reached.
waitForNavigation([options])	Waits for the given navigation lifecycle event to occur and returns the main resource response.
waitForSelector(selector[, options])	Returns when element specified by selector satisfies `state` option.
waitForTimeout(timeout)	Waits for the given `timeout` in milliseconds.
waitForURL(url[, options])	Waits for the frame to navigate to the specified URL.

JSHandle

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

JSHandle

Represents a reference to a JavaScript object within the context of a webpage. This allows you to interact with JavaScript objects directly from your script.

Supported APIs

Method	Description
asElement()	Returns either `null` or the object handle itself, if the object handle is an instance of ElementHandle.
dispose()	Stops referencing the element handle.
evaluate(pageFunction[, arg])	Evaluates the `pageFunction` and returns its return value.
evaluateHandle(pageFunction[, arg])	Evaluates the `pageFunction` and returns a `JSHandle`.
getProperties()	Fetches a map with own property names of of the `JSHandle` with their values as `JSHandle` instances.
jsonValue()	Fetches a JSON representation of the object.

Example

import { browser } from 'k6/browser';

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

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

  try {
    await page.goto('https://test.k6.io/');
    const jsHandle = await page.evaluateHandle(() => document.head);
    // ...
  } finally {
    await page.close();
  }
}

Keyboard

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

Keyboard

Keyboard provide a way to interact with a virtual keyboard.

Method	Description
down(key)	Dispatches a `keydown` event.
up(key)	Dispatches a `keyup` event.
press(key[, options])	Dispatches a `keydown` event followed by an `keyup` event.
type(text[, options])	Dispatches a `keydown`, `keypress` or`input`, and `keyup` events for each character in the text.
insertText(text)	Dispatches only an `input` 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();
  await page.goto('https://test.k6.io/my_messages.php', {
    waitUntil: 'networkidle'
  });

  const login = page.locator('input[name="login"]');
  await login.click();
  await page.keyboard.type("admin");

  const password = page.locator('input[name="password"]');
  await password.click();
  await page.keyboard.type("123");

  await Promise.all([
    page.keyboard.press('Enter'), // submit
    page.waitForNavigation(),
  ]);

  await page.close();
}

Locator

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

Locator

The Locator API makes it easier to work with dynamically changing elements. Some of the benefits of using it over existing ways to locate an element (e.g. Page.$()) include:

Helps with writing robust tests by finding an element even if the underlying frame navigates.
Makes it easier to work with dynamic web pages and SPAs built with Svelte, React, Vue, etc.
Enables the use of test abstractions like the Page Object Model (POM) pattern to simplify and organize tests.
strict mode is enabled for all locator methods that are expected to target a single DOM element, meaning that if more than one element matches the given selector, an error will be thrown.

Locator can be created with the page.locator(selector[, options]) method.

Method	Description
all()	When multiple elements match the selector, returns an array of `locator`.
boundingBox([options])	Returns the bounding box of the element.
check([options])	Select the input checkbox.
clear([options])	Clears text boxes and input fields of any existing values.
click([options])	Mouse click on the chosen element.
contentFrame()	Returns a `FrameLocator` object pointing to the same `iframe` as this locator.
count()	Returns the number of elements matching the selector.
dblclick([options])	Mouse double click on the chosen element.
dispatchEvent(type, eventInit, [options])	Dispatches HTML DOM event types e.g. `'click'`.
evaluate(pageFunction[, arg])	Returns the value of the `pageFunction` invocation, called with the matching element as first argument.
evaluateHandle(pageFunction[, arg])	Returns the value of the `pageFunction` invocation as a JSHandle.
fill(value, [options])	Fill an `input`, `textarea` or `contenteditable` element with the provided value.
filter(options)	Returns a new `locator` that matches only elements containing or excluding specified text.
first()	Returns a `locator` to the first matching element.
focus([options])	Calls focus on the element, if it can be focused.
frameLocator(selector)	Shorthand for `locator(selector).contentFrame()`. Returns a FrameLocator for the iframe matching the given `selector`.
getAttribute(name, [options])	Returns the element attribute value for the given attribute name.
getByAltText(altText[, options])	Returns a locator for elements with the specified `alt` attribute text.
getByLabel(text[, options])	Returns a locator for form controls with the specified label text.
getByPlaceholder(placeholder[, options])	Returns a locator for input elements with the specified `placeholder` attribute text.
getByRole(role[, options])	Returns a locator for elements with the specified ARIA role.
getByTestId(testId)	Returns a locator for elements with the specified `data-testid` attribute.
getByText(text[, options])	Returns a locator for elements containing the specified text.
getByTitle(title[, options])	Returns a locator for elements with the specified `title` attribute.
hover([options])	Hovers over the element.
innerHTML([options])	Returns the `element.innerHTML`.
innerText([options])	Returns the `element.innerText`.
inputValue([options])	Returns `input.value` for the selected `input`, `textarea` or `select` element.
isChecked([options])	Checks if the `checkbox` `input` type is selected.
isDisabled([options])	Checks if the element is `disabled`.
isEditable([options])	Checks if the element is `editable`.
isEnabled([options])	Checks if the element is `enabled`.
isHidden()	Checks if the element is `hidden`.
isInViewport([options])	Checks if the element is in the viewport, with an optional visible-ratio threshold.
isVisible()	Checks if the element is `visible`.
last()	Returns a `locator` to the last matching element.
locator(selector[, options])	Returns a new chained `locator` for the given `selector`.
nth()	Returns a `locator` to the n-th matching element.
press(key, [options])	Press a single key on the keyboard or a combination of keys.
pressSequentially(text, [options])	Type text character by character, simulating real keyboard input.
selectOption(values, [options])	Select one or more options which match the values.
setChecked(checked[, options])	Sets the `checkbox` or `radio` input element’s value to the specified checked or unchecked state.
tap([options])	Tap on the chosen element.
textContent([options])	Returns the `element.textContent`.
type(text, [options])	Type in the text into the input field.
uncheck([options])	Unselect the `input` checkbox.
waitFor([options])	Wait for the element to be in a particular state e.g. `visible`.

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

    /*
    In this example, we will use two locators, matching a
    different betting button on the page. If you were to query
    the buttons once and save them as below, you would see an
    error after the initial navigation. Try it!
  
      const heads = await page.$("input[value='Bet on heads!']");
      const tails = await page.$("input[value='Bet on tails!']");
  
    The Locator API allows you to get a fresh element handle each
    time you use one of the locator methods. And, you can carry a
    locator across frame navigations. Let's create two locators;
    each locates a button on the page.
    */
    const heads = page.locator("input[value='Bet on heads!']");
    const tails = page.locator("input[value='Bet on tails!']");

    const currentBet = page.locator("//p[starts-with(text(),'Your bet: ')]");

    // In the following Promise.all the tails locator clicks
    // on the tails button by using the locator's selector.
    // Since clicking on each button causes page navigation,
    // waitForNavigation is needed -- this is because the page
    // won't be ready until the navigation completes.
    // Setting up the waitForNavigation first before the click
    // is important to avoid race conditions.
    await Promise.all([page.waitForNavigation(), tails.click()]);
    console.log(await currentBet.innerText());
    // the heads locator clicks on the heads button
    // by using the locator's selector.
    await Promise.all([page.waitForNavigation(), heads.click()]);
    console.log(await currentBet.innerText());
    await Promise.all([page.waitForNavigation(), tails.click()]);
    console.log(await currentBet.innerText());
  } finally {
    await page.close();
  }
}

FrameLocator

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

FrameLocator

FrameLocator represents a way to find element(s) in an iframe. Frames can be nested, and this locator supports selecting a frame element and then working with it.

A FrameLocator can be created with the page.frameLocator(selector) method or the locator.contentFrame() method.

Method	Description
frameLocator(selector)	Returns a FrameLocator for a nested iframe matching the given `selector` within this frame.
getByAltText(altText[, options])	Returns a locator for elements with the specified `alt` attribute text.
getByLabel(text[, options])	Returns a locator for form controls with the specified label text.
getByPlaceholder(placeholder[, options])	Returns a locator for input elements with the specified `placeholder` attribute text.
getByRole(role[, options])	Returns a locator for elements with the specified ARIA role.
getByTestId(testId)	Returns a locator for elements with the specified `data-testid` attribute.
getByText(text[, options])	Returns a locator for elements containing the specified text.
getByTitle(title[, options])	Returns a locator for elements with the specified `title` attribute.
locator(selector[, options])	Returns a new chained `locator` for the given `selector` within the frame.

Mouse

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

Mouse

Mouse provides a way to interact with a virtual mouse.

Method	Description
click(x, y[, options])	Mouse clicks on the `x` and `y` coordinates.
dblclick(x, y[, options])	Mouse double clicks on the `x` and `y` coordinates.
down([options])	Dispatches a `mousedown` event on the mouse’s current position.
up([options])	Dispatches a `mouseup` event on the mouse’s current position.
move(x, y[, options])	Dispatches a `mousemove` event on the mouse’s current position.

Example

import { browser } from 'k6/browser';

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

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

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

  // Obtain ElementHandle for news link and navigate to it
  // by clicking in the 'a' element's bounding box
  const newsLinkBox = await page.$('a[href="/news.php"]');
  const boundingBox = await newsLinkBox.boundingBox();
  const x = newsLinkBox.x + newsLinkBox.width / 2; // center of the box
  const y = newsLinkBox.y;

  await page.mouse.click(x, y);

  await page.close();
}

Page

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

Page

Page provides methods to interact with a single tab in a running web browser. A single BrowserContext can have many pages.

Method	Description
$(selector)	Finds an element matching the specified `selector` within the page.
$$(selector)	Finds all elements matching the specified `selector` within the page.
bringToFront()	Activates a browser tab.
check(selector[, options])	Select the input checkbox.
click(selector[, options])	Clicks on an element matching a `selector`.
close()	Closes a tab that the `page` is associated with.
content()	Gets the HTML contents of the page.
context()	Gets the BrowserContext that the page belongs to.
dblclick(selector[, options])	With the Mouse, double click on an element matching the provided `selector`.
dispatchEvent(selector, type, eventInit[, options])	Dispatches HTML DOM event types e.g. `'click'`
emulateMedia([options])	Changes the CSS media type and the color scheme feature.
emulateVisionDeficiency(type)	Emulates your website with the specified vision deficiency `type`.
evaluate(pageFunction[, arg])	Returns the value of the `pageFunction` invocation.
evaluateHandle(pageFunction[, arg])	Returns the value of the `pageFunction` invocation as a JSHandle.
fill(selector, value[, options])	Fill an `input`, `textarea` or `contenteditable` element with the provided value.
focus(selector[, options])	Fetches an element with `selector` and focuses on it.
frames()	Returns an array of frames on the page.
frameLocator(selector)	Returns a FrameLocator for the iframe matching the given `selector`.
getAttribute(selector, name[, options])	Returns the element attribute value for the given attribute name.
getByAltText(altText[, options])	Returns a locator for elements with the specified `alt` attribute text.
getByLabel(text[, options])	Returns a locator for form controls with the specified label text.
getByPlaceholder(placeholder[, options])	Returns a locator for input elements with the specified `placeholder` attribute text.
getByRole(role[, options])	Returns a locator for elements with the specified ARIA role.
getByTestId(testId)	Returns a locator for elements with the specified `data-testid` attribute.
getByText(text[, options])	Returns a locator for elements containing the specified text.
getByTitle(title[, options])	Returns a locator for elements with the specified `title` attribute.
goBack([options])	Navigates back in the browser’s session history.
goForward([options])	Navigates forward in the browser’s session history.
goto(url[, options])	Navigates to the specified `url`.
hover(selector[, options])	Hovers over an element matching `selector`.
innerHTML(selector[, options])	Returns the `element.innerHTML`.
innerText(selector[, options])	Returns the `element.innerText`.
inputValue(selector[, options])	Returns `input.value` for the selected `input`, `textarea` or `select` element.
isChecked(selector[, options])	Checks to see if the `checkbox` `input` type is selected or not.
isClosed()	Checks if the page has been closed.
isDisabled(selector[, options])	Checks if the element is `disabled`.
isEditable(selector[, options])	Checks if the element is `editable`.
isEnabled(selector[, options])	Checks if the element is `enabled`.
isHidden(selector[, options])	Checks if the element is `hidden`.
isVisible(selector[, options])	Checks if the element is `visible`.
keyboard	Returns the Keyboard instance to interact with a virtual keyboard on the page.
locator(selector[, options])	Returns a Locator for the given `selector`.
mainFrame()	Returns the page’s main Frame.
mouse	Returns the Mouse instance to interact with a virtual mouse on the page.
on(event, handler)	Registers a handler to be called whenever the specified event occurs.
opener()	Returns the `page` that opened the current `page`.
press(selector, key[, options])	Focuses the element, and then presses the given `key` on the Keyboard.
reload([options])	Reloads the current page.
route(url, handler)	Adds a route to the page to modify network requests made by that page.
screenshot([options])	Returns a buffer with the captured screenshot from the web browser.
selectOption(selector, values[, options])	Selects one or more options which match the values from a `<select>` element.
setContent(html[, options])	Sets the supplied HTML string to the current page.
setChecked(selector, checked[, options])	Sets the `checkbox` or `radio` input element’s value to the specified checked or unchecked state.
setDefaultNavigationTimeout(timeout)	Changes the navigation timeout for page.goto(url[, options]), page.reload([options]), page.setContent(html[, options]), and page.waitForNavigation([options])
setDefaultTimeout(timeout)	Changes the timeout for all the methods accepting a `timeout` option.
setExtraHTTPHeaders(headers)	Sets extra HTTP headers which will be sent with subsequent HTTP requests.
setInputFiles(selector, file[, options])	Sets the file input element’s value to the specified files.
setViewportSize(viewportSize)	Updates the `page`’s width and height.
tap(selector[, options])	Taps the first element that matches the `selector`.
textContent(selector[, options])	Returns the `element.textContent`.
throttleCPU(cpuProfile)	Throttles the CPU in Chrome/Chromium to slow it down by the specified `rate` in the `cpuProfile` object.
throttleNetwork(networkProfile)	Throttles the network in Chrome/Chromium to slow it down by the specified fields in the `networkProfile` object.
title()	Returns the `page`’s title.
type(selector, text[, options])	Types the `text` in the first element found that matches the `selector`.
touchscreen	Returns the Touchscreen instance to interact with a virtual touchscreen on the page.
uncheck(selector[, options])	Unselects an input `checkbox` element.
unroute(url)	Removes all existing routes for the `url`.
unrouteAll()	Removes all routes created with `page.route()`.
url()	Returns the `page`’s URL.
viewportSize()	Returns the `page`’s size (width and height).
waitForEvent(event[, optionsOrPredicate])	Waits for the specified event to be emitted.
waitForFunction(pageFunction, options[, arg])	Returns when the `pageFunction` returns a truthy value.
waitForLoadState(state[, options])	Waits for the given load `state` to be reached.
waitForNavigation([options])	Waits for the given navigation lifecycle event to occur and returns the main resource response.
waitForRequest(urlPattern[, options])	Waits for an HTTP request that matches the specified URL pattern.
waitForResponse(urlPattern[, options])	Waits for an HTTP response that matches the specified URL pattern.
waitForSelector(selector[, options])	Returns when element specified by selector satisfies `state` option.
waitForTimeout(timeout)	Waits for the given `timeout` in milliseconds.
waitForURL(url[, options])	Waits for the page to navigate to the specified URL.
workers()	Returns an array of the dedicated WebWorkers associated with the page.

Request

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

Request

The request that the browser performs can be retrieved from the Response when a navigation occurs.

Supported APIs

Method	Description
allHeaders()	Returns an object of headers associated to the request including headers added by the browser.
frame()	The Frame that initiated the request.
headers()	Returns an object of headers associated to the request.
headersArray()	An array with all the request HTTP headers.
headerValue(name)	Returns the value of the header matching the name. The name is case insensitive.
isNavigationRequest()	Returns a boolean stating whether the request is for a navigation.
method()	Request’s method (GET, POST, etc.).
postData()	Contains the request’s post body, if any.
postDataBuffer()	Request’s post body in a binary form, if any.
resourceType()	Contains the request’s resource type as it was perceived by the rendering engine.
response()	Returns the matching Response object.
size()	Returns an object containing the size of the request headers and body.
timing()	Returns resource timing information for given request.
url()	URL of the request.

Example

import { browser } from 'k6/browser';

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

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

  try {
    const res = await page.goto('https://test.k6.io/');
    const req = res.request();
  } finally {
    await page.close();
  }
}

Response

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

Response

Response represents a response received by the page.

Supported APIs

Method	Description
allHeaders()	Returns an object of headers associated to the response including headers added by the browser.
body()	Returns the response body.
frame()	The Frame that initiated the request which this response is associated to.
headers()	Returns an object of headers associated to the response.
headersArray()	An array with all the response HTTP headers.
headerValue(name)	Returns the value of the header matching the name. The name is case insensitive.
headerValues(name)	Returns all values of the headers matching the name, for example `set-cookie`. The name is case insensitive.
json()	Returns the JSON representation of response body.
ok()	Returns a `boolean` stating whether the response was successful or not.
request()	Returns the matching Request object.
securityDetails()	Returns SSL and other security information.
serverAddr()	Returns the IP address and port of the server for this response.
status()	Contains the status code of the response (e.g., 200 for a success).
statusText()	Contains the status text of the response (e.g. usually an “OK” for a success).
size()	The size of the response body and the headers.
text()	Returns the response body as a string.
url()	URL of the response.

Example

import { browser } from 'k6/browser';

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

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

  try {
    // Response returned once goto resolves.
    const res = await page.goto('https://test.k6.io/');
  } finally {
    await page.close();
  }
}

Route

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

Route

Route represents a network request intercepted by the page.route() function and allows to modify its behavior. Once routing is enabled, every request intercepted by a route will stall unless it’s continued, fulfilled or aborted.

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

Supported APIs

Method	Description
abort([errorCode])	Aborts the route’s request.
continue([options])	Continues the request with optional overrides.
fulfill([options])	Fulfills the request with the given response
request()	Returns the matching Request object.

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

Touchscreen

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

Touchscreen

The Touchscreen class allows to interact with a virtual touchscreen. A Touchscreen instance can be obtained by calling the page.touchscreen method.

Method	Description
tap()	Simulates a tap.

Worker

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

Worker

Represents a Web Worker or a Service Worker within the browser context.

Supported APIs

k6 Class	Description
url()	Returns the URL of the web worker.

import { browser } from 'k6/browser';

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

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

  try {
    await page.goto('https://test.k6.io/browser.php');
    console.log(page.workers());
  } finally {
    await page.close();
  }
}

close()

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

close()

Closes the connection to the browser, along with all of its BrowserContexts and Pages.

Calling this method is optional. k6 closes the connection at the end of the iteration either way, so use close() only when you want to release it earlier. Closing an already closed browser is a no-op.

Since you manage the browser, closing the connection doesn’t stop the browser itself, which keeps running and stays available to later iterations.

Using the browser after you close it throws an error, so treat close() as the last thing you do with it.

Returns

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

Example

import { chromium } from 'k6/browser';

export default async function () {
  const browser = await chromium.connectOverCDP(__ENV.CDP_WS_URL);
  const page = await browser.newPage();

  try {
    await page.goto('https://quickpizza.grafana.com/');
  } finally {
    await page.close();
    await browser.close(); // releases the connection, the browser keeps running
  }
}

browser.isConnected - Check whether the CDP connection is still active
chromium.connectOverCDP() - Attach to an existing browser over CDP

closeContext()

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

closeContext()

Closes the current BrowserContext. If there is no active browser context, because none has been created yet or because it has been previously closed, this method throws an error.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the `BrowserContext` 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 page1 = await browser.newPage({
    isMobile: true,
  }); // implicitly creates a new context

  await page1.goto('https:/test.k6.io/');
  page1.close();
  await browser.closeContext(); // closes the context created on newPage

  const page2 = await browser.newPage({
    isMobile: false,
  }); // creates a new context with different settings

  await page2.goto('https://test.k6.io/');
  page2.close();
  await browser.closeContext();

  await browser.closeContext(); // throws an error as browser has no active context
}

context()

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

context()

Returns the current BrowserContext.

Returns

Type	Description
object \| null	The current BrowserContext if one has been created, otherwise `null`.

Example

import { browser } from 'k6/browser';

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

export default async function () {
  console.log(browser.context()); // null

  const page1 = await browser.newPage(); // implicitly creates a new browserContext
  const context = browser.context(); // underlying live browserContext associated with browser
  const page2 = await context.newPage(); // shares the browserContext with page1

  page1.close();
  page2.close();
  await context.close();
}

isConnected()

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

isConnected()

Indicates whether the CDP connection to the browser process is active or not.

Returns

Type	Description
boolean	Returns `true` if the browser module is connected to the browser application. Otherwise, returns `false`.

Example

import { browser } from 'k6/browser';

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

export default function () {
  const isConnected = browser.isConnected();
  console.log(isConnected); // true
}

newContext([options])

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

newContext([options])

Creates and returns a new BrowserContext, if one hasn’t already been initialized for the Browser. If one has already been initialized an error is thrown.

Parameter	Type	Default	Description
options	object	`null`
options.bypassCSP	boolean	`false`	Whether to bypass a page’s Content-Security-Policy.
options.colorScheme	string	`'light'`	Whether to display a page in dark or light mode by emulating the ‘prefers-colors-scheme’ media feature. It can be one of `'light'`, `'dark'`, `'no-preference'`.
options.deviceScaleFactor	number	`1`	Sets the resolution ratio in physical pixels to the resolution in CSS pixels i.e. if set higher than `1`, then images will look sharper on high pixel density screens. See an example below.
options.extraHTTPHeaders	object	`null`	Contains additional HTTP headers to be sent with every request, where the keys are HTTP headers and values are HTTP header values.
options.geolocation	object	`null`	Sets the user’s geographical location.
options.geolocation.latitude	number	`0`	Latitude should be between `-90` and `90`.
options.geolocation.longitude	number	`0`	Longitude should be between `-180` and `180`.
options.geolocation.accuracy	number	`0`	Accuracy should only be a non-negative number. Defaults to `0`.
options.hasTouch	boolean	`false`	Whether to simulate a device with touch events.
options.httpCredentials	object	`null`	Sets the credentials for HTTP authentication using Basic Auth.
options.httpCredentials.username	string	`''`	Username to pass to the web browser for Basic HTTP Authentication.
options.httpCredentials.password	string	`''`	Password to pass to the web browser for Basic HTTP Authentication.
options.ignoreHTTPSErrors	boolean	`false`	Whether to ignore HTTPS errors that may be caused by invalid certificates.
options.isMobile	boolean	`false`	Whether to simulate a mobile device.
options.javaScriptEnabled	boolean	`true`	Whether to activate JavaScript support for the context.
options.locale	string	system	Specifies the user’s locale, such as `'en-US'`, `'tr-TR'`, etc.
options.offline	boolean	`false`	Whether to emulate an offline network.
options.permissions	Array	`null`	Permissions to grant for the context’s pages. See browserContext.grantPermissions() for the options.
options.proxy	object	`null`	Network proxy settings to use for all pages in the context. See an example below.
options.proxy.server	string	-	Proxy server URL, including scheme and port, for example `http://proxy.test:8080`. Required when `proxy` is set.
options.proxy.bypass	string	-	Comma-separated list of hosts to connect to directly, bypassing the proxy, for example `localhost,127.0.0.1`.
options.reducedMotion	string	`'no-preference'`	Minimizes the amount of motion by emulating the ‘prefers-reduced-motion’ media feature. It can be one of `'reduce'` and `'no-preference'`. See page.emulateMedia() for the options.
options.screen	object	`{'width': 1280, 'height': 720}`	Sets a window screen size for all pages in the context. It can only be used when the viewport is set.
options.screen.width	number	`1280`	Page width in pixels.
options.screen.height	number	`720`	Page height in pixels.
options.timezoneID	string	system	Changes the context’s timezone. See ICU’s metaZones.txt for a list of supported timezone IDs.
options.userAgent	string	browser	Specifies the user agent to use in the context.
options.viewport	object	`{'width': 1280, 'height': 720}`	Sets a viewport size for all pages in the context. `null` disables the default viewport.
options.viewport.width	number	`1280`	Page width in pixels.
options.viewport.height	number	`720`	Page height in pixels.

Returns

Type	Description
`Promise<BrowserContext>`	A Promise that fulfills with a `BrowserContext` object.

deviceScaleFactor 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({
    viewport: {
      width: 375,
      height: 812,
    },
    deviceScaleFactor: 3,
  });
  const page = await context.newPage();

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

proxy example

Route the context’s traffic through a proxy server:

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({
    proxy: {
      server: 'http://proxy.test:8080',
      bypass: 'localhost,127.0.0.1',
    },
  });
  const page = await context.newPage();

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

newPage([options])

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

newPage([options])

Creates and returns a new Page in a new BrowserContext if a BrowserContext hasn’t already been initialized for the Browser. If a BrowserContext has already been initialized an error is thrown.

Parameter	Type	Default	Description
options	object	`null`
options.bypassCSP	boolean	`false`	Whether to bypass a page’s Content-Security-Policy.
options.colorScheme	string	`'light'`	Whether to display a page in dark or light mode by emulating the ‘prefers-colors-scheme’ media feature. It can be one of `'light'`, `'dark'`, `'no-preference'`.
options.deviceScaleFactor	number	`1`	Sets the resolution ratio in physical pixels to the resolution in CSS pixels i.e. if set higher than `1`, then images will look sharper on high pixel density screens. See an example below.
options.extraHTTPHeaders	object	`null`	Contains additional HTTP headers to be sent with every request, where the keys are HTTP headers and values are HTTP header values.
options.geolocation	object	`null`	Sets the user’s geographical location.
options.geolocation.latitude	number	`0`	Latitude should be between `-90` and `90`.
options.geolocation.longitude	number	`0`	Longitude should be between `-180` and `180`.
options.geolocation.accuracy	number	`0`	Accuracy should only be a non-negative number. Defaults to `0`.
options.hasTouch	boolean	`false`	Whether to simulate a device with touch events.
options.httpCredentials	object	`null`	Sets the credentials for HTTP authentication using Basic Auth.
options.httpCredentials.username	string	`''`	Username to pass to the web browser for Basic HTTP Authentication.
options.httpCredentials.password	string	`''`	Password to pass to the web browser for Basic HTTP Authentication.
options.ignoreHTTPSErrors	boolean	`false`	Whether to ignore HTTPS errors that may be caused by invalid certificates.
options.isMobile	boolean	`false`	Whether to simulate a mobile device.
options.javaScriptEnabled	boolean	`true`	Whether to activate JavaScript support for the context.
options.locale	string	system	Specifies the user’s locale, such as `'en-US'`, `'tr-TR'`, etc.
options.offline	boolean	`false`	Whether to emulate an offline network.
options.permissions	Array	`null`	Permissions to grant for the context’s pages. See browserContext.grantPermissions() for the options.
options.proxy	object	`null`	Network proxy settings to use for the page’s context.
options.proxy.server	string	-	Proxy server URL, including scheme and port, for example `http://proxy.test:8080`. Required when `proxy` is set.
options.proxy.bypass	string	-	Comma-separated list of hosts to connect to directly, bypassing the proxy, for example `localhost,127.0.0.1`.
options.reducedMotion	string	`'no-preference'`	Minimizes the amount of motion by emulating the ‘prefers-reduced-motion’ media feature. It can be one of `'reduce'` and `'no-preference'`. See page.emulateMedia() for the options.
options.screen	object	`{'width': 1280, 'height': 720}`	Sets a window screen size for all pages in the context. It can only be used when the viewport is set.
options.screen.width	number	`1280`	Page width in pixels.
options.screen.height	number	`720`	Page height in pixels.
options.timezoneID	string	system	Changes the context’s timezone. See ICU’s metaZones.txt for a list of supported timezone IDs.
options.userAgent	string	browser	Specifies the user agent to use in the context.
options.viewport	object	`{'width': 1280, 'height': 720}`	Sets a viewport size for all pages in the context. `null` disables the default viewport.
options.viewport.width	number	`1280`	Page width in pixels.
options.viewport.height	number	`720`	Page height in pixels.

Returns

Type	Description
`Promise<Page>`	A Promise that fulfills with a `Page` object.

deviceScaleFactor 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({
    viewport: {
      width: 375,
      height: 812,
    },
    deviceScaleFactor: 3,
  });

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

page.on("requestfailed")

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

page.on(“requestfailed”)

Subscribe to the requestfailed event, which fires when a network request fails to reach the server.

This event is triggered when requests encounter network-level failures such as DNS errors, connection refused, timeouts, or other network problems. It does not fire for HTTP 4xx/5xx responses, which are considered successful network requests.

Parameter	Type	Description
event	string	The event name: `"requestfailed"`
handler	function	A callback function that receives a Request object

Handler Parameters

Parameter	Type	Description
request	Request	The failed Request object

Request Object Properties

The handler receives a Request object with the following useful properties:

Property	Type	Description
request.url()	string	The URL of the request
request.method()	string	The HTTP method (GET, POST, PUT, DELETE, etc.)
request.resourceType()	string	The type of resource (document, stylesheet, image, etc.)
request.failure()	object	Information about the failure (see below)

Request Failure Information

The request.failure() method returns an object with the following property:

Property	Type	Description
failure.errorText	string	Text describing the error that caused the request to fail

Examples

Basic usage

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

Monitoring for specific failure types

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 connection timeout failures specifically
  const timeoutFailures = [];

  page.on('requestfailed', (request) => {
    const failure = request.failure();
    if (failure && failure.errorText.toLowerCase().includes('timeout')) {
      timeoutFailures.push({
        url: request.url(),
        error: failure.errorText,
        timestamp: new Date().toISOString(),
      });

      console.log(`Timeout: ${failure.errorText} for ${request.url()}`);
    }
  });

  // Perform actions that might cause timeouts
  await page.goto('https://test.k6.io/');

  console.log(`Timeout failures: ${timeoutFailures.length}`);

  await page.close();
}

Best practices

Setup before navigation: Always set up the event listener before performing actions that trigger network requests:

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

  // CORRECT: Setup event listener before navigation
  page.on('requestfailed', (request) => {
    console.log(`Request failed: ${request.method()} ${request.url()}`);
  });
  await page.goto('https://example.com');

  await page.close();
}

If you set up the event listener after navigation, you may miss early failures:

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

  // INCORRECT: May miss early failures since navigation happens first
  await page.goto('https://example.com');
  page.on('requestfailed', (request) => {
    console.log(`Request failed: ${request.method()} ${request.url()}`);
  });

  await page.close();
}

Distinguish from other events:
- Use page.on('request') to track when requests are initiated
- Use page.on('response') to track when responses start arriving
- Use page.on('requestfinished') to track when requests successfully complete
- Use page.on('requestfailed') to track when requests fail at the network level
Error categorization: The failure.errorText can help categorize different types of network failures.
Monitoring: This event is valuable for identifying network infrastructure issues during browser automation tests.

page.on() - Register handlers for page events
page.on(“request”) - Subscribe to request initiation events
page.on(“response”) - Subscribe to response start events
page.on(“requestfinished”) - Subscribe to request completion events
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
Request - Request object methods and properties

page.on("requestfinished")

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

page.on(“requestfinished”)

Subscribe to the requestfinished event, which fires when a network request successfully completes (receives a response).

This event is triggered after the response is fully received, making it useful for tracking completed network activity, measuring request durations, or collecting statistics about successful requests.

Parameter	Type	Description
event	string	The event name: `"requestfinished"`
handler	function	A callback function that receives a Request object

Handler Parameters

Parameter	Type	Description
request	Request	The completed Request object

Request Object Properties

The handler receives a Request object with the following useful properties:

Property	Type	Description
request.url()	string	The URL of the request
request.method()	string	The HTTP method (GET, POST, PUT, DELETE, etc.)
request.resourceType()	string	The type of resource (document, stylesheet, image, etc.)
request.isNavigationRequest()	boolean	Whether this request is a navigation request

Examples

Basic usage

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

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

  await page.close();
}

Tracking API requests

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 API requests specifically
  const apiRequests = [];

  page.on('requestfinished', (request) => {
    if (request.url().includes('/api/')) {
      apiRequests.push({
        url: request.url(),
        method: request.method(),
        timestamp: new Date().toISOString(),
      });
    }
  });

  // Navigate to a page that might trigger API calls
  await page.goto('https://test.k6.io/');

  // Wait for a bit to allow any API requests to complete
  await page.waitForTimeout(2000);

  console.log(`API requests completed: ${apiRequests.length}`);

  await page.close();
}

Best practices

Setup before navigation: Always set up the event listener before performing actions that trigger network requests:

// Correct
page.on('requestfinished', handler);
await page.goto('https://example.com');

// Incorrect - may miss early requests
await page.goto('https://example.com');
page.on('requestfinished', handler);

Distinguish from other events:
- Use page.on('request') to track when requests are initiated
- Use page.on('response') to track when responses start arriving
- Use page.on('requestfinished') to track when requests completely finish
Performance monitoring: This event is ideal for measuring actual request completion times and tracking network performance.

page.on() - Register handlers for page events
page.on(“request”) - Subscribe to request initiation events
page.on(“response”) - Subscribe to response start events
page.on(“requestfailed”) - Subscribe to request failure events
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
Request - Request object methods and properties

version()

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

version()

Returns the browser application’s version.

Returns

Type	Description
string	The browser application’s version.

Example

import { browser } from 'k6/browser';

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

export default function () {
  const version = browser.version();
  console.log(version); // 105.0.5195.52
}

k6/browser on Grafana Labs

BrowserContext

BrowserContext

Chromium

Chromium

ConsoleMessage

ConsoleMessage

Supported APIs

MetricMessage

MetricMessage

tag

Example Usage

ElementHandle

ElementHandle

Examples

Frame

Frame

JSHandle

JSHandle

Supported APIs

Example

Keyboard

Keyboard

Example

Locator

Locator

Example

FrameLocator

FrameLocator

Mouse

Mouse

Example

Page

Page

Request

Request

Supported APIs

Example

Response

Response

Supported APIs

Example

Route

Route

Supported APIs

Example

Touchscreen

Touchscreen

Worker

Worker

Supported APIs

close()

close()

Returns

Example

Related

closeContext()

closeContext()

Returns

Example

context()

context()

Returns

Example

isConnected()

isConnected()

Returns

Example

newContext([options])

newContext([options])

Returns

deviceScaleFactor example

proxy example

newPage([options])

newPage([options])

Returns

deviceScaleFactor example

page.on("requestfailed")

page.on(“requestfailed”)

Handler Parameters