Using k6 browser on Grafana Labs

Write your first browser test

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

Write your first browser test

k6 browser tests allow you to simulate real user interactions with web applications, such as clicking buttons, filling out forms, and verifying page content. This helps you test not only backend performance, but also frontend reliability and user experience.

In this guide, you’ll learn how to write your first k6 browser test script using the browser module.

Before you begin

To write and run k6 browser tests, you’ll need:

A basic knowledge of JavaScript or TypeScript.
A code editor to write your scripts, such as Visual Studio Code or JetBrains editors.
A Chromium-based browser (such as Google Chrome) installed locally.
Install k6 on your machine.

Basic structure of a k6 browser test

For k6 to be able to interpret and execute your test, every k6 script follows a common structure, revolving around a few core components:

Default function: This is where the test logic resides. It defines what your test will do and how it will behave during execution. It should be exported as the default function in your script. For browser scripts, it’s written as an async function to handle browser actions.
Imports: You can import additional k6 modules or JavaScript libraries (jslibs) to extend your script’s functionality, such as making HTTP requests. Note that k6 is not built upon Node.js, and instead uses its own JavaScript runtime. Compatibility with some npm modules may vary.
Options: Enable you to configure the execution of the test, such as defining the number of virtual users, the test duration, or setting performance thresholds. Refer to Options for more details.
Lifecycle operations (optional): Because your test might need to run code before and/or after the execution of the test logic, such as parsing data from a file, or download an object from Amazon S3, lifecycle operations allow you to write code, either as predefined functions or within specific code scopes, that will be executed at different stages of the test execution.

Key concepts

To write k6 browser tests, its important to understand a few key concepts:

Browser type: A browser script must have the options.browser.type field set in the options object. For example:
js
```
export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};
```
If that option isn’t set, k6 will throw an error when trying to execute your script.
Asynchronous operations: Browser interactions (like navigation and clicks) are asynchronous, so your test must use async/await. Refer to Asynchronous operations for more details.
Locators: The Locator API can be used to find and interact with elements on a page, such as buttons or headers. There are other ways to find elements, such as using the Page.$() method, but the Locator API provides several benefits, including finding an element even if the underlying frame navigates, and working with dynamic web pages and SPAs such as React.

Write your first browser test script

Let’s walk through creating a browser test that loads a page, clicks a button, takes a screenshot, and checks for recommendations.

Create a test file: A test file can be named anything you like, and live wherever you see fit in your project, but it should have a .js or .ts extension. In this example, create a JavaScript file named my-first-browser-test.js. Open your terminal and run the following command:
Bash
```
touch my-first-browser-test.js
```

Import k6 modules: Import the necessary modules for HTTP requests, browser automation, and utility functions.

import http from 'k6/http';
import exec from 'k6/execution';
import { browser } from 'k6/browser';
import { sleep, check, fail } from 'k6';

Define options: Configure the options object to use the browser executor and specify the browser type.

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

Setup function: Create a setup function to check if the target site is available, before running the main test logic.

export function setup() {
  let res = http.get(BASE_URL);
  if (res.status !== 200) {
    exec.test.abort(`Got unexpected status code ${res.status} when trying to setup. Exiting.`);
  }
}

Default function: The default exported function is the entry point for the test script. It will be executed repeatedly the number of times you define with the iterations option. In this function, using async/await, add the functions that open a browser page, interacts with the elements on the page, takes a screenshot, and performs a check:

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

  try {
    await page.goto(BASE_URL);

    checkData = await page.locator('h1').textContent();
    check(page, {
      header: checkData === 'Looking to break out of your pizza routine?',
    });

    await page.locator('//button[. = "Pizza, Please!"]').click();
    await page.waitForTimeout(500);

    await page.screenshot({ path: 'screenshot.png' });

    checkData = await page.locator('div#recommendations').textContent();
    check(page, {
      recommendation: checkData !== '',
    });
  } catch (error) {
    fail(`Browser iteration failed: ${error.message}`);
  } finally {
    await page.close();
  }

  sleep(1);
}

Your final script should look like this:

import http from 'k6/http';
import exec from 'k6/execution';
import { browser } from 'k6/browser';
import { sleep, check, fail } from 'k6';

const BASE_URL = __ENV.BASE_URL || 'https://quickpizza.grafana.com';

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

export function setup() {
  const res = http.get(BASE_URL);
  if (res.status !== 200) {
    exec.test.abort(`Got unexpected status code ${res.status} when trying to setup. Exiting.`);
  }
}

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

  try {
    await page.goto(BASE_URL);

    checkData = await page.locator('h1').textContent();
    check(page, {
      header: checkData === 'Looking to break out of your pizza routine?',
    });

    await page.locator('//button[. = "Pizza, Please!"]').click();
    await page.waitForTimeout(500);

    await page.screenshot({ path: 'screenshot.png' });

    checkData = await page.locator('div#recommendations').textContent();
    check(page, {
      recommendation: checkData !== '',
    });
  } catch (error) {
    fail(`Browser iteration failed: ${error.message}`);
  } finally {
    await page.close();
  }

  sleep(1);
}

Extending your browser test

Once you’re comfortable with the basics, you can extend your browser test by:

Simulating more complex user flows (multiple pages, form submissions, etc.).
Adding more checks and assertions to validate UI elements and content.
Creating hybrid performance tests to test both the frontend and backend simultaneously.

Refer to the Using k6 browser section for more details about the browser module and its features.

Next steps

Now that you’ve written your first k6 browser test script, it’s time to run it. Refer to Running k6 browser tests for instructions on executing your script and analyzing results.

Running browser tests

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

Running browser tests

Follow along to learn how to:

Run a test
Interact with elements on your webpage
Wait for page navigation
Run both browser-level and protocol-level tests in a single script

Run a test

To run a simple local script:

Copy the following code, paste it into your favorite editor, and save it as script.js.

Note that providing an executor and setting the browser scenario option’s type to chromium is mandatory. Please see the options and scenarios documentation for more information.
JavaScript
```
import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    ui: {
      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/');
    await page.screenshot({ path: 'screenshots/screenshot.png' });
  } finally {
    await page.close();
  }
}
```
The preceding code imports the browser the browser module), and uses its newPage method to open a new page.

After getting the page, you can interact with it using the Page methods. This example visits a test URL and takes a screenshot of the page.

Subsequently, the page is closed. This allows for the freeing up of allocated resources and enables the accurate calculation of Web Vital metrics.

Note
Starting from v0.52.0 the browser module API has been converted to an asynchronous API. That means that most of the methods now return promises. Refer to the migration guide to learn more about the changes and how to update your scripts.

Then, run the test on your terminal with this command:

k6 run script.js

# WARNING!
# The grafana/k6:master-with-browser image launches a Chrome browser by setting the
# 'no-sandbox' argument. Only use it with trustworthy websites.
#
# As an alternative, you can use a Docker SECCOMP profile instead, and overwrite the
# Chrome arguments to not use 'no-sandbox' such as:
# docker container run --rm -i -e K6_BROWSER_ARGS='' --security-opt seccomp=$(pwd)/chrome.json grafana/k6:master-with-browser run - <script.js
#
# You can find an example of a hardened SECCOMP profile in:
# https://raw.githubusercontent.com/jfrazelle/dotfiles/master/etc/docker/seccomp/chrome.json.
docker run --rm -i -v $(pwd):/home/k6/screenshots grafana/k6:master-with-browser run - <script.js

k6 run script.js

k6 run script.js

You can also use the browser module options to customize the launching of a browser process. For instance, you can start a headful browser using the previous test script with this command.

K6_BROWSER_HEADLESS=false k6 run script.js

