Installation

Linux

Debian/Ubuntu

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 379CE192D401AB61
echo "deb https://dl.bintray.com/loadimpact/deb stable main" | sudo tee -a /etc/apt/sources.list
sudo apt-get update
sudo apt-get install k6

⚠️ If you are behind a firewall or proxy

There have been reports of users being unable to download the key from Ubuntu’s keyserver using apt-key command due to firewalls or proxies blocking their requests. If you experience this issue, you may try this alternative approach instead:

wget -q -O - https://bintray.com/user/downloadSubjectPublicKey?username=bintray | sudo apt-key add -

Redhat/CentOS

wget https://bintray.com/loadimpact/rpm/rpm -O bintray-loadimpact-rpm.repo
sudo mv bintray-loadimpact-rpm.repo /etc/yum.repos.d/
sudo yum install k6

Mac (brew)

Brew

brew install k6

Windows (MSI installer)

Download the k6 installer from here

Binaries

Grab a prebuilt binary from our Releases page. Install the binary in your PATH to run k6 from any location.

Docker

Docker

docker pull loadimpact/k6

Running k6

SUGGEST EDITS

Running local tests

Let’s start by running a simple local script. Copy the code below, paste it into your favourite editor, and save it as “script.js”:script.js

import http from 'k6/http';
import { sleep } from 'k6';

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

Then run k6 using this command:CLIDockerDocker in Win PowerShell

$ k6 run script.js

Adding more VUs

Now we’ll try running a load test with more than 1 virtual user and a slightly longer duration:CLIDockerDocker in Win PowerShell

k6 run --vus 10 --duration 30s script.js

Running a 30-second, 10-VU load test

k6 works with the concept of virtual users (VUs), which run scripts – they’re essentially glorified, parallel while(true) loops. Scripts are written using JavaScript, as ES6 modules, which allows you to break larger tests into smaller pieces, or make reusable pieces as you like.

Scripts must contain, at the very least, a default function – this defines the entry point for your VUs, similar to the main() function in many other languages:

export default function() {
  // vu code: do things here...
}

The init context and the default function

“Why not just run my script normally, from top to bottom”, you might ask – the answer is: we do, but code inside and outside your default function can do different things.

Code inside default is called “VU code”, and is run over and over for as long as the test is running. Code outside of it is called “init code”, and is run only once per VU.

// init code

export default function( {
  // vu code
}

VU code can make HTTP requests, emit metrics, and generally do everything you’d expect a load test to do – with a few important exceptions: you can’t load anything from your local filesystem, or import any other modules. This all has to be done from init-code.

Read more about the different life cycle stages of a k6 test.

Using options

If you want to avoid having to type --vus 10 and --duration 30s all the time, you can include those settings inside your JavaScript file also:script.js

import http from 'k6/http';
import { sleep } from 'k6';
export let options = {
  vus: 10,
  duration: '30s',
};
export default function() {
  http.get('http://test.k6.io');
  sleep(1);
}

Then you just run the script without those parameters on the command line:CLIDockerDocker in Win PowerShell

$ k6 run script.js

Stages: ramping up/down VUs

You can also have the VU level ramp up and down during the test. The options.stages property allows you to configure ramping behaviour.stages.js

import http from 'k6/http';
import { check, sleep } from 'k6';

export let options = {
  stages: [
    { duration: '30s', target: 20 },
    { duration: '1m30s', target: 10 },
    { duration: '20s', target: 0 },
  ],
};

export default function() {
  let res = http.get('https://httpbin.org/');
  check(res, { 'status was 200': r => r.status == 200 });
  sleep(1);
}

This can also be accomplished with more advanced configuration using scenarios and the ramping-vus executor.

Running cloud tests

k6 supports three execution modes to run your k6 tests:

• Local: on your local machine or a CI server.
• Cloud: on cloud infrastructure managed by k6 Cloud.
• Clustered: on more than one machine managed by you. Not supported yet.

One of the goals with k6 is to support running a test in the three execution modes without making modifications to the script.

For running cloud tests from the CLI, you must first register a k6 Cloud account and then log into your account via the CLI. Then, you only have to pass your existing script to the k6 cloud command.Running a cloud test

$ k6 cloud script.js

For detailed instructions and the different options, read more on running cloud tests from the CLI.