jslib on Grafana Labs

aws

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

aws

Note
The source code for this library can be found in the grafana/k6-jslib-aws GitHub repository.

The aws module is an external JavaScript library that helps interact with a subset of AWS services in the context of k6 test scripts.

httpx

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

httpx

Note
The source code for this library can be found in the grafana/k6-jslib-httpx GitHub repository.

The httpx module is an external JavaScript library that wraps around the native k6/http module. It’s an HTTP client with features that are not yet available in the native module.

Ability to set HTTP options globally (such as timeout).
Ability to set default tags and headers that will be used for all requests.
More user-friendly arguments to request functions (get, post, put take the same arguments).

The httpx module integrates well with the expect library.

Caution
This library is in active development. It’s stable enough to be useful, but you can watch the GitHub repository to be notified when a new version is released.

Methods

Function	Description
asyncRequest(method, url, [body], [params])	Generic method for making arbitrary, asynchronous HTTP requests.
request(method, url, [body], [params])	Generic method for making arbitrary HTTP requests.
get(url, [body], [params])	Makes GET request
post(url, [body], [params])	Makes POST request
put(url, [body], [params])	Makes PUT request
patch(url, [body], [params])	Makes PATCH request
delete(url, [body], [params])	Makes DELETE request
batch(requests)	Batches multiple HTTP requests together to issue them in parallel.
setBaseUrl(url)	Sets the base URL for the session
addHeader(key, value)	Adds a header to the session
addHeaders(object)	Adds multiple headers to the session
clearHeader(name)	Removes header from the session
addTag(key, value)	Adds a tag to the session
addTags(object)	Adds multiple tags to the session
clearTag(name)	Removes tag from the session

Example

import { fail } from 'k6';
import { Httpx } from 'https://jslib.k6.io/httpx/0.1.0/index.js';
import { randomIntBetween } from 'https://jslib.k6.io/k6-utils/1.2.0/index.js';

export const options = {
  vus: 1,
  iterations: 1,
};

const USERNAME = `user${randomIntBetween(1, 100000)}@example.com`; // random email address
const PASSWORD = 'secretpassword';

const session = new Httpx({
  baseURL: 'https://quickpizza.grafana.com',
  headers: {
    'User-Agent': 'My custom user agent',
  },
  timeout: 20000, // 20s timeout.
});

export default function testSuite() {
  const registrationResp = session.post(
    `/api/users`,
    JSON.stringify({
      username: USERNAME,
      password: PASSWORD,
    })
  );

  if (registrationResp.status !== 201) {
    fail('registration failed');
  }

  const loginResp = session.post(
    `/api/users/token/login`,
    JSON.stringify({
      username: USERNAME,
      password: PASSWORD,
    })
  );

  if (loginResp.status !== 200) {
    fail('Authentication failed');
  }

  const authToken = loginResp.json('token');

  // set the authorization header on the session for the subsequent requests.
  session.addHeader('Authorization', `Bearer ${authToken}`);

  const payload = {
    stars: 5,
    pizza_id: 1,
  };

  // this request uses the Authorization header set above.
  const respCreateRating = session.post(`/api/ratings`, JSON.stringify(payload));

  if (respCreateRating.status !== 201) {
    fail('Rating creation failed');
  } else {
    console.log('New rating created');
  }
}

k6chaijs

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

k6chaijs

Note
The source code for this library can be found in the grafana/k6-jslib-k6chaijs GitHub repository.

k6chaijs is a library to provide BDD assertions in k6 based on ChaiJS. You can use k6chaijs as an alternative to check and group.

With this library, you get the following:

BDD style of assertions for more expressive language
Chainable assertions
More powerful assertions functions such as: deep, nested, ordered, etc.
Automatic assertion messages
Exception handling for better test stability

Installation

This library is hosted on jslib and can be imported directly in your k6 script.

import { describe, expect } from 'https://jslib.k6.io/k6chaijs/4.5.0.1/index.js';