# WARNING!
# The grafana/k6:master-with-browser image launches a Chrome browser by setting the
# 'no-sandbox' argument. Only use it with trustworthy websites.
#
# As an alternative, you can use a Docker SECCOMP profile instead, and overwrite the
# Chrome arguments to not use 'no-sandbox' such as:
# docker container run --rm -i -e K6_BROWSER_ARGS='' --security-opt seccomp=$(pwd)/chrome.json grafana/k6:master-with-browser run - <script.js
#
# You can find an example of a hardened SECCOMP profile in:
# https://raw.githubusercontent.com/jfrazelle/dotfiles/master/etc/docker/seccomp/chrome.json.
docker run --rm -i -v $(pwd):/home/k6/screenshots -e K6_BROWSER_HEADLESS=false grafana/k6:master-with-browser run - <script.js

set "K6_BROWSER_HEADLESS=false" && k6 run script.js

$env:K6_BROWSER_HEADLESS=false ; k6 run script.js

Note
When using Docker to run k6 browser tests, make sure you have pulled the correct image with Chromium built-in. See k6 Installation via Docker for more information.

Optional step: running browser tests in Docker on Mac computers with Apple Silicon:
1. Make sure you’re running the latest Docker version.
2. Update Rosetta and export an environment variable with the following:
  Bash
```
softwareupdate --install-rosetta &&
  export DOCKER_DEFAULT_PLATFORM=linux/amd64
```
3. Select VirtuoFS in Settings > General > VirtuoFS.
4. Enable the Rosetta emulation in Settings > Features in development > Use Rosetta for x86/amd64 emulation on Apple Silicon.
5. Restart Docker.
6. Run the browser image with the following command (adds the --platform flag):
  Bash
```
docker run --rm -i --platform linux/amd64 -v $(pwd):/home/k6/screenshots -e K6_BROWSER_HEADLESS=false grafana/k6:master-with-browser run - <script.js
```

How to write browser tests

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

How to write browser tests

Migrate a Playwright script to k6

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

Migrate a Playwright script to k6

Playwright is an end-to-end testing framework for modern web apps. You can use it for web testing across browsers, mobile web testing, API testing, and general-purpose browser automation.

You can convert your Playwright scripts to k6 browser scripts and use them in the following ways:

Run performance tests and frontend testing simultaneously in k6 OSS or Grafana Cloud k6 to see how your application behaves in real-world scenarios.
Use Synthetic Monitoring to ensure your application is monitored and working correctly on a consistent schedule.

In this guide, you’ll learn the key differences between Playwright and k6, and how to migrate your scripts.

Before you begin

To run a k6 test, you’ll need:

A machine with k6 installed.

Example migration

The following example shows a Playwright script and the common steps to migrate it to a k6 script:

import { test, expect } from '@playwright/test';

test('has title', async ({ page }) => {
  await page.goto('https://playwright.dev/');

  // Expect a title "to contain" a substring.
  await expect(page).toHaveTitle(/Playwright/);
});

Create a new file named pw-migrated.js and copy the following initial k6 script setup:

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';
import { browser } from 'k6/browser';

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

export default async function () {
    // Paste your test code here
}

k6 browser is an official module to run browser tests with k6. Any Playwright script that you migrate must include the import { browser } from 'k6/browser'; line at the top.

k6 browser doesn’t implement a test framework. Instead, the logic of test is handled inside the export default async function ().

Next, copy the contents from the test() function from the Playwright script into the k6 default async function ().

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';
import { browser } from 'k6/browser';

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

export default async function () {
  await page.goto('https://playwright.dev/');

  // Expect a title "to contain" a substring.
  await expect(page).toHaveTitle(/Playwright/);
}

k6 doesn’t implement fixtures like Playwright does. Instead, use the browser class to retrieve a page within its own context. After that, you can use the usual page methods such as goto or click:

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';
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(); // Create a new page in its own incognito context
  await page.goto('https://playwright.dev/');

  // Expect a title "to contain" a substring.
  await expect(page).toHaveTitle(/Playwright/);
}

Save your script, and then run it in your terminal:

k6 run pw-migrated.js

You should see an output similar to the following:

