Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentation Grafana k6 Using k6 JavaScript mode

JavaScript compatibility mode

You can write k6 scripts in various ECMAScript versions:

• ES6+ JavaScript with ES modules (ESM).
• ES6+ JavaScript with CommonJS modules.

k6 supports both module types and most ES6+ features in all k6 execution modes: local, distributed, and cloud.

To enable ES module support, k6 uses Babel internally to transform ESM to CommonJS. The process is as follows:

Some users prefer to bundle their test code outside k6. For this reason, k6 offers two JavaScript compatibility modes:

• Extended mode: The default option, supporting ESM and most ES6+ features.
• Base mode: Limited to CommonJS, excluding the Babel step.

When running tests, you can change the mode by using the --compatibility-mode option:

Extended mode

By default, k6 uses the --compatibility-mode=extended mode:

bash

Copy

bash Copy

$ k6 run script.js

As illustrated in the previous diagram, if k6 detects unsupported ES+ features while parsing the test script, it then transforms the script with Babel to polyfill the unsupported features.

Currently, the k6 Babel transformation only adds ESM support and sets global (node’s global variable) with the value of globalThis.

Base mode

clienv

Copy

cli Copy

$ k6 run --compatibility-mode=base script.js

env Copy

$ K6_COMPATIBILITY_MODE=base k6 run script.js

The base mode omits the Babel transformation step, supporting only ES5.1+ code. You may want to enable this mode if your scripts are already written using only ES5.1 features or were previously transformed by Babel.

Generally, this mode is not recommended as it offers minor benefits in reducing startup time.

CommonJS Example

JavaScript

Copy

JavaScript Copy

const http = require('k6/http');
const k6 = require('k6');

module.exports.options = {
  vus: 10,
  duration: '30s',
};

module.exports.default = function () {
  http.get('http://test.k6.io');
  k6.sleep(1);
};

⚠️ About require()

Note that require() is a custom k6 implementation of module loading, which doesn’t behave in the same way as the require() call in Node.js. Specifically, it only handles loading of built-in k6 modules, scripts on the local filesystem, and remote scripts over HTTP(S), but it does not support the Node.js module resolution algorithm.

Bundling with Babel outside of k6

The examples below demonstrate the use of Babel with bundlers like Webpack and Rollup:

• k6-template-es6: Template using Webpack and Babel to bundle k6 tests.
• k6-rollup-example: Example using Rollup and Babel to bundle a testing project.

Read more

• Native ESM support: GitHub issue for native ESM support in k6. This feature aims to eliminate the Babel transformation step within k6.
• Running large tests: Optimize k6 for better performance.
• k6 Modules: Different options to import modules in k6.
• k6 Archive Command: The k6 archive command bundles all k6 test dependencies into a tar file, which can then be used for execution. It may also reduce the execution startup time.