Running k6

Follow along to learn how to:

1. Run a test.
2. Add virtual users.
3. Increase the test duration.
4. Ramp the number of requests up and down as the test runs.

With these example snippets, you'll run the test with your machine's resources. But, if you have a cloud account, you can also use the k6 cloud command to outsource the test to our cloud servers.

Running local tests

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

1import http from 'k6/http';
2import { sleep } from 'k6';
3
4export default function () {
5  http.get('https://test.k6.io');
6  sleep(1);
7}

Then, run k6 with this command:

$ k6 run script.js

Adding more VUs

Now let's run a load test with more than one virtual user and a longer duration:

$ 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 your test scripts. VUs are essentially parallel while(true) loops. Scripts are written in JavaScript, as ES6 modules, which allows you to break larger tests into smaller pieces or make reusable pieces as you like.

The init context and the default function

For a test to run, you need to have init code, which prepares the test, and VU code, which makes requests.

Code in the init context defines functions and configures the test options (like duration).

Every test also has a default function. This function defines the entry point for your VUs.

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

Init code runs first and is called only once per VU. On the other hand, default code executes as many times as the test options set.

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

Using options

Instead of typing --vus 10 and --duration 30s each time you run the script, you can include the options in your JavaScript file:

1import http from 'k6/http';
2import { sleep } from 'k6';
3export const options = {
4  vus: 10,
5  duration: '30s',
6};
7export default function () {
8  http.get('http://test.k6.io');
9  sleep(1);
10}

Then, run the script without those options on the command line:

$ k6 run script.js

Stages: ramping up/down VUs

You can ramp the number of VUs up and down during the test. To configure ramping, use the options.stages property.

1import http from 'k6/http';
2import { check, sleep } from 'k6';
3
4export const options = {
5  stages: [
6    { duration: '30s', target: 20 },
7    { duration: '1m30s', target: 10 },
8    { duration: '20s', target: 0 },
9  ],
10};
11
12export default function () {
13  const res = http.get('https://httpbin.test.k6.io/');
14  check(res, { 'status was 200': (r) => r.status == 200 });
15  sleep(1);
16}

For advanced ramping, you can use scenarios and the ramping-vus executor.

Running cloud tests

k6 supports three test-execution modes:

• 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.

k6 has a goal of letting you run a test in all three execution modes without modifying the script.

To run cloud tests from the CLI:

1. Register a k6 Cloud account.
2. Log in to your account via the CLI.
3. Use the k6 cloud command to run the script you already have.

$ k6 cloud script.js