k6

Core k6 module with test utilities and assertion functions

The k6 module contains k6-specific functionality for writing load tests. This is the core module that provides essential functions like checks, groups, and sleep.

Import

import { check, fail, group, sleep, randomSeed } from 'k6';

Functions

check()

Runs one or more checks on a value and generates a pass/fail result but does not throw errors or interrupt execution upon failure.

val · any · required

Value to test.

sets · object · required

Tests (checks) to run on the value. Each key is a description, and each value is a function that returns a boolean.

tags · object

Extra tags to attach to metrics emitted.

return · boolean

Returns true if all checks have succeeded, false otherwise.

Basic check

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

export default function () {
  const res = http.get('https://quickpizza.grafana.com/');
  check(res, {
    'response code was 200': (res) => res.status == 200,
  });
}

Checks are not asserts. A failed assertion throws an error, while a check always returns with a pass or failure. Use thresholds to control failure conditions.

---

fail()

Immediately throws an error, aborting the current VU script iteration.

err · string

Error message that gets printed to stderr.

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

export default function () {
  const res = http.get('https://k6.io');
  if (
    !check(res, {
      'status code MUST be 200': (res) => res.status == 200,
    })
  ) {
    fail('status code was *not* 200');
  }
}

fail() does not abort the test or exit with non-0 status. It only aborts the current iteration. To halt test execution, use test.abort() from k6/execution.

---

group()

Runs code inside a group. Groups organize results in a test and tag metrics accordingly.

name · string · required

Name of the group.

fn · function · required

Group body - code to be executed in the group context.

return · any

The return value of the function.

import { group } from 'k6';

export default function () {
  group('visit product listing page', function () {
    // ...
  });
  group('add several products to the shopping cart', function () {
    // ...
  });
  group('visit login page', function () {
    // ...
  });
  group('authenticate', function () {
    // ...
  });
  group('checkout process', function () {
    // ...
  });
}

Avoid using group with async functions or asynchronous code. k6 might apply tags in an unreliable or unintuitive way with promises or await.

---

sleep()

Suspends VU execution for the specified duration.

t · number · required

Duration, in seconds.

Random sleep

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

export default function () {
  http.get('https://k6.io');
  sleep(Math.random() * 30);
  http.get('https://k6.io/features');
}

Don’t use sleep with async code like promises or event handlers. sleep blocks VU execution and prevents the event loop from processing. Use setTimeout from k6/timers for async code instead.

---

randomSeed()

Sets seed to get a reproducible pseudo-random number using Math.random.

int · integer · required

The seed value.

import { randomSeed } from 'k6';

export const options = {
  vus: 10,
  duration: '5s',
};

export default function () {
  randomSeed(123456789);
  const rnd = Math.random();
  console.log(rnd);
}

Using the same seed value across iterations produces the same sequence of random numbers.