Knowledgebase

Module imports


Background

Load Impact 4.0 and k6 come with a batteries included standard library. They also support importing external libraries. This article provides an explanation and code samples on how to import the included or external modules into your k6 script.

Best Practice Alert: We recommend that you start building out you own custom library for common actions you find yourself doing in your test scripts. This is especialy important to make your efforts scalable to the rest of your team.

Note: External libraries are only available for import when using k6 locally to trigger tests. When you execute your test using the k6 cloud command, k6 will automatically bundle up the dependencies into an archive and upload that to our cloud service. You can rerun these tests through the web interface.


Modules

Load testing sophisticated applications requires advanced scripting capabilities, k6 supports powerful modules feature allowing you to:

  • modularize your code.
  • reuse existing Javascript libraries.

k6 can load ES6 modules and ES5 libraries.

Refer to k6 docs on modules for additional information.

Builtin modules

There are a number of builtin modules in k6 with performance testing related APIs. These are available both in the web based script editor and when using k6 locally.

  • k6
    • The k6 module contains k6-specific functionality.
  • k6/crypto
    • The k6/crypto module provides common hashing functionality available in the GoLang crypto package.
  • k6/encoding
    • The encoding module provides base64 encoding/decoding as defined by RFC4648.
  • k6/html
    • The k6/html module contains functionality for HTML parsing.
  • k6/http
    • The k6/http module contains functionality for performing HTTP transactions.
  • k6/metrics
    • The metrics module provides functionality to create custom metrics
  • k6/ws
    • The ws module provides a WebSocket client implementing the WebSocket protocol.
1
2
3
4
5
//Example import of built in Modules
import http from "k6/http";
import { Counter, Gauge, Rate, Trend} from "k6/metrics";
import { check } from "k6";
import { sha256 } from "k6/crypto";

Full documentation of these modules can be found within the k6 docs

Remote modules

k6 can import modules that are hosted remotely. This functionality is only available when using k6 locally to trigger tests.

1
2
3
4
5
6
7
import http from "k6/http";
import moment from "s3.amazonaws.com/k6samples/moment.js";

export default function() {
	http.get("http://test.loadimpact.com/");
	console.log(moment().format());
}

This also works with modules from hosting services:

1
2
3
4
5
6
7
import http from "k6/http";
import moment from "cdnjs.com/libraries/moment.js/2.18.1";

export default function() {
	http.get("http://test.loadimpact.com/");
	console.log(moment().format());
}

Using Node.js modules

k6 does not run Node.js. However, it can load bundled npm modules with browserify.

Run browserify with the standalone option to generate a Universal Module Definition bundle. This creates a package containing all the dependencies, and make the module available via module.exports. This new package can be imported in a k6 test.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
import http from "k6/http";
import { check } from "k6";
import cheerio from "./vendor/cheerio.js";
import xml2js from "./vendor/xml2js.js";


export default function() {

  const res = http.get("https://loadimpact.com/");

  const $ = cheerio.load(res.body);

  const title = $('head title').text();
  check(title, {
    "has correct title": () => title == 'Performance testing for DevOps | Load Impact'
  });


  var xmlString = '<?xml version="1.0" ?>' +
   	'<items xmlns="http://foo.com">' +
   ' <item>Foo</item>' +
   ' <item color="green">Bar</item>' +
   '</items>'

  xml2js.parseString(xmlString, function (err, result) {
      console.log(JSON.stringify(result));
  });

}

See the k6 docs on Node.js for more information.

Local modules with Docker

When executing k6 in a Docker container you must make sure to mount the necessary folders from the host into the container, using Docker volumes. This enables k6 to see all the JS modules required.

For example, say you have the following structure on your host machine:

/home/k6/example/src/index.js /home/k6/example/src/modules/module.js

1
2
3
4
5
6
//myScript.js
import { hello_world } from './modules/module.js';

export default function() {
    hello_world();
}
1
2
3
4
// module.js
export function hello_world() {
    console.log("Hello world");
}
docker run -v /home/k6/example/src:/src -i loadimpact/k6 run /src/index.js

Considerations and Limtations

Each Virtual User will load the required modules into memory during text execution. RAM usage is directly correlated to the number of Virtual Users and the total size of your JS objects. Excessive use of RAM can negatively impact the machine performing the test and the test execution and results.

Next: Test configuration options