Alternatively, you can use a copy of this file stored locally. The source code is available on GitHub.

Example

The following example tests a hypothetical HTTP API that returns a JSON array of objects. Copy the following code, and save it as script.js:

import http from 'k6/http';
import { describe, expect } from 'https://jslib.k6.io/k6chaijs/4.3.4.3/index.js';

export default function testSuite() {
  describe('Fetch a list of pizza names', () => {
    const response = http.get('https://quickpizza.grafana.com/api/names');

    expect(response.status, 'response status').to.equal(200);
    expect(response).to.have.validJsonBody();
    expect(response.json('names').length, 'number of names').to.be.above(1);
  });
}

When you run this test with k6 run script.js, the output at the end of the test shows:

█ Fetch a list of public crocodiles
  ✓ expected response status to equal 200
  ✓ has valid json body
  ✓ expected number of crocs to be above 4

If you are familiar with k6, the result is the same as using check and group. Note that expect might add or extend the assertion message.

API

API	Description
config	Options to change `k6chaijs` behaviour.
describe	A wrapper of group that catches exceptions to allow continuing the test execution. It returns a boolean to indicate the success of all its `k6chaijs` assertions.
expect	A wrapper of check that provides BDD style of assertions.

Plugins

It’s possible to extend the default functionality with Chai plugins. To use a plugin or build a Chai version with plugins, follow the instructions in this example.

Use chai with k6

HTTP instrumentation for Pyroscope

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

HTTP instrumentation for Pyroscope

Note
The source code for this library can be found in the grafana/jslib.k6.io GitHub repository.

The http-instrumentation-pyroscope module allows you to instrument HTTP requests in a way that lets you tag Grafana Cloud Profiles with relevant information generated from k6 tests.

About baggage header

The baggage header is a standardized HTTP header used to propagate distributed context. The W3C specification goes into more detail on the specifics, but like many other headers, the baggage header is a list of key-value pairs.

This module, by default, adds three key-value pairs:

Scenario name
Name of the request (URL if not set)
Value of __ENV.K6_CLOUDRUN_TEST_RUN_ID, which is set automatically in Grafana Cloud k6.

API

Class/Function	Description
instrumentHTTP	Instruments the k6 http module with baggage header.
Client	Configurable Client that exposes instrumented HTTP operations.

Example

This example demonstrates how to use the this library to instrument every HTTP request made in a script with the baggage header.

import { check } from 'k6';
import pyroscope from 'https://jslib.k6.io/http-instrumentation-pyroscope/1.0.2/index.js';
import http from 'k6/http';

// instrumentHTTP will ensure that all requests made by the http module
// from this point forward will have a baggage context attached.
pyroscope.instrumentHTTP();

export default () => {
  // the instrumentHTTP call in the init context replaced
  // the http module with a version that will automatically
  // attach a baggage header to every request.
  const res = http.get('http://httpbin.org/get', {
    headers: {
      'X-Example-Header': 'instrumented/get',
    },
  });
};

HTTP instrumentation for Tempo

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

HTTP instrumentation for Tempo

Note
The source code for this library can be found in the grafana/jslib.k6.io GitHub repository.

The http-instrumentation-tempo module allows you to instrument HTTP requests so that they emit traces as the test runs. Use it to include a tracing context in HTTP requests, which can then be used by a tracing backend such as Grafana Tempo.

Migration from `k6/experimental/tracing`

This jslib is a drop in replacement, so all you need to migrate to it is to replace 'k6/experimental/tracing' import with 'https://jslib.k6.io/http-instrumentation-tempo/1.0.1/index.js'

About trace contexts

A trace context is a set of standardized HTTP headers added to a request that lets a tracing system correlate it with other requests as they navigate through a system. The trace context specifications, such as the supported W3C Trace Context and Jaeger Trace Context, define specific header names and an encoding format for the header values.

