utils on Grafana Labs

randomIntBetween(min, max)

Mon, 21 Sep 2026 15:16:28 +0000

randomIntBetween(min, max)

Function returns a random number between the specified range. The returned value is no lower than (and may possibly equal) min, and is no bigger than (and may possibly equal) max.

Parameter	Type	Description
min	int	Lower-end bound. Inclusive
max	int	Upper-end bound. Inclusive

Returns

Type	Description
int	Random integer

Example

import { sleep } from 'k6';
import { randomIntBetween } from 'https://jslib.k6.io/k6-utils/1.2.0/index.js';

export default function () {
  // code ...

  sleep(randomIntBetween(1, 5)); // sleep between 1 and 5 seconds.
}

randomItem(array)

Mon, 21 Sep 2026 15:16:28 +0000

randomItem(array)

Function returns a random item from an array.

Parameter	Type	Description
arrayOfItems	array	Array [] of items

Returns

Type	Description
any	Random item from the array

Example

import { randomItem } from 'https://jslib.k6.io/k6-utils/1.2.0/index.js';

const names = ['John', 'Jane', 'Bert', 'Ed'];

export default function () {
  const randomName = randomItem(names);
  console.log(`Hello, my name is ${randomName}`);
}

randomString(length, [charset])

Mon, 21 Sep 2026 15:16:28 +0000

randomString(length, [charset])

Function returns a random string of a given length, optionally selected from a custom character set.

Parameter	Type	Description
length	int	Length of the random string
charset (optional)	string	A customized list of characters

Returns

Type	Description
any	Random item(s) from the array of characters

Example

import { randomString } from 'https://jslib.k6.io/k6-utils/1.2.0/index.js';

export default function () {
  const randomFirstName = randomString(8);
  console.log(`Hello, my first name is ${randomFirstName}`);

  const randomLastName = randomString(10, `aeioubcdfghijpqrstuv`);
  console.log(`Hello, my last name is ${randomLastName}`);

  const randomCharacterWeighted = randomString(1, `AAAABBBCCD`);
  console.log(`Chose a random character ${randomCharacterWeighted}`);
}

uuidv4()

Mon, 21 Sep 2026 15:16:28 +0000

uuidv4()

Function returns a random uuid v4 in a string form.

Parameters

Parameter	Type	Description
secure (optional)	boolean	By default, `uuidv4()` uses a standard random number generator. If the `secure` option is set to `true`, `uuidv4` uses a cryptographically secure random number generator instead. While this adds security, the `secure` option also makes the function an order of magnitude slower.

Returns

Type	Description
string	Random UUID v4 string

Example

import { uuidv4 } from 'https://jslib.k6.io/k6-utils/1.4.0/index.js';

export default function () {
  const randomUUID = uuidv4();
  console.log(randomUUID); // 35acae14-f7cb-468a-9866-1fc45713149a
}

findBetween(content, left, right, [repeat])

Mon, 21 Sep 2026 15:16:28 +0000

findBetween(content, left, right, [repeat])

Function that returns a string from between two other strings.

Parameter	Type	Description
content	string	The string to search through (e.g. Response.body)
left	string	The string immediately before the value to be extracted
right	string	The string immediately after the value to be extracted
repeat (optional)	boolean	If `true`, the result will be a string array containing all occurrences

Returns

Type	Description
string	The extracted string, or an empty string if no match was found. If `repeat=true`, this will be an array of strings or an empty array

Example

import { findBetween } from 'https://jslib.k6.io/k6-utils/1.2.0/index.js';

export default function () {
  const response = '<div class="message">Message 1</div><div class="message">Message 2</div>';

  const message = findBetween(response, '<div class="message">', '</div>');

  console.log(message); // Message 1

  const allMessages = findBetween(response, '<div class="message">', '</div>', true);
  console.log(allMessages.length); // 2
}

normalDistributionStages(maxVus, durationSeconds, [numberOfStages])

Mon, 21 Sep 2026 15:16:28 +0000

normalDistributionStages(maxVus, durationSeconds, [numberOfStages])

Function to create stages producing a normal distribution (bell-curve) of VUs for a test.

Parameter	Type	Description
maxVus	int	Maximum virtual users at the height of the curve
durationSeconds	int	Overall duration for all stages combined
numberOfStages (optional)	int	Number of stages to create; default is `10`

Returns

Type	Description
array[object]	An array of `{"duration": "XXXs", "target": XXX}` JSON objects representing stages

Example

import { sleep } from 'k6';
import exec from 'k6/execution';
import { normalDistributionStages } from 'https://jslib.k6.io/k6-utils/1.2.0/index.js';

export const options = {
  // Alters the number of VUs from 1 to 10 over a period
  // of 20 seconds comprised of 5 stages.
  stages: normalDistributionStages(10, 20, 5),
};

export default function () {
  console.log(exec.instance.vusActive);
  sleep(1);
}

check( val, sets, [tags] )

Mon, 21 Sep 2026 15:16:28 +0000

check( val, sets, [tags] )

The check function is a drop-in replacement for the built-in check, with added support for async values. Any Promises will be awaited, and the result is reported once the operation has been completed.

Parameter	Type	Description
val	any	Value to test.
sets	Record<string, any>	Tests (checks) to run on the value. Functions will be called. `Promise`s will be awaited.
tags (optional)	Record<string, string>	Extra tags to attach to metrics emitted.

Returns

Type	Description
Promise	boolean	`true` if all checks have succeeded, `false` otherwise. If any of the checked values was a `Promise`, the result is wrapped in a `Promise`.

Examples

Using check() with async values.

import http from 'k6/http';
import { fail } from 'k6';
import { check } from 'https://jslib.k6.io/k6-utils/1.5.0/index.js';

function waitFor(delay) {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve(true);
    }, delay);
  });
}

export default async function () {
  const res = http.get('https://quickpizza.grafana.com/');

  const success = await check(res, {
    'passing promise as a value': waitFor(1000),
    'async function': async (res) => {
      await waitFor(500);

      return res.status === 200;
    },
  });

  if (!success) {
    fail('check did not succeed');
  }
}

For general usage of checks, refer to check(val, set, [tags]).