Documentation Grafana Cloud Testing and synthetics Performance testing Author and run tests Use k6 extensions

Use k6 extensions

k6 has a set of core functionalities that you can use via its own set of JavaScript APIs. As a user, you might want to test a service or a protocol that’s not supported by the existing k6 APIs. That’s where extensions come in.

k6 extensions are a way to extend the core functionality of k6. For k6 open source users, they can write custom extensions and then build a new k6 binary to use them locally. For Grafana Cloud k6 users, you can use a subset of these extensions when running your test scripts, without having to build a custom k6 binary.

Supported extensions in Grafana Cloud

Grafana Cloud k6 has built-in support for two categories of extensions: Official and Community.

Official extensions

These are extensions owned and maintained by Grafana Labs, and they work by default in all k6 execution modes:

• k6 run and k6 cloud run if using the CLI.
• Tests launched from the Performance Testing application, such as those launched through the Script editor.

Grafana guarantees regular maintenance, such as security patches and new versions that add or improve functionality.

Community extensions

These are extensions developed by the community, with support for specific versions. They only work in local execution modes, when you explicitly request them via the K6_ENABLE_COMMUNITY_EXTENSIONS environment variable:

• K6_ENABLE_COMMUNITY_EXTENSIONS=true k6 run test.js
• K6_ENABLE_COMMUNITY_EXTENSIONS=true k6 cloud run --local-execution test.js

Grafana doesn’t guarantee support for community extensions beyond allowing the use of vetted versions.

Use extensions in Grafana Cloud

There are different requirements for using extensions in Grafana Cloud depending on how you execute your test script.

Before you begin

• Extensions are only supported when running your test scripts using the Script editor or the CLI.
• When running your tests via the CLI, use k6 v1.2 or later, which includes native support for extension loading.
• Using extensions via the Test builder isn’t supported.

Import an extension in your test script

The first step to using a cloud extension is to import it into your test script. For example, if you want to use the xk6-faker extension, you can add the following import statement:

JavaScript Copy

import faker from 'k6/x/faker';

You can then use any functionality available from the extension. For example, you can create a random name using the faker.person class:

JavaScript Copy

import faker from 'k6/x/faker';

export default function () {
  console.log(faker.person.firstName());
}

If you are interested in specifying the version of k6 or the extensions, refer to Override versions.

Run a test with an extension in Grafana Cloud

To run a test script that uses an extension, you have to use the Script editor or the CLI.

Run a test via the script editor

The script editor supports built-in extensions by default. You can import and use any extensions, and run your test without any additional steps.

Run a test via the CLI

Make sure you have k6 v1.2 or later installed by running the following command:

Bash Copy

k6 version

Then, follow these steps to run your test script with extensions:

1. Authenticate with Grafana Cloud:

   Bash Copy

   k6 cloud login --token <API_TOKEN>

2. Run your test.

   • In the cloud:

     Bash Copy

     k6 cloud run test.js

   • Locally (with cloud-provisioned binary):

     Bash Copy

     k6 cloud run --local-execution test.js

If your script uses supported extensions, k6 automatically detects them and provisions a compatible binary, either in Grafana Cloud or locally.

Example output

text Copy

INFO[0287] A new k6 binary has been provisioned with version(s): k6:v1.1.0 k6/x/faker:v0.4.4

Disable extensions

You can disable this feature by setting the environment variable K6_AUTO_EXTENSION_RESOLUTION to false. If provided, the previous example fails because k6 can’t load the extension dynamically.

For example:

Bash Copy

K6_AUTO_EXTENSION_RESOLUTION=false k6 cloud run test.js

And an example output for a test failure:

text Copy

ERRO[0000] GoError: unknown module: k6/x/faker           hint="script exception"