A trace context generally consists of, at least, a trace_id, a span_id, and a sampled flag. The trace_id is a unique identifier for the trace, the span_id is a unique identifier for the request, and the sampled flag is a boolean that indicates whether the request should be traced. For instance, the W3C Trace Context defines the Traceparent header, whose value contains a trace_id, a span_id and a sampled flag, encoded as a dash (-) separated list of hexadecimal values. When a trace context header is attached to an HTTP request, we refer to it as being propagated to the downstream service.

API

Class/Function	Description
instrumentHTTP	Instruments the k6 http module with tracing capabilities.
Client	A configurable client that exposes instrumented HTTP operations and allows selectively instrumenting requests with tracing.

Example

This example demonstrates how to use the tracing API to instrument every HTTP request made in a script with tracing information.

import { check } from 'k6';
import tempo from 'https://jslib.k6.io/http-instrumentation-tempo/1.0.1/index.js';
import http from 'k6/http';

// instrumentHTTP will ensure that all requests made by the http module
// from this point forward will have a trace context attached.
//
// The first argument is a configuration object that
// can be used to configure the tracer.
tempo.instrumentHTTP({
  // possible values: "w3c", "jaeger"
  propagator: 'w3c',
});

export default () => {
  // the instrumentHTTP call in the init context replaced
  // the http module with a version that will automatically
  // attach a trace context to every request.
  //
  // Because the instrumentHTTP call was configured with the
  // w3c trace propagator, this request will as a result have
  // a `traceparent` header attached.
  const res = http.get('http://httpbin.org/get', {
    headers: {
      'X-Example-Header': 'instrumented/get',
    },
  });
};

utils

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

utils

Note
The source code for this library can be found in the grafana/k6-jslib-utils GitHub repository.

The utils module contains number of small utility functions useful in every day load testing.

Function	Description
check(val, sets, [tags])	Drop-in replacement for `check` with support for async values.
randomIntBetween(min, max)	Random integer in a given range
randomItem(array)	Random item from a given array
randomString(length, [charset])	Random string of a given length, optionally selected from a custom character set
uuidv4()	Random UUID v4 in a string representation
findBetween(content, left, right, [repeat])	Extract a string between two surrounding strings
normalDistributionStages(maxVUs, durationSeconds, [numberOfStages])	Creates stages which will produce a normal distribution (bell-curve) of VUs for a test
getCurrentStageIndex	Get the index of the running stage as defined in the `stages` array options. It can be used only with the executors that support the `stages` option as ramping-vus or ramping-arrival-rate.
tagWithCurrentStageIndex	Tag all the generated metrics in the iteration with the index of the current running stage.
tagWithCurrentStageProfile	Tag all the generated metrics in the iteration with the computed profile for the current running stage.

Simple example

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

import {
  randomIntBetween,
  randomString,
  randomItem,
  uuidv4,
  findBetween,
} from 'https://jslib.k6.io/k6-utils/1.4.0/index.js';

