No results for

Powered byAlgolia

Migrating to k6 v0.46

This guide outlines the key changes you will need to make when moving your existing k6 browser test scripts to the new k6 browser module (bundled with k6 version 0.46).

Key changes

The updated version introduces notable structural changes in its operation and API, including breaking changes:


You no longer need to use the K6_BROWSER_ENABLED flag when running browser tests with the k6 command.

Before and after comparison

Let's start with an overview of the main differences between the previous and new versions of the k6 browser API.

Before: The previous k6 browser API
1import { chromium } from 'k6/experimental/browser';
3export default async function () {
4 const browser = chromium.launch({
5 headless: false,
6 timeout: '60s',
7 });
8 const page = browser.newPage();
10 try {
11 await page.goto('');
12 page.screenshot({ path: 'screenshot.png' });
13 } finally {
14 page.close();
15 browser.close();
16 }
After: The new k6 browser API
1import { browser } from 'k6/experimental/browser';
3export const options = {
4 scenarios: {
5 ui: {
6 executor: 'shared-iterations',
7 options: {
8 browser: {
9 type: 'chromium',
10 },
11 },
12 },
13 }
16export default async function () {
17 const page = browser.newPage();
19 try {
20 await page.goto('');
21 page.screenshot({ path: 'screenshot.png' });
22 } finally {
23 page.close();
24 }

Import path

With the browser type (specifically chromium) now set in scenario options, you should directly import the browser object from the browser module.

Before: Import Path
1import { chromium } from 'k6/experimental/browser';
After: Import Path
1import { browser } from 'k6/experimental/browser';

Simplified resource management

The browser lifecycle is now automatically managed by the browser module, and so the chromium.launch(), chromium.connect(), and browser.close() methods are no longer necessary and have been removed.

Now, all that is needed is to specify the browser.type within the scenario options. If the option is set, a browser instance will automatically start at the beginning and close at the end of each test iteration.

Browser options

With the removal of the chromium.launch() and chromium.connect() methods, setting browsers options is now done by using environment variables. For more information, refer to Browser Module Options.

Launching a browser


1export default async function () {
2 const browser = chromium.launch({
3 headless: false,
4 timeout: '60s',
5 });


Windows: CMD
Windows: PowerShell
$ K6_BROWSER_HEADLESS=false K6_BROWSER_TIMEOUT='60s' k6 run script.js

Connecting to a remote browser


1export default async function () {
2 const remoteURL = 'REMOTE_URL'
3 const browser = chromium.connect(remoteURL);
4 const page = browser.newPage();


Windows: CMD
Windows: PowerShell
$ K6_BROWSER_WS_URL='REMOTE_URL' k6 run script.js

The following browser options are no longer supported: devtools, env, and proxy since they weren't providing much value. slowMo has been temporarily removed, and we're working on reintroducing it.

Scenario options

You must now set the executor and browser type as options in a scenario definition. Specifically, the browser.type option should be set to chromium, as Chromium is the only browser supported.

1export const options = {
2 scenarios: {
3 ui: {
4 executor: 'shared-iterations',
5 options: {
6 browser: {
7 type: 'chromium',
8 },
9 },
10 },
11 }

Opening and closing a page

You can open a new page by using the imported browser object's browser.newPage() method. You can still use the Page object as before.

1export default async function () {
2 const browser = chromium.launch();
3 const page = browser.newPage();
4 // ...
5 page.close();
6 browser.close();
1export default async function () {
2 const page = browser.newPage();
3 // ...
4 page.close();

The browser.close() method has been removed, so you can remove that from your scripts and use page.close() once you're done using the page object.


Closing of the page is critical for the calculation of accurate Web Vital metrics. See the browser metrics for more details.

Browser context limit

The new browser implementation limits the usage to a single active BrowserContext per iteration. This change enhances the prediction of resource requirements for a test run and promotes the use of scenarios to separate independent browser sessions.

For instance, the code below will not function as intended, as it attempts to execute two simultaneous BrowserContexts within the same iteration.

Incorrect usage
1export default async function() {
2 const context1 = browser.newContext();
3 // Simultaneous browser contexts are not permitted!
4 const context2 = browser.newContext();

On the other hand, the next example will function correctly by closing the initial BrowserContext prior to establishing a new one.

Correct usage
1export default async function() {
2 const context1 = browser.newContext();
3 context1.close();
5 // Since the first browser context is closed, a new browser context can be created.
6 const context2 = browser.newContext();
7 context2.close()

These updates make the usage of the API more straightforward for users, aiding in more consistent and automatic resource management.

For all the details, make sure to review the complete changelog for k6 version 0.46. For more information watch k6 Office Hours #98, where we discuss the latest changes in k6 browser, and, as always, ask in the community forum if you need help!