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:

• The import path for the browser module has switched from chromium to browser.
• Simplified resource management. The browser module now handles the startup and shutdown of browser processes automatically. The chromium.launch(), chromium.connect(), and browser.close() methods are no longer necessary and have been removed.
• Browser options can now only be set using environment variables.
• Scenario options must now be defined for running browser tests.
• Single browser context per iteration. You can now only run a single BrowserContext at a time in the same iteration.

note

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.

1import { chromium } from 'k6/experimental/browser';
2
3export default async function () {
4    const browser = chromium.launch({
5        headless: false,
6        timeout: '60s',
7    });
8    const page = browser.newPage();
9
10    try {
11        await page.goto('https://test.k6.io/');
12        page.screenshot({ path: 'screenshot.png' });
13    } finally {
14        page.close();
15        browser.close();
16    }
17}

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

Import path

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

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

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

Before:

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

After:

$ K6_BROWSER_HEADLESS=false K6_BROWSER_TIMEOUT='60s' k6 run script.js

Connecting to a remote browser

Before:

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

After:

$ K6_BROWSER_WS_URL='REMOTE_URL' k6 run script.js

note

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  }
12}

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

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

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.

note

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.

• A new BrowserContext can be created either with the browser.newContext() or browser.newPage() methods.
• If a new BrowserContext needs to be created, the existing one must be closed first using the browserContext.close() method.
• Alongside these changes, the browser.contexts() method has been altered to browser.context() to retrieve the current BrowserContext.

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

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

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

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

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!