export default function () {
  const res = http.post(`https://quickpizza.grafana.com/api/users`, {
    username: `user_${randomString(10)}@example.com`, // random email address,
    password: uuidv4(), // random password in form of uuid
  });

  // find a string between two strings to grab the username:
  const username = findBetween(res.body, '"username":"', '"');
  console.log('username from response: ' + username);

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

totp

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

totp

Note
The source code for this library can be found in the grafana/k6-jslib-totp GitHub repository.

The totp module provides TOTP (Time-based One-Time Password) generation and verification as defined in RFC 6238.

Class/Method	Description
TOTP(secret, [digits])	Create a new TOTP instance
TOTP.gen([timeStep], [bias])	Generate a TOTP code
TOTP.verify(code, [timeStep])	Verify a TOTP code

Example

import { TOTP } from 'https://jslib.k6.io/totp/1.0.0/index.js';

export default async function () {
  const totp = new TOTP('GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ', 6);
  const code = await totp.gen();
  console.log(`TOTP code: ${code}`);

  const isValid = await totp.verify(code);
  console.log(`Valid: ${isValid}`);
}

With k6 Secrets

import secrets from 'k6/secrets';
import { TOTP } from 'https://jslib.k6.io/totp/1.0.0/index.js';

export default async function () {
  const secret = await secrets.get('totp_secret');
  const totp = new TOTP(secret, 6);
  const code = await totp.gen();
  console.log(`TOTP code: ${code}`);
}

k6-testing

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

k6-testing

The k6 testing library provides assertion capabilities for both protocol and browser testing, and draws inspiration from Playwright’s test API design.
The entire library is centered around the expect() function, which can be configured for convenience.

Note
The k6 testing library source code is available on GitHub.

Features

Playwright-inspired assertions: API designed with patterns inspired by Playwright’s testing approach
Protocol and browser testing: Works with both HTTP/API testing and browser automation
Auto-retrying assertions: Automatically retry assertions until they pass or timeout
Soft assertions: Continue test execution even after assertion failures
Configurable timeouts: Customizable timeout and polling intervals

Usage

To use the testing library in your k6 script, import it in your tests directly from the jslib repository:

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

Demo

Protocol Testing

import { check } from 'k6';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';
import { randomString } from 'https://jslib.k6.io/k6-utils/1.4.0/index.js';
import http from 'k6/http';

export default function () {
  const payload = JSON.stringify({
    username: `${randomString(5)}_default@example.com`,
    password: 'secret',
  });
  const response = http.post(`https://quickpizza.grafana.com/api/users`, payload); // create user

  console.info(response.json());

  //Traditional k6 check
  check(response, {
    'status is 201': (r) => r.status === 201,
  });

  //Using expect assertions
  expect(response.status).toBe(201);
  expect(response.json()).toHaveProperty('id');
}

Browser Testing

import { browser } from 'k6/browser';
import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

export const options = {
  scenarios: {
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
};

export default async function () {
  const page = await browser.newPage();

  await page.goto('https://quickpizza.grafana.com');

  // Retrying Assertions
  await expect(page.locator('h1')).toBeVisible();
  await expect(page.locator('h1')).toHaveText('Looking to break out of your pizza routine?');
}

Configuration

Create configured expect.configure() instances for custom behavior:

import { expect } from 'https://jslib.k6.io/k6-testing/0.6.1/index.js';

// Create configured expect instance
const myExpect = expect.configure({
  timeout: 10000, // Default timeout for retrying assertions
  interval: 200, // Polling interval for retrying assertions
  colorize: true, // Enable colored output
  display: 'pretty', // Output format
  softMode: 'fail', // Soft assertion behavior
});

Assertion types

The testing library provides two types of assertions:

Non-Retrying Assertions

Synchronous assertions that evaluate immediately. These are ideal for testing static values, API responses, and scenarios where the expected condition should be true at the moment of evaluation.

Retrying Assertions

Asynchronous assertions that automatically retry until conditions become true or timeout. These are suitable for browser testing, dynamic content, and scenarios where conditions may change over time.

API Reference

Function	Description
expect()	Main assertion function
expect.configure()	Create configured expect instances
Non-Retrying Assertions	Synchronous assertions for immediate evaluation
Retrying Assertions	Asynchronous assertions for dynamic content

jslib on Grafana Labs

aws

aws

httpx

httpx

Methods

Example

k6chaijs

k6chaijs

Installation

Example

API

Plugins

Read more

HTTP instrumentation for Pyroscope

HTTP instrumentation for Pyroscope

About baggage header

API

Example

HTTP instrumentation for Tempo

HTTP instrumentation for Tempo

Migration from k6/experimental/tracing

About trace contexts

API

Example

utils

utils

Simple example

totp

totp

Example

With k6 Secrets

k6-testing

k6-testing

Features

Usage

Demo

Protocol Testing

Browser Testing

Configuration

Assertion types

Non-Retrying Assertions

Retrying Assertions

API Reference

Migration from `k6/experimental/tracing`