k6/browser

Browser automation API for browser-based load testing with k6

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:

Class	Description
BrowserContext	Enables independent browser sessions with separate pages, cache, and cookies
ElementHandle	Represents an in-page DOM element
Frame	Access and interact with the Page’s frames
JSHandle	Represents an in-page JavaScript object
Keyboard	Simulate keyboard interactions with the page
Locator	Makes it easier to work with dynamically changing elements
Mouse	Simulate mouse interactions with the page
Page	Provides methods to interact with a single tab in a browser
Request	Track requests made by the Page
Response	Represents the response received by the Page
Touchscreen	Simulate touch interactions with the page
Worker	Represents a WebWorker

Examples

Basic Browser Test

Basic Example

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

import { browser, devices } 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 iphoneX = devices['iPhone X'];
  const context = await browser.newContext(iphoneX);
  const page = await context.newPage();

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

Running Browser Tests

Linux/macOS

k6 run script.js

# WARNING: The grafana/k6:master-with-browser image launches Chrome 
# with 'no-sandbox' argument. Only use with trustworthy websites.
docker run --rm -i grafana/k6:master-with-browser run - <script.js

k6 run script.js

Browser Module Options

Customize the browser module’s behavior using environment variables:

Environment Variable	Description
K6_BROWSER_ARGS	Additional arguments to pass to the browser
K6_BROWSER_HEADLESS	Run browser in headless mode (default: true)
K6_BROWSER_TIMEOUT	Default timeout for browser operations

Related Resources

BrowserContext

Manage isolated browser sessions

Page

Interact with browser pages

Locator

Find and interact with elements

Browser Options

Configure browser behavior