Documentation Grafana k6 Using k6 browser Migrating browser scripts to k6 v0.52

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:

1. 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.
2. 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.
3. 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.

Migrating to async

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

1. Change the import from k6/experimental/browser to k6/browser.
2. 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:

JavaScript

Copy

JavaScript Copy

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

...

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

And now:

JavaScript

Copy

JavaScript Copy

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

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:

JavaScript

Copy

JavaScript Copy

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

And now:

JavaScript

Copy

JavaScript Copy

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.