> k6 run pw-migrated.js

         /\      Grafana   /‾‾/  
    /\  /  \     |\  __   /  /   
   /  \/    \    | |/ /  /   ‾‾\ 
  /          \   |   (  |  (‾)  |
 / __________ \  |_|\_\  \_____/ 

     execution: local
        script: pw-migrated.js
        output: -

     scenarios: (100.00%) 1 scenario, 1 max VUs, 10m30s max duration (incl. graceful stop):
              * ui: 1 iterations shared among 1 VUs (maxDuration: 10m0s, gracefulStop: 30s)



  █ TOTAL RESULTS 

    EXECUTION
    iteration_duration..........: avg=1.81s    min=1.81s  med=1.81s   max=1.81s p(90)=1.81s    p(95)=1.81s  
    iterations..................: 1      0.463436/s
    vus.........................: 1      min=1       max=1
    vus_max.....................: 1      min=1       max=1

    NETWORK
    data_received...............: 0 B    0 B/s
    data_sent...................: 0 B    0 B/s

    BROWSER
    browser_data_received.......: 1.8 MB 829 kB/s
    browser_data_sent...........: 7.7 kB 3.6 kB/s
    browser_http_req_duration...: avg=120.89ms min=1.95ms med=98.73ms max=1.14s p(90)=139.67ms p(95)=263.7ms
    browser_http_req_failed.....: 0.00%  0 out of 23

    WEB_VITALS
    browser_web_vital_fcp.......: avg=1.24s    min=1.24s  med=1.24s   max=1.24s p(90)=1.24s    p(95)=1.24s  
    browser_web_vital_ttfb......: avg=1.14s    min=1.14s  med=1.14s   max=1.14s p(90)=1.14s    p(95)=1.14s  




running (00m02.2s), 0/1 VUs, 1 complete and 0 interrupted iterations
ui   ✓ [======================================] 1 VUs  00m02.2s/10m0s  1/1 shared iters

Migrate multiple tests

The following example shows a Playwright test file that contains two tests. To migrate multiple tests, use the k6 scenarios feature to create equivalent test logic:

import { test, expect } from '@playwright/test';

test('admin', async ({ page }) => {
  await page.goto('https://quickpizza.grafana.com/admin', {
    waitUntil: 'networkidle',
  });

  await page.getByLabel('username').fill('admin');
  await page.getByLabel('password').fill('admin');
  await page.getByRole('button', { name: 'Sign in' }).click()

  await page.getByRole('button', { name: 'Logout' }).waitFor()

  const label = page.locator('h2')
  const textContent = await label.textContent()
  expect(textContent).toEqual('Latest pizza recommendations');
});

test('user', async ({ page }) => {
  await page.goto('https://quickpizza.grafana.com/login', {
    waitUntil: 'networkidle',
  });

  await page.getByLabel('username').fill('default');
  await page.getByLabel('password').fill('12345678');
  await page.getByText('Sign in').click();

  await page.getByRole('button', { name: 'Logout' }).waitFor()

  const label = page.locator('h2')
  const textContent = await label.textContent()
  expect(textContent).toEqual('Your Pizza Ratings:');
});

To convert this Playwright script to k6, create a new file named pw-multiple-migrated.js.

First, create two scenarios and point them to two exported functions using the exec field in each scenario:

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';
import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    user: {
      exec: 'userLogin',
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
    admin: {
      exec: 'adminLogin',
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export async function adminLogin() {
    // Paste admin test code here
}

export async function userLogin() {
    // Paste user test code here
}

Next, copy the test code into the respective exported functions. Since k6 doesn’t have fixtures, use the imported browser object to create a newPage:

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';
import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    user: {
      exec: 'userLogin',
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
    admin: {
      exec: 'adminLogin',
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

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

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

  await page.getByLabel('username').fill('admin');
  await page.getByLabel('password').fill('admin');
  await page.getByRole('button', { name: 'Sign in' }).click()

  await page.getByRole('button', { name: 'Logout' }).waitFor()

  const label = page.locator('h2')
  const textContent = await label.textContent()
  expect(textContent).toEqual('Latest pizza recommendations');
}

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

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

  await page.getByLabel('username').fill('default');
  await page.getByLabel('password').fill('12345678');
  await page.getByText('Sign in').click();

  await page.getByRole('button', { name: 'Logout' }).waitFor()

  const label = page.locator('h2')
  const textContent = await label.textContent()
  expect(textContent).toEqual('Your Pizza Ratings:');
}

Run the test script:

k6 run pw-multiple-migrated.js

The command runs the two scenarios concurrently and produces output similar to the following:

         /\      Grafana   /‾‾/  
    /\  /  \     |\  __   /  /   
   /  \/    \    | |/ /  /   ‾‾\ 
  /          \   |   (  |  (‾)  |
 / __________ \  |_|\_\  \_____/ 

     execution: local
        script: pw-multiple-migrated.js
        output: -

     scenarios: (100.00%) 2 scenarios, 2 max VUs, 10m30s max duration (incl. graceful stop):
              * admin: 1 iterations shared among 1 VUs (maxDuration: 10m0s, exec: adminLogin, gracefulStop: 30s)
              * user: 1 iterations shared among 1 VUs (maxDuration: 10m0s, exec: userLogin, gracefulStop: 30s)



  █ TOTAL RESULTS 

    EXECUTION
    iteration_duration..........: avg=5.01s    min=4.7s     med=5.01s    max=5.33s    p(90)=5.26s    p(95)=5.3s    
    iterations..................: 2      0.333461/s
    vus.........................: 2      min=2       max=2
    vus_max.....................: 2      min=2       max=2

    NETWORK
    data_received...............: 0 B    0 B/s
    data_sent...................: 0 B    0 B/s

    BROWSER
    browser_data_received.......: 601 kB 100 kB/s
    browser_data_sent...........: 14 kB  2.3 kB/s
    browser_http_req_duration...: avg=489.58ms min=114.61ms med=514.78ms max=3.25s    p(90)=524.5ms  p(95)=534.85ms
    browser_http_req_failed.....: 0.00%  0 out of 46

    WEB_VITALS
    browser_web_vital_cls.......: avg=0.009527 min=0        med=0.009527 max=0.019055 p(90)=0.017149 p(95)=0.018102
    browser_web_vital_fcp.......: avg=3.09s    min=2.76s    med=3.09s    max=3.43s    p(90)=3.36s    p(95)=3.39s   
    browser_web_vital_fid.......: avg=200µs    min=199.99µs med=200µs    max=200µs    p(90)=200µs    p(95)=200µs   
    browser_web_vital_inp.......: avg=16ms     min=16ms     med=16ms     max=16ms     p(90)=16ms     p(95)=16ms    
    browser_web_vital_lcp.......: avg=3.09s    min=2.76s    med=3.09s    max=3.43s    p(90)=3.36s    p(95)=3.39s   
    browser_web_vital_ttfb......: avg=2.84s    min=2.43s    med=2.84s    max=3.25s    p(90)=3.17s    p(95)=3.21s   




running (00m06.0s), 0/2 VUs, 2 complete and 0 interrupted iterations
admin ✓ [======================================] 1 VUs  00m05.3s/10m0s  1/1 shared iters
user  ✓ [======================================] 1 VUs  00m06.0s/10m0s  1/1 shared iters

Key differences

Test isolation patterns

In k6, scenarios let you configure and model diverse workloads and organize your tests. Playwright has a dedicated testing framework. This difference stems from k6 being a performance testing tool.

Note
There are plans to create a testing framework in k6. For more details or to contribute, refer to this GitHub issue.

Metrics

k6 collects and reports on several built-in metrics, such as request and response times, data size, and more. It also includes support for Web Vital metrics, such as FCP, INP, and TTFB.

Refer to Built-in metrics for more details.

k6 concepts

To effectively use k6 for browser testing, it’s important to understand a few core concepts from its load testing foundation:

Virtual User: A Virtual User (VU) is an independent thread of execution that runs concurrently with other VUs. Scripts are often designed so that one VU represents the activity of one real user.
Iteration: The number of times a single VU runs the test script.
Thresholds and checks: Thresholds are pass/fail criteria that you configure for your test metrics. For example, you can configure a threshold to fail if more than 1% of requests return an error. Checks validate a boolean condition in your test. For example, you can check whether the response status code equals 200. The main difference is that unmet thresholds cause a test to finish with a failed status, while checks don’t. k6 also provides a k6-testing library that behaves similarly to assertions in Playwright. For more details, refer to the k6-testing documentation.

Browser context restrictions

Unlike Playwright, k6 can only work with a single browser context at a time. The following script fails when you run it with k6:

const bc1 = await browser.newContext();
// This next call results in an error: "existing browser context must be closed before creating a new one"
const bc2 = await browser.newContext();

To fix this, close the existing browser context before creating a new one.

Hybrid tests

Hybrid tests are performance tests that run browser-level and protocol-level requests simultaneously. They’re a great alternative to resource-intensive browser-based load testing, while still measuring application performance under load by making requests to both the frontend and backend.

Refer to Hybrid performance with k6 browser for more details.

Run k6 tests in Grafana Cloud

In addition to running k6 scripts locally by installing k6 on your machine, you can use Grafana Cloud for a seamless experience. Using Grafana Cloud means you don’t have to worry about whether your machine has the right resources to run a performance test. You also get pre-made Grafana dashboards to analyze test results and can collaborate with other team members to debug performance issues.

Refer to Run a test using Grafana Cloud k6 for more details.

References

k6 browser APIs
k6-testing library for Playwright-inspired assertions
Understand k6 CLI output results
Test lifecycle
k6 browser recommended practices

Playwright APIs in k6

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

Playwright APIs in k6

The following table shows which Playwright APIs are implemented in k6. k6 tries to match Playwright’s API behavior and signature exactly, but some differences may exist. For more details, refer to the individual API documentation page.

The status column has three different options:

Status	Description
🟩	Implemented in k6 Browser
🟥	Not implemented in k6 Browser
🟧	k6 Browser only

Note
If k6 is missing an API from Playwright that you need for your test, you can open an issue in the k6 GitHub repository.

Object	Method	Status	Alternate
Browser	addListener	🟥	None
Browser	browserType	🟥	None
Browser	close	🟩	Only on browsers returned by chromium.connectOverCDP
Browser	closeContext	🟧	-
Browser	context	🟧	-
Browser	contexts	🟥	browser.context
Browser	isConnected	🟩	-
Browser	newBrowserCDPSession	🟥	None
Browser	newContext	🟩	-
Browser	newPage	🟩	-
Browser	off	🟥	None
Browser	on	🟥	page.on
Browser	once	🟥	None
Browser	prependListener	🟥	None
Browser	removeAllListeners	🟥	None
Browser	removeListener	🟥	None
Browser	startTracing	🟥	None
Browser	stopTracing	🟥	None
Browser	userAgent	🟩	-
Browser	version	🟩	-
BrowserContext	addCookies	🟩	-
BrowserContext	addInitScript	🟩	-
BrowserContext	addListener	🟥	None
BrowserContext	backgroundPages	🟥	None
BrowserContext	browser	🟩	-
BrowserContext	clearCookies	🟩	-
BrowserContext	clearPermissions	🟩	-
BrowserContext	close	🟩	-
BrowserContext	cookies	🟩	-
BrowserContext	exposeBinding	🟥	None
BrowserContext	exposeFunction	🟥	None
BrowserContext	grantPermissions	🟩	-
BrowserContext	newCDPSession	🟥	None
BrowserContext	newPage	🟩	-
BrowserContext	off	🟥	None
BrowserContext	on	🟥	page.on
BrowserContext	once	🟥	None
BrowserContext	pages	🟩	-
BrowserContext	prependListener	🟥	None
BrowserContext	removeAllListeners	🟥	None
BrowserContext	removeListener	🟥	None
BrowserContext	route	🟥	page.route
BrowserContext	routeFromHAR	🟥	None
BrowserContext	routeWebSocket	🟥	None
BrowserContext	serviceWorkers	🟥	None
BrowserContext	setDefaultNavigationTimeout	🟩	-
BrowserContext	setDefaultTimeout	🟩	-
BrowserContext	setExtraHTTPHeaders	🟥	page.setExtraHTTPHeaders
BrowserContext	setGeolocation	🟩	-
BrowserContext	setHTTPCredentials	🟥	None
BrowserContext	setOffline	🟩	-
BrowserContext	storageState	🟥	None
BrowserContext	unroute	🟥	page.unroute
BrowserContext	unrouteAll	🟥	page.unrouteAll
BrowserContext	waitForEvent	🟩	-
BrowserType	connectOverCDP	🟩	-
ConsoleMessage	args	🟩	-
ConsoleMessage	location	🟥	None
ConsoleMessage	page	🟩	-
ConsoleMessage	text	🟩	-
ConsoleMessage	type	🟩	-
Dialog	accept	🟥	None
Dialog	defaultValue	🟥	None
Dialog	dismiss	🟥	None
Dialog	message	🟥	None
Dialog	page	🟥	None
Dialog	type	🟥	None
Download	cancel	🟥	None
Download	createReadStream	🟥	None
Download	delete	🟥	None
Download	failure	🟥	None
Download	page	🟥	None
Download	path	🟥	None
Download	saveAs	🟥	None
Download	suggestedFilename	🟥	None
Download	url	🟥	None
ElementHandle	$	🟩	-
ElementHandle	$$	🟩	-
ElementHandle	$$eval	🟥	None
ElementHandle	$eval	🟥	None
ElementHandle	asElement	🟩	-
ElementHandle	boundingBox	🟩	-
ElementHandle	check	🟩	-
ElementHandle	click	🟩	-
ElementHandle	contentFrame	🟩	-
ElementHandle	dblclick	🟩	-
ElementHandle	dispatchEvent	🟩	-
ElementHandle	dispose	🟩	-
ElementHandle	evaluate	🟩	-
ElementHandle	evaluateHandle	🟩	-
ElementHandle	fill	🟩	-
ElementHandle	focus	🟩	-
ElementHandle	getAttribute	🟩	-
ElementHandle	getProperties	🟩	-
ElementHandle	getProperty	🟥	elementHandle.getProperties
ElementHandle	hover	🟩	-
ElementHandle	innerHTML	🟩	-
ElementHandle	innerText	🟩	-
ElementHandle	inputValue	🟩	-
ElementHandle	isChecked	🟩	-
ElementHandle	isDisabled	🟩	-
ElementHandle	isEditable	🟩	-
ElementHandle	isEnabled	🟩	-
ElementHandle	isHidden	🟩	-
ElementHandle	isVisible	🟩	-
ElementHandle	jsonValue	🟩	-
ElementHandle	ownerFrame	🟩	-
ElementHandle	press	🟩	-
ElementHandle	screenshot	🟩	-
ElementHandle	scrollIntoViewIfNeeded	🟩	-
ElementHandle	selectOption	🟩	-
ElementHandle	selectText	🟩	-
ElementHandle	setChecked	🟩	-
ElementHandle	setInputFiles	🟩	-
ElementHandle	tap	🟩	-
ElementHandle	textContent	🟩	-
ElementHandle	type	🟩	-
ElementHandle	uncheck	🟩	-
ElementHandle	waitForElementState	🟩	-
ElementHandle	waitForSelector	🟩	-
FileChooser	element	🟥	None
FileChooser	isMultiple	🟥	None
FileChooser	page	🟥	None
FileChooser	setFiles	🟥	None
Frame	$	🟩	-
Frame	$$	🟩	-
Frame	$$eval	🟥	None
Frame	$eval	🟥	None
Frame	addScriptTag	🟥	None
Frame	addStyleTag	🟥	None
Frame	check	🟩	-
Frame	childFrames	🟩	-
Frame	click	🟩	-
Frame	content	🟩	-
Frame	dblclick	🟩	-
Frame	dispatchEvent	🟩	-
Frame	dragAndDrop	🟥	None
Frame	evaluate	🟩	-
Frame	evaluateHandle	🟩	-
Frame	fill	🟩	-
Frame	focus	🟩	-
Frame	frameElement	🟩	-
Frame	frameLocator	🟩	-
Frame	getAttribute	🟩	-
Frame	getByAltText	🟩	-
Frame	getByLabel	🟩	-
Frame	getByPlaceholder	🟩	-
Frame	getByRole	🟩	-
Frame	getByTestId	🟩	-
Frame	getByText	🟩	-
Frame	getByTitle	🟩	-
Frame	goto	🟩	-
Frame	hover	🟩	-
Frame	innerHTML	🟩	-
Frame	innerText	🟩	-
Frame	inputValue	🟩	-
Frame	isChecked	🟩	-
Frame	isDetached	🟩	-
Frame	isDisabled	🟩	-
Frame	isEditable	🟩	-
Frame	isEnabled	🟩	-
Frame	isHidden	🟩	-
Frame	isVisible	🟩	-
Frame	locator	🟩	-
Frame	name	🟩	-
Frame	page	🟩	-
Frame	parentFrame	🟩	-
Frame	press	🟩	-
Frame	selectOption	🟩	-
Frame	setChecked	🟩	-
Frame	setContent	🟩	-
Frame	setInputFiles	🟩	-
Frame	tap	🟩	-
Frame	textContent	🟩	-
Frame	title	🟩	-
Frame	type	🟩	-
Frame	uncheck	🟩	-
Frame	url	🟩	-
Frame	waitForFunction	🟩	-
Frame	waitForLoadState	🟩	-
Frame	waitForNavigation	🟩	-
Frame	waitForSelector	🟩	-
Frame	waitForTimeout	🟩	-
Frame	waitForURL	🟩	-
FrameLocator	first	🟥	None
FrameLocator	frameLocator	🟩	-
FrameLocator	getByAltText	🟩	-
FrameLocator	getByLabel	🟩	-
FrameLocator	getByPlaceholder	🟩	-
FrameLocator	getByRole	🟩	-
FrameLocator	getByTestId	🟩	-
FrameLocator	getByText	🟩	-
FrameLocator	getByTitle	🟩	-
FrameLocator	last	🟥	None
FrameLocator	locator	🟩	-
FrameLocator	nth	🟥	None
FrameLocator	owner	🟥	None
JSHandle	asElement	🟩	-
JSHandle	dispose	🟩	-
JSHandle	evaluate	🟩	-
JSHandle	evaluateHandle	🟩	-
JSHandle	getProperties	🟩	-
JSHandle	getProperty	🟥	jsHandle.getProperties
JSHandle	jsonValue	🟩	-
Keyboard	down	🟩	-
Keyboard	insertText	🟩	-
Keyboard	press	🟩	-
Keyboard	type	🟩	-
Keyboard	up	🟩	-
Locator	all	🟩	-
Locator	allInnerTexts	🟥	None
Locator	allTextContents	🟥	None
Locator	and	🟥	None
Locator	ariaSnapshot	🟥	None
Locator	blur	🟥	None
Locator	boundingBox	🟩	-
Locator	check	🟩	-
Locator	clear	🟩	-
Locator	click	🟩	-
Locator	contentFrame	🟩	-
Locator	count	🟩	-
Locator	dblclick	🟩	-
Locator	dispatchEvent	🟩	-
Locator	dragTo	🟥	None
Locator	elementHandle	🟥	None
Locator	elementHandles	🟥	None
Locator	evaluate	🟩	-
Locator	evaluateAll	🟥	None
Locator	evaluateHandle	🟩	-
Locator	fill	🟩	-
Locator	filter	🟩	-
Locator	first	🟩	-
Locator	focus	🟩	-
Locator	frameLocator	🟩	-
Locator	getAttribute	🟩	-
Locator	getByAltText	🟩	-
Locator	getByLabel	🟩	-
Locator	getByPlaceholder	🟩	-
Locator	getByRole	🟩	-
Locator	getByTestId	🟩	-
Locator	getByText	🟩	-
Locator	getByTitle	🟩	-
Locator	highlight	🟥	None
Locator	hover	🟩	-
Locator	innerHTML	🟩	-
Locator	innerText	🟩	-
Locator	inputValue	🟩	-
Locator	isChecked	🟩	-
Locator	isDisabled	🟩	-
Locator	isEditable	🟩	-
Locator	isEnabled	🟩	-
Locator	isHidden	🟩	-
Locator	isVisible	🟩	-
Locator	last	🟩	-
Locator	locator	🟩	-
Locator	nth	🟩	-
Locator	or	🟥	None
Locator	page	🟥	None
Locator	press	🟩	-
Locator	pressSequentially	🟥	None
Locator	screenshot	🟥	None
Locator	scrollIntoViewIfNeeded	🟥	None
Locator	selectOption	🟩	-
Locator	selectText	🟥	None
Locator	setChecked	🟩	-
Locator	setInputFiles	🟥	None
Locator	tap	🟩	-
Locator	textContent	🟩	-
Locator	type	🟩	-
Locator	uncheck	🟩	-
Locator	waitFor	🟩	-
Mouse	click	🟩	-
Mouse	dblclick	🟩	-
Mouse	down	🟩	-
Mouse	move	🟩	-
Mouse	up	🟩	-
Mouse	wheel	🟥	None
Page	$	🟩	-
Page	$$	🟩	-
Page	$$eval	🟥	None
Page	$eval	🟥	None
Page	addInitScript	🟥	browserContext.addInitScript
Page	addListener	🟥	None
Page	addLocatorHandler	🟥	None
Page	addScriptTag	🟥	None
Page	addStyleTag	🟥	None
Page	bringToFront	🟩	-
Page	check	🟩	-
Page	click	🟩	-
Page	close	🟩	-
Page	content	🟩	-
Page	context	🟩	-
Page	dblclick	🟩	-
Page	dispatchEvent	🟩	-
Page	dragAndDrop	🟥	None
Page	emulateMedia	🟩	-
Page	emulateVisionDeficiency	🟧	-
Page	evaluate	🟩	-
Page	evaluateHandle	🟩	-
Page	exposeBinding	🟥	None
Page	exposeFunction	🟥	None
Page	fill	🟩	-
Page	focus	🟩	-
Page	frame	🟥	None
Page	frameLocator	🟩	-
Page	frames	🟩	-
Page	getAttribute	🟩	-
Page	getByAltText	🟩	-
Page	getByLabel	🟩	-
Page	getByPlaceholder	🟩	-
Page	getByRole	🟩	-
Page	getByTestId	🟩	-
Page	getByText	🟩	-
Page	getByTitle	🟩	-
Page	goBack	🟥	None
Page	goForward	🟥	None
Page	goto	🟩	-
Page	hover	🟩	-
Page	innerHTML	🟩	-
Page	innerText	🟩	-
Page	inputValue	🟩	-
Page	isChecked	🟩	-
Page	isClosed	🟩	-
Page	isDisabled	🟩	-
Page	isEditable	🟩	-
Page	isEnabled	🟩	-
Page	isHidden	🟩	-
Page	isVisible	🟩	-
Page	locator	🟩	-
Page	mainFrame	🟩	-
Page	off	🟥	None
Page	on	🟩	-
Page	once	🟥	None
Page	opener	🟩	-
Page	pause	🟥	None
Page	pdf	🟥	None
Page	prependListener	🟥	None
Page	press	🟩	-
Page	reload	🟩	-
Page	removeAllListeners	🟥	None
Page	removeListener	🟥	None
Page	removeLocatorHandler	🟥	None
Page	requestGC	🟥	None
Page	route	🟩	-
Page	routeFromHAR	🟥	None
Page	routeWebSocket	🟥	None
Page	screenshot	🟩	-
Page	selectOption	🟩	-
Page	setChecked	🟩	-
Page	setContent	🟩	-
Page	setDefaultNavigationTimeout	🟩	-
Page	setDefaultTimeout	🟩	-
Page	setExtraHTTPHeaders	🟩	-
Page	setInputFiles	🟩	-
Page	setViewportSize	🟩	-
Page	tap	🟩	-
Page	textContent	🟩	-
Page	throttleCPU	🟧	-
Page	throttleNetwork	🟧	-
Page	title	🟩	-
Page	type	🟩	-
Page	uncheck	🟩	-
Page	unroute	🟩	-
Page	unrouteAll	🟩	-
Page	url	🟩	-
Page	video	🟥	None
Page	viewportSize	🟩	-
Page	waitForEvent	🟥	None
Page	waitForFunction	🟩	-
Page	waitForLoadState	🟩	-
Page	waitForNavigation	🟩	-
Page	waitForRequest	🟩	-
Page	waitForResponse	🟩	-
Page	waitForSelector	🟩	-
Page	waitForTimeout	🟩	-
Page	waitForURL	🟩	-
Page	workers	🟩	-
Request	allHeaders	🟩	-
Request	failure	🟥	None
Request	frame	🟩	-
Request	headerValue	🟩	-
Request	headers	🟩	-
Request	headersArray	🟩	-
Request	isNavigationRequest	🟩	-
Request	method	🟩	-
Request	postData	🟩	-
Request	postDataBuffer	🟩	-
Request	postDataJSON	🟥	None
Request	redirectedFrom	🟥	None
Request	redirectedTo	🟥	None
Request	resourceType	🟩	-
Request	response	🟩	-
Request	serviceWorker	🟥	None
Request	size	🟧	-
Request	sizes	🟥	request.size
Request	timing	🟩	-
Request	url	🟩	-
Response	allHeaders	🟩	-
Response	body	🟩	-
Response	finished	🟥	None
Response	frame	🟩	-
Response	fromServiceWorker	🟥	None
Response	headerValue	🟩	-
Response	headerValues	🟩	-
Response	headers	🟩	-
Response	headersArray	🟩	-
Response	json	🟩	-
Response	ok	🟩	-
Response	request	🟩	-
Response	securityDetails	🟩	-
Response	serverAddr	🟩	-
Response	size	🟧	-
Response	status	🟩	-
Response	statusText	🟩	-
Response	text	🟥	None
Response	url	🟩	-
Route	abort	🟩	-
Route	continue	🟩	-
Route	fallback	🟥	None
Route	fetch	🟥	None
Route	fulfill	🟩	-
Route	request	🟩	-
Touchscreen	tap	🟩	-
Worker	addListener	🟥	None
Worker	evaluate	🟥	None
Worker	evaluateHandle	🟥	None
Worker	off	🟥	None
Worker	on	🟥	None
Worker	once	🟥	None
Worker	prependListener	🟥	None
Worker	removeListener	🟥	None
Worker	url	🟩	-

Recommended practices

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

Recommended practices

This section presents some examples and recommended practices when working with the k6 browser module to leverage browser automation as part of your k6 tests.

Browser metrics

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

Browser metrics

Follow along to learn about:

Google’s Core Web Vitals and why they are important
How to analyze the browser metrics output
How to set thresholds for your browser metrics
How to use the Performance API to measure web performance.

Google’s Core Web Vitals

The k6 browser module emits metrics based on the Core Web Vitals.

Google introduced these metrics to provided unified signals to assess user experience on the web. The vitals are composed of three important metrics to help user experience when using your web application.

Loading performance
Interactivity
And visual stability

Why web vitals

The Core Web Vitals are one of Google’s Page Experience Signals. A positive page experience naturally leads to better quality and better search engine rankings. These golden metrics help you understand which areas of your frontend application need optimization so your pages can rank higher than similar content.

Existing browser measures, such as Load and DOMContentLoaded times, no longer accurately reflect user experience very well. Relying on these load events does not give the correct metric to analyze critical performance bottlenecks that your page might have. Google’s Web Vitals is a better measure of your page performance and its user experience.

Browser metrics

The following Core Web Vital metrics are collected when using the k6 browser module.

Metric name	Description
browser_web_vital_cls	Measures the visual stability on a webpage by quantifying the amount of unexpected layout shift of visible page content. Refer to Cumulative Layout Shift for more information.
browser_web_vital_inp	A metric that measures a page’s responsiveness. Refer to Interaction to Next Paint for more information.
browser_web_vital_lcp	Measures the time it takes for the largest content element on a page to become visible. Refer to Largest Contentful Paint for more information.

Additionally, k6 also collects other Web Vital metrics.

Metric name	Description
browser_web_vital_fcp	Measures the time it takes for the browser to render the first DOM element on the page, whether that’s a text, image or header. Refer to First Contentful Paint for more information.
browser_web_vital_ttfb	Measures the time it takes between the browser request and the start of the response from a server. Refer to Time to First Byte for more information.

To review the complete list of k6 metrics, refer to the Metrics reference.

Understanding the browser metrics output

When a browser test finishes, k6 reports a top-level overview of the aggregated browser metrics output. The following snippet is an example:

Note
As Google also recommends measuring the 75th percentile for each web vital metric, there will still be future tweaks to improve the summary output.

  browser_data_received.......: 2.6 kB  2.0 kB/s
  browser_data_sent...........: 1.9 kB  1.5 kB/s
  browser_http_req_duration...: avg=215.4ms  min=124.9ms med=126.65ms max=394.64ms p(90)=341.04ms p(95)=367.84ms
  browser_http_req_failed.....: 0.00%   ✓ 0        ✗ 3
  browser_web_vital_cls.......: avg=0        min=0       med=0        max=0        p(90)=0        p(95)=0
  browser_web_vital_fcp.......: avg=344.15ms min=269.2ms med=344.15ms max=419.1ms  p(90)=404.11ms p(95)=411.6ms
  browser_web_vital_inp.......: avg=8ms      min=8ms     med=8ms      max=8ms      p(90)=8ms      p(95)=8ms
  browser_web_vital_lcp.......: avg=419.1ms  min=419.1ms med=419.1ms  max=419.1ms  p(90)=419.1ms  p(95)=419.1ms
  browser_web_vital_ttfb......: avg=322.4ms  min=251ms   med=322.4ms  max=393.8ms  p(90)=379.52ms p(95)=386.66ms

You can also visualize these results in different ways depending on your team’s needs. For more information, check out our blog post on visualizing k6 results.

Web vitals across page navigations

Starting with k6 v2.3.0, browser web vital aggregates include measurements from intermediate pages when a test navigates between documents in the same tab. For example, a flow that visits a login page, an account page, and a detail page can report web vitals for each page, even if you close the tab only at the end. Earlier versions could lose LCP, CLS, and INP measurements from the intermediate pages.

Each page contributes one sample for each web vital it reports. k6 records the latest available value when the main frame navigates to another document or the page closes. Not every page reports every metric: for example, INP requires a qualifying user interaction. This improvement covers navigations that load a new document; it does not add support for measuring client-side route changes within a single-page application.

The additional intermediate-page samples can change averages and percentiles after you upgrade, even if the application’s performance has not changed. Use URL-specific thresholds to evaluate individual pages instead of only the aggregate across the flow.

Always await page.close() in a finally block, as shown in the custom metrics example, so the last page can finish reporting its measurements. An abrupt test termination can discard measurements that have not yet been emitted.

Set thresholds for your browser metrics

The browser module can use all key k6 functionalities, such as Thresholds.

To set thresholds for your browser metrics:

Add the metric you want to check.
Specify its threshold value.

As the following example shows, you can also pass in different URLs if you’re going to set a threshold for other pages, especially when your script contains page navigations.

Caution
By default, use URL tags to distinguish pages in thresholds. Group tags aren’t reliably applied to browser metrics, as described in #721.

When you enable the experimental async-metric-context feature flag, browser_data_sent, browser_data_received, browser_http_req_duration, and browser_http_req_failed keep a best-effort copy of the tags and metadata from the browser operation that initiated the request. This includes the group tag. The feature doesn’t change group attribution for other browser metrics.

export const options = {
  thresholds: {
    'browser_web_vital_lcp': ['p(90) < 1000'],
    'browser_web_vital_inp{url:https://test.k6.io/}': ['p(90) < 80'],
    'browser_web_vital_inp{url:https://test.k6.io/my_messages.php}': ['p(90) < 100'],
  },
};

When the test is run, you should see a similar output as the one below.

  browser_web_vital_inp..........................: avg=0s       min=0s       med=0s       max=0s       p(90)=0s       p(95)=0s
  ✓ { url:https://test.k6.io/ }..................: avg=0s       min=0s       med=0s       max=0s       p(90)=0s       p(95)=0s
  ✓ { url:https://test.k6.io/my_messages.php }...: avg=0s       min=0s       med=0s       max=0s       p(90)=0s       p(95)=0s
✓ browser_web_vital_lcp..........................: avg=460.1ms  min=460.1ms  med=460.1ms  max=460.1ms  p(90)=460.1ms  p(95)=460.1ms
  browser_web_vital_ttfb.........................: avg=339.3ms  min=258.9ms  med=339.3ms  max=419.7ms  p(90)=403.62ms p(95)=411.66ms

Measure custom metrics

When using the k6 browser page.evaluate function, you can call the Performance API to measure the performance of web applications. For example, if you want to measure the time it takes for your users to complete actions, such as a search feature, you can use the performance.mark method to add a timestamp in your browser’s performance timeline. Using the performance.measure method, you can also measure the time difference between two performance markers. The time duration that performance.measure returns can be added as a custom metric in k6 browser using Trends.

import { browser } from 'k6/browser';
import { Trend } from 'k6/metrics';

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

const myTrend = new Trend('total_action_time', true);

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

  try {
    await page.goto('https://test.k6.io/browser.php');
    await page.evaluate(() => window.performance.mark('page-visit'));

    await page.locator('#checkbox1').check();
    await page.locator('#counter-button').click();
    await page.locator('#text1').fill('This is a test');

    await page.evaluate(() => window.performance.mark('action-completed'));

    // Get time difference between visiting the page and completing the actions
    await page.evaluate(() =>
      window.performance.measure('total-action-time', 'page-visit', 'action-completed')
    );

    const totalActionTime = await page.evaluate(
      () =>
        JSON.parse(JSON.stringify(window.performance.getEntriesByName('total-action-time')))[0]
          .duration
    );

    myTrend.add(totalActionTime);
  } finally {
    await page.close();
  }
}

After you run the test, you should see a similar output as the one below.

  iteration_duration..........: avg=1.06s    min=1.06s    med=1.06s    max=1.06s    p(90)=1.06s    p(95)=1.06s
  iterations..................: 1      0.70866/s
  total_action_time.............: avg=295.3ms    min=295.3ms    med=295.3ms    max=295.3ms    p(90)=295.3ms    p(95)=295.3ms

Browser options

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

Browser options

To enable browser testing, add the browser configuration within the options property of the Scenario options.

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

Script options

Option	Description
type^(required)	Name of the browser running the test. Options include `'chromium'`.

Environment variable options

You can customize the behavior of the browser module by passing environment variables.

Note
Customizing browser options via environment variables is unsupported when running browser tests in Grafana Cloud k6.

Environment Variable	Description
K6_BROWSER_ARGS	Extra command line arguments to include when launching browser process. See the browser arguments for usage and common arguments.
K6_BROWSER_DEBUG	All CDP messages and internal fine grained logs will be logged if set to `true`.
K6_BROWSER_EXECUTABLE_PATH	Override search for browser executable in favor of specified absolute path.
K6_BROWSER_HEADLESS	Show browser GUI or not. `true` by default.
K6_BROWSER_IGNORE_DEFAULT_ARGS	Ignore any of the default arguments included when launching a browser process.
K6_BROWSER_TIMEOUT	Default timeout for initializing the connection to the browser instance. `'30s'` if not set.
K6_BROWSER_TRACES_METADATA	Sets additional key-value metadata that is included as attributes in every span generated from browser module traces. Example: `K6_BROWSER_TRACES_METADATA=attr1=val1,attr2=val2`. This only applies if traces generation is enabled, refer to Traces output for more details.

The following command passes the browser 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

# WARNING!
# The grafana/k6:master-with-browser image launches a Chrome browser by setting the
# 'no-sandbox' argument. Only use it with trustworthy websites.
#
# As an alternative, you can use a Docker SECCOMP profile instead, and overwrite the
# Chrome arguments to not use 'no-sandbox' such as:
# docker container run --rm -i -e K6_BROWSER_ARGS='' --security-opt seccomp=$(pwd)/chrome.json grafana/k6:master-with-browser run - <script.js
#
# You can find an example of a hardened SECCOMP profile in:
# https://raw.githubusercontent.com/jfrazelle/dotfiles/master/etc/docker/seccomp/chrome.json.
docker run --rm -i -e K6_BROWSER_HEADLESS=false -e K6_BROWSER_ARGS='show-property-changed-rects' grafana/k6:master-with-browser run - <script.js

set "K6_BROWSER_HEADLESS=false" && set "K6_BROWSER_ARGS='show-property-changed-rects' " && k6 run script.js

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

Browser arguments

The following table highlights commonly useful arguments you can pass via the K6_BROWSER_ARGS environment variable. Most tests run without extra arguments, because the browser module already uses sensible defaults. Set these extra arguments only when you need to debug or adapt to your environment. For a complete list, refer to Chromium command line switches.

Note
Arguments should not start with -- when passing them to K6_BROWSER_ARGS.

Argument	Type	Description
disable-web-security	boolean	Disables the same-origin policy. Useful when testing a site whose CORS configuration blocks the browser from interacting with cross-origin iframes or assets.
ignore-certificate-errors	boolean	Ignores TLS certificate errors. Useful when testing against hosts with self-signed or otherwise invalid certificates.
no-sandbox	boolean	Disables the Chromium sandbox. Needed when running as root inside Docker, CI, or Kubernetes. Only use with trustworthy targets.
proxy-server	string	Routes browser traffic through an HTTP or SOCKS proxy. Pass the proxy address (`host:port`) as the value. Useful for corporate proxies or inspecting traffic with tools like mitmproxy.

For example, pass the following arguments to the K6_BROWSER_ARGS environment variable to ignore TLS certificate errors and route browser traffic through a proxy when running a browser test:

K6_BROWSER_ARGS='ignore-certificate-errors,proxy-server=127.0.0.1:8080' k6 run script.js

docker run --rm -i -e K6_BROWSER_ARGS='ignore-certificate-errors,proxy-server=127.0.0.1:8080' grafana/k6:master-with-browser run - <script.js

set "K6_BROWSER_ARGS='ignore-certificate-errors,proxy-server=127.0.0.1:8080'" && k6 run script.js

$env:K6_BROWSER_ARGS='ignore-certificate-errors,proxy-server=127.0.0.1:8080' ; 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.

Argument	Value	Description
disable-background-networking	`true`	Disables several subsystems which run network requests in the background. This is used during network performance testing to avoid measurement noise.
enable-features	NetworkService, NetworkServiceInProcess	Comma-separated list of feature names to enable.
disable-background-timer-throttling	`true`	Disables task throttling of timer tasks from background pages.
disable-backgrounding-occluded-windows	`true`	Disables backgrounding renders for occluded windows. Done for tests to avoid nondeterministic behavior.
disable-breakpad	`true`	Disables the crash reporting.
disable-component-extensions -with-background-pages	`true`	Disables default component extensions with background pages. Useful for performance tests where these pages may interfere with results.
disable-default-apps	`true`	Disables the installation of default apps on the first run. This is used during automated testing.
disable-dev-shm-usage	`true`	The /dev/shm partition is too small in certain VM environments, causing Chrome to fail or crash. This flag provides a work-around for this issue (a temporary directory will always be used to create anonymous shared memory files).
disable-extensions	`true`	Disables extensions.
disable-features	ImprovedCookieControls, LazyFrameLoading, GlobalMediaControls, DestroyProfileOnBrowserClose, MediaRouter, AcceptCHFrame	Comma-separated list of feature names to disable.
disable-hang-monitor	`true`	Suppresses hang monitor dialogs in renderer processes. This may allow slow unload handlers on a page to prevent the tab from closing, but the Task Manager can be used to terminate the offending process in this case.
disable-ipc-flooding-protection	`true`	Disables the IPC flooding protection. It is activated by default. Some javascript functions can be used to flood the browser process with IPC. This protection limits the rate at which they can be used.
disable-popup-blocking	`true`	Disables pop-up blocking.
disable-prompt-on-repost	`true`	Usually, when the user attempts to navigate to a page that was the result of a post request, the browser prompts to make sure that’s the intention of the user. This switch may be used to disable that check during automated testing.
disable-renderer-backgrounding	`true`	Prevents renderer process backgrounding when set.
force-color-profile	`srgb`	Forces all monitors to be treated as though they have the specified color profile. Accepted values are “srgb” and “generic-rgb” (currently used by Mac layout tests) and “color-spin-gamma24” (used by layout tests).
metrics-recording-only	`true`	Enables the recording of metrics reports but disables reporting. This executes all the code that a normal client would use for reporting, except the report is dropped rather than sent to the server. This is useful for finding issues in the metrics code during UI and performance tests.
no-first-run	`true`	Skips the “First Run” tasks, whether or not it’s the first run, and the “What’s New” page. This does not drop the “First Run” sentinel and thus doesn’t prevent “First Run” from occurring the next time Chromium is launched without this flag. It also does not update the last “What’s New” milestone, so it does not prevent “What’s New” from occurring the next time Chromium is launched without this flag.
enable-automation	`true`	Enables indication that the browser is controlled by automation.
password-store	`basic`	Specifies which encryption storage backend to use. The possible values are kwallet, kwallet5, gnome, gnome-keyring, gnome-libsecret, and basic. Any other value will lead to Chromium detecting the best backend automatically.
use-mock-keychain	`true`	Uses mock keychain on Mac to prevent the blocking permissions dialog about: “Chrome wants to use your confidential information stored in your keychain.”
no-service-autorun	`true`	Disables the service process from adding itself as an autorun process. This does not delete existing autorun registrations, it just prevents the service from registering a new one.
no-startup-window	`true`	Does not automatically open a browser window on startup (used when launching Chrome for the purpose of hosting background apps).
no-default-browser-check	`true`	Disables the default browser check. Useful for UI/browser tests where we want to avoid having the default browser info-bar displayed.
headless	`true`/`false`	Run in headless mode, i.e., without a UI or display server dependencies. Set by `K6_BROWSER_HEADLESS` environment variable (default true).
window-size	`800,600`	Sets the initial window size. Provided as string in the format “800,600”.

Additionally, the following arguments are set in headless mode (when K6_BROWSER_HEADLESS is true, which is the default option):

Argument	Value	Description
hide-scrollbars	`true`	Prevents creating scrollbars for web content. Useful for taking consistent screenshots.
mute-audio	`true`	Mutes audio sent to the audio device so it is not audible during automated testing.
blink-settings	primaryHoverType=2,availableHoverTypes=2, primaryPointerType=4,availablePointerTypes=4	Sets blink settings. Format is <name>[=<value>],<name>[=<value>],… The names are declared in settings.json5 from chromium project. For boolean type, use “true”, “false”, or omit ‘=<value>’ part to set to true. For enum type, use the int value of the enum value.

Migrating browser scripts to k6 v0.52

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

Migrating browser scripts to k6 v0.52

This guide outlines the key changes you will need to make when moving your existing k6 experimental browser test scripts to the latest k6 browser module version bundled with k6 0.52.

Key changes

In the latest release of k6, we have graduated k6 browser module out of experimental and is now under the import k6/browser. Migrating to this is a breaking change that will affect all scripts that use the experimental k6 browser module. The breaking changes are:

Converted most of the k6 browser module APIs to asynchronous (async) APIs. That means they will return a promise that will resolve to a value when the API call succeeds or reject when an error occurs.
A side effect of making this async changes is that you will need to use the check utility function from jslib.k6.io instead of working with the k6 check API.
Finally, it’s also worth reiterating that the group API still doesn’t work with async APIs.

If you are interested in the rationale behind this change, refer to the v0.51 release notes.

Note
The experimental import (k6/experimental/browser) and the corresponding synchronous APIs will be supported up until the 23rd of September 2024.

Migrating to async

To ensure your scripts work with the latest release of the k6 browser module, you must:

Change the import from k6/experimental/browser to k6/browser.
Ensure that all the synchronous (sync) APIs that have been migrated over to async are handled appropriately. In most cases, you will only need to add await in front of the API call.

For example, before:

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

...

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

And now:

import { browser } from 'k6/browser';

...

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

You might have already encountered async APIs when working with the browser module, such as page.click, so the use of async and await keywords might be familiar to you.

Below is a screenshot of a comparison between a generic browser test in v0.51 and v0.52 to help visualize the change:

The affected APIs

Class	Method
Browser	closeContext
Browser	context
Browser	newContext
Browser	newPage
Browser	userAgent
BrowserContext	addCookies
BrowserContext	addInitScript
BrowserContext	browser
BrowserContext	clearCookies
BrowserContext	clearPermissions
BrowserContext	close
BrowserContext	cookies
BrowserContext	grantPermissions
BrowserContext	newPage
BrowserContext	setGeolocation
BrowserContext	setOffline
ElementHandle	$
ElementHandle	$$
ElementHandle	boundingBox
ElementHandle	check
ElementHandle	contentFrame
ElementHandle	dblclick
ElementHandle	dispatchEvent
ElementHandle	fill
ElementHandle	focus
ElementHandle	getAttribute
ElementHandle	hover
ElementHandle	innerHTML
ElementHandle	innerText
ElementHandle	inputValue
ElementHandle	isChecked
ElementHandle	isDisabled
ElementHandle	isEditable
ElementHandle	isEnabled
ElementHandle	isHidden
ElementHandle	isVisible
ElementHandle	ownerFrame
ElementHandle	press
ElementHandle	screenshot
ElementHandle	scrollIntoViewIfNeeded
ElementHandle	selectOption
ElementHandle	selectText
ElementHandle	setInputFiles
ElementHandle	tap
ElementHandle	textContent
ElementHandle	type
ElementHandle	uncheck
ElementHandle	waitForElementState
ElementHandle	waitForSelector
Frame	$
Frame	$$
Frame	check
Frame	content
Frame	dblclick
Frame	dispatchEvent
Frame	evaluate<R, Arg>
Frame	evaluateHandle<R, Arg>
Frame	fill
Frame	focus
Frame	frameElement
Frame	getAttribute
Frame	hover
Frame	innerHTML
Frame	innerText
Frame	inputValue
Frame	isChecked
Frame	isDisabled
Frame	isEditable
Frame	isEnabled
Frame	isHidden
Frame	isVisible
Frame	press
Frame	selectOption
Frame	setContent
Frame	setInputFiles
Frame	tap
Frame	textContent
Frame	title
Frame	type
Frame	uncheck
Frame	waitForLoadState
Frame	waitForSelector
Frame	waitForTimeout
JSHandle	asElement
JSHandle	dispose
JSHandle	evaluate<R, Arg>
JSHandle	evaluateHandle<R, Arg>
JSHandle	getProperties
JSHandle	jsonValue
Keyboard	down
Keyboard	insertText
Keyboard	press
Keyboard	type
Keyboard	up
Locator	check
Locator	clear
Locator	dblclick
Locator	dispatchEvent
Locator	fill
Locator	focus
Locator	getAttribute
Locator	hover
Locator	innerHTML
Locator	innerText
Locator	inputValue
Locator	isChecked
Locator	isDisabled
Locator	isEditable
Locator	isEnabled
Locator	isHidden
Locator	isVisible
Locator	press
Locator	selectOption
Locator	tap
Locator	textContent
Locator	type
Locator	uncheck
Locator	waitFor
Mouse	click
Mouse	dblclick
Mouse	down
Mouse	move
Mouse	up
Page	$
Page	$$
Page	bringToFront
Page	check
Page	close
Page	content
Page	dblclick
Page	dispatchEvent
Page	emulateMedia
Page	emulateVisionDeficiency
Page	evaluate<R, Arg>
Page	evaluateHandle<R, Arg>
Page	fill
Page	focus
Page	getAttribute
Page	hover
Page	innerHTML
Page	innerText
Page	inputValue
Page	isChecked
Page	isDisabled
Page	isEditable
Page	isEnabled
Page	isHidden
Page	isVisible
Page	on
Page	opener
Page	press
Page	reload
Page	screenshot
Page	selectOption
Page	setContent
Page	setExtraHTTPHeaders
Page	setInputFiles
Page	setViewportSize
Page	tap
Page	textContent
Page	throttleCPU
Page	throttleNetwork
Page	title
Page	type
Page	uncheck
Page	viewportSize
Page	waitForLoadState
Page	waitForSelector
Page	waitForTimeout
Request	allHeaders
Request	headerValue
Request	headersArray
Request	postData
Request	resourceType
Request	response
Request	size
Request	timing
Response	allHeaders
Response	body
Response	headerValue
Response	headerValues
Response	headersArray
Response	json
Response	securityDetails
Response	serverAddr
Response	size
Touchscreen	tap

Working with k6 check

The k6 check API will not await promises, so calling a function that returns a Promise, for example locator.textContent(), inside one of the predicates will not work. Instead, you can work with the jslib.k6.io’s check utility function.

For example, before:

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

And now:

import { check } from 'https://jslib.k6.io/k6-utils/1.5.0/index.js';

// ...

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

Groups

A note on groups, they don’t work with async APIs either, there is no workaround as of yet. Here’s the GitHub issue that you can follow to keep up-to-date with relevant news on a group API that works with async APIs.

Migrating from k6 v0.45 or below

If you use k6 v0.45 or below, first review how to migrate to v0.46. This guide details the breaking changes introduced in v0.46 for the browser APIs and provides instructions on how to migrate to them.

Where to get extra help

With the release of k6 v0.52, you’ll also be able to find the latest type definitions and updates to the k6 browser documentation. Refer to Configure k6 IntelliSense for details on how to work with the type definition file in your project.

For all the details, review the CHANGELOG for k6 version 0.52. You can also ask questions in the community forum if you need help.