browser

Experimental module

While we intend to keep experimental modules as stable as possible, we may need to introduce breaking changes. This could happen at future k6 releases until the module becomes fully stable and graduates as a k6 core module. For more information, refer to the extension graduation process.

Experimental modules maintain a high level of stability and follow regular maintenance and security measures. Feel free to open an issue if you have any feedback or suggestions.

The browser module APIs aim for rough compatibility with the Playwright API for NodeJS.

Note that because k6 does not run in NodeJS, the browser module APIs will slightly differ from their Playwright counterparts.

You can find examples of using the browser module API in our getting started guide.

note

To work with the browser module, make sure you are using the latest k6 version.

Properties

The table below lists the properties you can import from the browser module ('k6/experimental/browser').

Browser Module API

The browser module is the entry point for all your tests, and it is what interacts with the actual web browser via Chrome DevTools Protocol (CDP). It manages:

• BrowserContext which is where you can set a variety of attributes to control the behavior of pages;
• and Page which is where your rendered site is displayed.

Example

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

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

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

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

Then, you can run the test with this command. Also, see the browser module options for customizing the browser module's behavior using environment variables.

$ k6 run script.js

Browser-level APIs

Browser Module Options

You can customize the behavior of the browser module by providing browser options as environment variables.

The following command passes the browser module options as environment variables to launch a headful browser with custom arguments.

$ K6_BROWSER_HEADLESS=false K6_BROWSER_ARGS='show-property-changed-rects' k6 run script.js

Default arguments

List of default arguments included when launching the browser process. You can pass one or more of the arguments to the K6_BROWSER_IGNORE_DEFAULT_ARGS environment variable when starting a test for the ones you want to ignore.

note

The starting '--' have been omitted from the argument names in these lists.

Additionally if headless mode is set to true in browser options, the following arguments are also set:

Devices Example

To emulate the browser behaviour on a mobile device and approximately measure the browser performance, you can import devices from k6/experimental/browser.

1import { browser, devices } from 'k6/experimental/browser';
2
3export const options = {
4  scenarios: {
5    browser: {
6      executor: 'shared-iterations',
7      options: {
8        browser: {
9            type: 'chromium',
10        },
11      },
12    },
13  },
14}
15
16export default async function () {
17  const iphoneX = devices['iPhone X'];
18  const context = browser.newContext(iphoneX);
19  const page = context.newPage();
20
21  try {
22    await page.goto('https://test.k6.io/');
23  } finally {
24    page.close();
25  }
26}