Skip to main content
The k6/browser module provides a browser automation API for running browser-based load tests. It uses the Chrome DevTools Protocol (CDP) to interact with Chromium-based browsers, enabling you to test real user workflows including page loads, interactions, and modern web features.

​
Overview

The browser module is inspired by Playwright and other frontend testing frameworks. It manages browser contexts and pages, allowing you to simulate real user behavior in performance tests.
Make sure you are using the latest k6 version to work with the browser module.

​
Importing the Module

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

​
Properties

​
browser
object
Entry point for all browser tests. Manages BrowserContext and Page instances via Chrome DevTools Protocol.
​
devices
object
Predefined emulation settings for many end-user devices. Use to simulate browser behavior on mobile devices.

​
Browser Module API

The browser module is the entry point for all your tests. It manages:
  • BrowserContext: Control browser behavior, set attributes, manage cookies and cache
  • Page: Display and interact with your rendered site

​
Methods

​
browser.closeContext()
function
Closes the current BrowserContext.
​
browser.context()
function
Returns the current BrowserContext.
​
browser.isConnected
boolean
Indicates whether the CDP connection to the browser process is active.
​
browser.newContext([options])
function
Creates and returns a new BrowserContext.Parameters:
  • options (optional): Configuration object for the browser context
​
browser.newPage([options])
function
Creates a new Page in a new BrowserContext and returns the page.Parameters:
  • options (optional): Configuration object for the page
Pages that have been opened should be closed using Page.close(). Pages left open could distort Web Vital metrics.
​
browser.version()
function
Returns the browser application’s version.

​
Browser-Level APIs

The following classes provide the browser automation functionality:
ClassDescription
BrowserContextEnables independent browser sessions with separate pages, cache, and cookies
ElementHandleRepresents an in-page DOM element
FrameAccess and interact with the Page’s frames
JSHandleRepresents an in-page JavaScript object
KeyboardSimulate keyboard interactions with the page
LocatorMakes it easier to work with dynamically changing elements
MouseSimulate mouse interactions with the page
PageProvides methods to interact with a single tab in a browser
RequestTrack requests made by the Page
ResponseRepresents the response received by the Page
TouchscreenSimulate touch interactions with the page
WorkerRepresents a WebWorker

​
Examples

​
Basic Browser Test

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
  thresholds: {
    checks: ['rate==1.0'],
  },
};

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

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

​
Running Browser Tests

k6 run script.js

​
Browser Module Options

Customize the browser module’s behavior using environment variables:
Environment VariableDescription
K6_BROWSER_ARGSAdditional arguments to pass to the browser
K6_BROWSER_HEADLESSRun browser in headless mode (default: true)
K6_BROWSER_TIMEOUTDefault timeout for browser operations

BrowserContext

Manage isolated browser sessions

Page

Interact with browser pages

Locator

Find and interact with elements

Browser Options

Configure browser behavior

Build docs developers (and LLMs) love

Get started for freeTalk to us