Examples on Grafana Labs

Get started with k6

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

Get started with k6

This tutorial provides some procedures for common real-life uses of k6. They assume no prior knowledge of k6 or of JavaScript.

These tasks are all reproducible, so open up your favorite editor and follow along. Imagine that you are a developer or tester who is responsible for performance in your development team.

Context: test a new endpoint

Your development team has just developed a new login endpoint. Before releasing, you must test the endpoint for the following questions:

Does it work?
Does it perform within the service-level objectives under average load?
At what load does performance degrade beyond objectives?

After you test the endpoint, your team wants you to compare different components of the user-facing application.

Finally, after you test the API and web application, break your scripts down into reusable parts.

Before you start

We encourage you to open your terminal and actively experiment with these examples. The tutorial requires the following:

k6 installed
A clean directory to experiment in.
Something to do during the minute or two when k6 runs the longest example tests
Optional: jq to filter some results

Tutorials

In this tutorial	Learn how to
Test for functional behavior	Use k6 to script requests and evaluate that performance is correct
Test for performance	Use k6 to increase load and find faults
Analyze results	Filter results and make custom metrics
Reuse and re-run	Modularize and re-run tests

Single request

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

Single request

import http from 'k6/http';

export const options = {
  iterations: 1,
};

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

HTTP Authentication

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

HTTP Authentication

Scripting examples on how to use different authentication or authorization methods in your load test.

Basic authentication

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

const username = 'user';
const password = 'passwd';

export default function () {
  const credentials = `${username}:${password}`;

  // Passing username and password as part of the URL will
  // allow us to authenticate using HTTP Basic Auth.
  const url = `https://${credentials}@quickpizza.grafana.com/api/basic-auth/${username}/${password}`;

  let res = http.get(url);

  // Verify response
  check(res, {
    'status is 200': (r) => r.status === 200,
    'is authenticated': (r) => r.json().authenticated === true,
    'is correct user': (r) => r.json().user === username,
  });

  // Alternatively you can create the header yourself to authenticate
  // using HTTP Basic Auth
  const encodedCredentials = encoding.b64encode(credentials);
  const options = {
    headers: {
      Authorization: `Basic ${encodedCredentials}`,
    },
  };

  res = http.get(`https://quickpizza.grafana.com/api/basic-auth/${username}/${password}`, options);

  // Verify response (checking the echoed data from the QuickPizza
  // basic auth test API endpoint)
  check(res, {
    'status is 200': (r) => r.status === 200,
    'is authenticated': (r) => r.json().authenticated === true,
    'is correct user': (r) => r.json().user === username,
  });
}

NTLM authentication

import http from 'k6/http';

const username = 'user';
const password = 'passwd';

export default function () {
  // Passing username and password as part of URL and then specifying
  // "ntlm" as auth type will do the trick!
  const credentials = `${username}:${password}`;
  const res = http.get(`http://${credentials}@example.com/`, { auth: 'ntlm' });
}

AWS Signature v4 authentication with the k6-jslib-aws

To authenticate requests to AWS APIs using AWS Signature Version 4, k6 offers the k6-jslib-aws JavaScript library, which provides a dedicated SignatureV4 class. This class can produce authenticated requests to send to AWS APIs using the http k6 module.

Here’s an example script to demonstrate how to sign a request to fetch an object from an S3 bucket:

import http from 'k6/http';
import {
  AWSConfig,
  SignatureV4,
} from 'https://jslib.k6.io/aws/0.14.0/signature.js';

const awsConfig = new AWSConfig({
  region: __ENV.AWS_REGION,
  accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
  secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,

  /**
   * Optional session token for temporary credentials.
   */
  sessionToken: __ENV.AWS_SESSION_TOKEN,
});

export default function () {
  /**
   * Create a signer instance with the AWS credentials.
   * The signer will be used to sign the request.
   */
  const signer = new SignatureV4({
    service: 's3',
    region: awsConfig.region,
    credentials: {
      accessKeyId: awsConfig.accessKeyId,
      secretAccessKey: awsConfig.secretAccessKey,
      sessionToken: awsConfig.sessionToken,
    },
  });

  /**
   * Use the signer to prepare a signed request.
   * The signed request can then be used to send the request to the AWS API.
   */
  const signedRequest = signer.sign(
    {
      method: 'GET',
      protocol: 'https',
      hostname: 'test-jslib-aws.s3.us-east-1.amazonaws.com',
      path: '/bonjour.txt',
      headers: {},
      uriEscapePath: false,
      applyChecksum: false,
    },
    {
      signingDate: new Date(),
      signingService: 's3',
      signingRegion: 'us-east-1',
    }
  );

  /**
   * The `signedRequest` object contains the signed request URL and headers.
   * We can use them to send the request to the AWS API.
   */
  http.get(signedRequest.url, { headers: signedRequest.headers });
}

OAuth Authentication

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

OAuth Authentication

Scripting examples on how to use OAuth authentication in your load test.

OAuth authentication

The following examples take a set of arguments, shown in the function documentation, and returns the response body as JSON so that you can extract the token from.

Azure Active Directory

import http from 'k6/http';

/**
 * Authenticate using OAuth against Azure Active Directory
 * @function
 * @param  {string} tenantId - Directory ID in Azure
 * @param  {string} clientId - Application ID in Azure
 * @param  {string} clientSecret - Can be obtained from https://docs.microsoft.com/en-us/azure/storage/common/storage-auth-aad-app#create-a-client-secret
 * @param  {string} scope - Space-separated list of scopes (permissions) that are already given consent to by admin
 * @param  {string} resource - Either a resource ID (as string) or an object containing username and password
 */
export function authenticateUsingAzure(tenantId, clientId, clientSecret, scope, resource) {
  let url;
  const requestBody = {
    client_id: clientId,
    client_secret: clientSecret,
    scope: scope,
  };

  if (typeof resource == 'string') {
    url = `https://login.microsoftonline.com/${tenantId}/oauth2/token`;
    requestBody['grant_type'] = 'client_credentials';
    requestBody['resource'] = resource;
  } else if (
    typeof resource == 'object' &&
    resource.hasOwnProperty('username') &&
    resource.hasOwnProperty('password')
  ) {
    url = `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`;
    requestBody['grant_type'] = 'password';
    requestBody['username'] = resource.username;
    requestBody['password'] = resource.password;
  } else {
    throw 'resource should be either a string or an object containing username and password';
  }

  const response = http.post(url, requestBody);

  return response.json();
}

Azure B2C

The following example shows how you can authenticate with Azure B2C using the Client Credentials Flow.

This example is based on a JMeter example found at the azure-ad-b2c/load-tests repository.

To use this script, you need to:

Set up your own Azure B2C tenant
- Copy the tenant name, it will be used in your test script.
Register a web application
- Register a single page application with the redirect URL of: https://jwt.ms. That’s needed for the flow to receive a token.
- After the creation, you can get the Application (client) ID, and the Directory (tenant) ID. Copy both of them, they’ll be used in your test script.
Create a user flow so that you can sign up and create a user
- Create a new user, and copy the username and password. They’ll be used in the test script.

You can find the settings in the B2C settings in the Azure portal if you need to refer to them later on. Make sure to fill out all the variables for the B2CGraphSettings object, as well as replace USERNAME and PASSWORD in export default function.

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

const B2CGraphSettings = {
  B2C: {
    client_id: '', // Application ID in Azure
    user_flow_name: '',
    tenant_id: '', // Directory ID in Azure
    tenant_name: '',
    scope: 'openid',
    redirect_url: 'https://jwt.ms',
  },
};

/**
 * Authenticate using OAuth against Azure B2C
 * @function
 * @param  {string} username - Username of the user to authenticate
 * @param  {string} password
 * @return {string} id_token
 */
export function GetB2cIdToken(username, password) {
  const state = GetState();
  SelfAsserted(state, username, password);
  const code = CombinedSigninAndSignup(state);
  return GetToken(code, state.codeVerifier);
}

/**
 * @typedef {object} b2cStateProperties
 * @property {string} csrfToken
 * @property {string} stateProperty
 * @property {string} codeVerifier
 *
 */

/**
 * Get the id token from Azure B2C
 * @function
 * @param {string} code
 * @returns {string} id_token
 */
const GetToken = (code, codeVerifier) => {
  const url =
    `https://${B2CGraphSettings.B2C.tenant_name}.b2clogin.com/${B2CGraphSettings.B2C.tenant_id}` +
    `/oauth2/v2.0/token` +
    `?p=${B2CGraphSettings.B2C.user_flow_name}` +
    `&client_id=${B2CGraphSettings.B2C.client_id}` +
    `&grant_type=authorization_code` +
    `&scope=${B2CGraphSettings.B2C.scope}` +
    `&code=${code}` +
    `&redirect_uri=${B2CGraphSettings.B2C.redirect_url}` +
    `&code_verifier=${codeVerifier}`;

  const response = http.post(url, '', {
    tags: {
      b2c_login: 'GetToken',
    },
  });

  return JSON.parse(response.body).id_token;
};

/**
 * Signs in the user using the CombinedSigninAndSignup policy
 * extraqct B2C code from response
 * @function
 * @param {b2cStateProperties} state
 * @returns {string} code
 */
const CombinedSigninAndSignup = (state) => {
  const url =
    `https://${B2CGraphSettings.B2C.tenant_name}.b2clogin.com/${B2CGraphSettings.B2C.tenant_name}.onmicrosoft.com` +
    `/${B2CGraphSettings.B2C.user_flow_name}/api/CombinedSigninAndSignup/confirmed` +
    `?csrf_token=${state.csrfToken}` +
    `&rememberMe=false` +
    `&tx=StateProperties=${state.stateProperty}` +
    `&p=${B2CGraphSettings.B2C.user_flow_name}`;

  const response = http.get(url, '', {
    tags: {
      b2c_login: 'CombinedSigninAndSignup',
    },
  });
  const codeRegex = '.*code=([^"]*)';
  return response.url.match(codeRegex)[1];
};

/**
 * Signs in the user using the SelfAsserted policy
 * @function
 * @param {b2cStateProperties} state
 * @param {string} username
 * @param {string} password
 */
const SelfAsserted = (state, username, password) => {
  const url =
    `https://${B2CGraphSettings.B2C.tenant_name}.b2clogin.com/${B2CGraphSettings.B2C.tenant_id}` +
    `/${B2CGraphSettings.B2C.user_flow_name}/SelfAsserted` +
    `?tx=StateProperties=${state.stateProperty}` +
    `&p=${B2CGraphSettings.B2C.user_flow_name}` +
    `&request_type=RESPONSE` +
    `&email=${username}` +
    `&password=${password}`;

  const params = {
    headers: {
      'X-CSRF-TOKEN': `${state.csrfToken}`,
    },
    tags: {
      b2c_login: 'SelfAsserted',
    },
  };
  http.post(url, '', params);
};

/**
 * Calls the B2C login page to get the state property
 * @function
 * @returns {b2cStateProperties} b2cState
 */
const GetState = () => {
  const nonce = randomString(50);
  const challenge = crypto.sha256(nonce.toString(), 'base64rawurl');

  const url =
    `https://${B2CGraphSettings.B2C.tenant_name}.b2clogin.com` +
    `/${B2CGraphSettings.B2C.tenant_id}/oauth2/v2.0/authorize?` +
    `p=${B2CGraphSettings.B2C.user_flow_name}` +
    `&client_id=${B2CGraphSettings.B2C.client_id}` +
    `&nonce=${nonce}` +
    `&redirect_uri=${B2CGraphSettings.B2C.redirect_url}` +
    `&scope=${B2CGraphSettings.B2C.scope}` +
    `&response_type=code` +
    `&prompt=login` +
    `&code_challenge_method=S256` +
    `&code_challenge=${challenge}` +
    `&response_mode=fragment`;

  const response = http.get(url, '', {
    tags: {
      b2c_login: 'GetCookyAndState',
    },
  });

  const vuJar = http.cookieJar();
  const responseCookies = vuJar.cookiesForURL(response.url);

  const b2cState = {};
  b2cState.codeVerifier = nonce;
  b2cState.csrfToken = responseCookies['x-ms-cpim-csrf'][0];
  b2cState.stateProperty = response.body.match('.*StateProperties=([^"]*)')[1];
  return b2cState;
};

/**
 * Helper function to get the authorization header for a user
 * @param {user} user
 * @returns {object} httpsOptions
 */
export const GetAuthorizationHeaderForUser = (user) => {
  const token = GetB2cIdToken(user.username, user.password);

  return {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + token,
    },
  };
};

export default function () {
  const token = GetB2cIdToken('USERNAME', 'PASSWORD');
  console.log(token);
}

Okta

import http from 'k6/http';
import encoding from 'k6/encoding';

/**
 * Authenticate using OAuth against Okta
 * @function
 * @param  {string} oktaDomain - Okta domain to authenticate against (e.g. 'k6.okta.com')
 * @param  {string} authServerId - Authentication server identifier (default is 'default')
 * @param  {string} clientId - Generated by Okta automatically
 * @param  {string} clientSecret - Generated by Okta automatically
 * @param  {string} scope - Space-separated list of scopes
 * @param  {string|object} resource - Either a resource ID (as string) or an object containing username and password
 */
export function authenticateUsingOkta(
  oktaDomain,
  authServerId,
  clientId,
  clientSecret,
  scope,
  resource
) {
  if (authServerId === 'undefined' || authServerId == '') {
    authServerId = 'default';
  }
  const url = `https://${oktaDomain}/oauth2/${authServerId}/v1/token`;
  const requestBody = { scope: scope };
  let response;

  if (typeof resource == 'string') {
    requestBody['grant_type'] = 'client_credentials';

    const encodedCredentials = encoding.b64encode(`${clientId}:${clientSecret}`);
    const params = {
      auth: 'basic',
      headers: {
        Authorization: `Basic ${encodedCredentials}`,
      },
    };

    response = http.post(url, requestBody, params);
  } else if (
    typeof resource == 'object' &&
    resource.hasOwnProperty('username') &&
    resource.hasOwnProperty('password')
  ) {
    requestBody['grant_type'] = 'password';
    requestBody['username'] = resource.username;
    requestBody['password'] = resource.password;
    requestBody['client_id'] = clientId;
    requestBody['client_secret'] = clientSecret;

    response = http.post(url, requestBody);
  } else {
    throw 'resource should be either a string or an object containing username and password';
  }

  return response.json();
}

For a detailed example, please visit this article: How to Load Test OAuth secured APIs with k6?

Correlation and Dynamic Data

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

Correlation and Dynamic Data

Scripting examples on how to correlate dynamic data in your test script. Correlation is often required when using the HAR converter to generate your test script. This is because those tools will capture session IDs, CSRF tokens, VIEWSTATE, wpnonce, and other dynamic values from your specific session. These tokens typically expire very quickly. This is one of the most common things that users will script for when testing user journeys across websites or web apps.

Correlation

In a load testing scenario, correlation means extracting one or more values from the response of one request and then reusing them in subsequent requests. Often, this could be getting a token or some sort of ID necessary to fulfill a sequence of steps in a user journey.

A recording will capture session data such as CSRF tokens, VIEWSTATES, nonce, etc. This type of data is unlikely to be valid when you run your test, meaning you’ll need to handle the extraction of this data from the HTML/form to include it in subsequent requests. This issue is fairly common with any site that has forms and can be handled with a little bit of scripting.

Extracting values/tokens from a JSON response

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

export default function () {
  // Make a request that returns some JSON data
  const reqHeaders = {
    Authorization: 'Token abcdef0123456789',
  };
  const res = http.get('https://quickpizza.grafana.com/api/doughs', {
    headers: reqHeaders,
  });

  // Extract data from that JSON data by first parsing it
  // using a call to "json()" and then accessing properties by
  // navigating the JSON data as a JS object with dot notation.
  const dough1 = res.json().doughs[0];
  check(dough1, {
    'dough1 1 has correct name': (s) => s.name === 'Thin',
    'dough1 1 has correct ID': (s) => s.ID === 1,
  });

  // Now we could use the "dough1" variable in subsequent requests...
}

Relevant k6 APIs:

Response.json()
JSON.parse() (An alternative API that can be used for parsing JSON data)

Extracting values/tokens from form fields

You can choose from two different approaches when deciding how to handle form submissions. Either you use the higher-level Response.submitForm([params]) API or you extract necessary hidden fields etc. and build a request yourself and then send it using the appropriate http.* family of APIs, like http.post(url, [body], [params]).

Extracting .NET ViewStates, CSRF tokens and other hidden input fields

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

export default function () {
  // Request the page containing a form and save the response. This gives you access
  //to the response object, `res`.
  const res = http.get('https://test.k6.io/my_messages.php', { responseType: 'text' });

  // Query the HTML for an input field named "redir". We want the value or "redir"
  const elem = res.html().find('input[name=redir]');

  // Get the value of the attribute "value" and save it to a variable
  const val = elem.attr('value');

  // Now you can concatenate this extracted value in subsequent requests that require it.
  // ...
  // console.log() works when executing k6 scripts locally and is handy for debugging purposes
  console.log('The value of the hidden field redir is: ' + val);

  sleep(1);
}

⚠️ Did you know?

Take note if discardResponseBodies is set to true in the options section of your script. If it is, you can either make it false or save the response per request with {"responseType": "text"} as shown in the example.

Relevant k6 APIs:

Selection.find(selector) (the jQuery Selector API docs are also a good resource on what possible selector queries can be made)
Selection.attr(name)

Generic extraction of values/tokens

Sometimes, responses may be neither JSON nor HTML, in which case the above extraction methods would not apply. In these situations, you would likely want to operate directly on the Response.body string using a simple function capable of extracting a string at some known location. This is typically achieved by looking for the string “boundaries” immediately before (left) and after (right) the value needing extraction.

The jslib utils library contains an example of this kind of function, findBetween. The function uses the JavaScript built-in String.indexOf and therefore doesn’t depend on potentially expensive regular-expression operations.

Extracting a value/token using findBetween

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

export default function () {
  // This request returns XML:
  const res = http.get('https://quickpizza.grafana.com/api/xml?color=green');

  // Use findBetween to extract the first <value> tag encountered:
  const color = findBetween(res.body, '<value>', '</value>');

  check(color, {
    'color is correct': (t) => t === 'green',
  });
}

Relevant k6 APIs:

Data parameterization

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

Data parameterization

Data parameterization is the process of turning test values into reusable parameters, for example, through variables and shared arrays.

This page gives some examples of how to parameterize data in a test script. Parameterization is typically necessary when Virtual Users (VUs) make a POST, PUT, or PATCH request in a test. You can also use parameterization when you need to add test data from a separate file.

Parameterization helps to prevent server-side caching from impacting your load test, which makes your tests more realistic.

Performance implications of `SharedArray`

Each VU in k6 is a separate JS VM. To prevent multiple copies of the whole data file, SharedArray was added. It does have some CPU overhead in accessing elements compared to a normal non shared array, but the difference is negligible compared to the time it takes to make requests. This becomes even less of an issue compared to not using it with large files, as k6 would otherwise use too much memory to run, which might lead to your script not being able to run at all or aborting in the middle if the system resources are exhausted.

For example, the Cloud service allocates 8GB of memory for every 300 VUs. So if your files are large enough and you are not using SharedArray, that might mean that your script will run out of memory at some point. Additionally even if there is enough memory, k6 has a garbage collector (as it’s written in golang) and it will walk through all accessible objects (including JS ones) and figure out which need to be garbage collected. For big JS arrays copied hundreds of times this adds quite a lot of additional work.

A note on performance characteristics of SharedArray can be found within its API documentation.

From a JSON file

{
  "users": [
    { "username": "test", "password": "qwerty" },
    { "username": "test", "password": "qwerty" }
  ]
}

import { SharedArray } from 'k6/data';
// not using SharedArray here will mean that the code in the function call (that is what loads and
// parses the json) will be executed per each VU which also means that there will be a complete copy
// per each VU
const data = new SharedArray('some data name', function () {
  return JSON.parse(open('./data.json')).users;
});

export default function () {
  const user = data[0];
  console.log(data[0].username);
}

From a CSV file

k6 doesn’t parse CSV files natively, but you can use an external library, Papa Parse.

You can download the library and import it locally like this:

import papaparse from './papaparse.js';
import { SharedArray } from 'k6/data';
// not using SharedArray here will mean that the code in the function call (that is what loads and
// parses the csv) will be executed per each VU which also means that there will be a complete copy
// per each VU
const csvData = new SharedArray('another data name', function () {
  // Load CSV file and parse it using Papa Parse
  return papaparse.parse(open('./data.csv'), { header: true }).data;
});

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

Or you can grab it directly from jslib.k6.io like this.

import papaparse from 'https://jslib.k6.io/papaparse/5.1.1/index.js';
import { SharedArray } from 'k6/data';

// not using SharedArray here will mean that the code in the function call (that is what loads and
// parses the csv) will be executed per each VU which also means that there will be a complete copy
// per each VU
const csvData = new SharedArray('another data name', function () {
  // Load CSV file and parse it using Papa Parse
  return papaparse.parse(open('./data.csv'), { header: true }).data;
});

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

Here’s an example using Papa Parse to parse a CSV file of username/password pairs and using that data to login to the test.k6.io test site:

/*  Where contents of data.csv is:
username,password
admin,123
test_user,1234
*/
import http from 'k6/http';
import { check, sleep } from 'k6';
import { SharedArray } from 'k6/data';
import papaparse from 'https://jslib.k6.io/papaparse/5.1.1/index.js';

// not using SharedArray here will mean that the code in the function call (that is what loads and
// parses the csv) will be executed per each VU which also means that there will be a complete copy
// per each VU
const csvData = new SharedArray('another data name', function () {
  // Load CSV file and parse it using Papa Parse
  return papaparse.parse(open('./data.csv'), { header: true }).data;
});

export default function () {
  // Now you can use the CSV data in your test logic below.
  // Below are some examples of how you can access the CSV data.

  // Loop through all username/password pairs
  for (const userPwdPair of csvData) {
    console.log(JSON.stringify(userPwdPair));
  }

  // Pick a random username/password pair
  const randomUser = csvData[Math.floor(Math.random() * csvData.length)];
  console.log('Random user: ', JSON.stringify(randomUser));

  const params = {
    login: randomUser.username,
    password: randomUser.password,
  };
  console.log('Random user: ', JSON.stringify(params));

  const res = http.post('https://test.k6.io/login.php', params);
  check(res, {
    'login succeeded': (r) => r.status === 200 && r.body.indexOf('successfully authorized') !== -1,
  });

  sleep(1);
}

Retrieving unique data

It is often a requirement not to use the same data more than once in a test. With the help of k6/execution, which includes a property scenario.iterationInTest, you can retrieve unique rows from your dataset.

Note
scenario.iterationInTest property is unique per scenario, not the overall test. That means if you have multiple scenarios in your test you might need to split your data per scenario.

import { SharedArray } from 'k6/data';
import { scenario } from 'k6/execution';

const data = new SharedArray('users', function () {
  return JSON.parse(open('./data.json')).users;
});

export const options = {
  scenarios: {
    'use-all-the-data': {
      executor: 'shared-iterations',
      vus: 10,
      iterations: data.length,
      maxDuration: '1h',
    },
  },
};

export default function () {
  // this is unique even in the cloud
  const user = data[scenario.iterationInTest];
  console.log(`user: ${JSON.stringify(user)}`);
}

Alternatively, if your use case requires using a unique dataset per VU, you could leverage a property called vu.idInTest.

In the following example we’re going to be using per-vu-iterations executor to ensure that every VU completes a fixed amount of iterations.

import { sleep } from 'k6';
import { SharedArray } from 'k6/data';
import { vu } from 'k6/execution';

const users = new SharedArray('users', function () {
  return JSON.parse(open('./data.json')).users;
});

export const options = {
  scenarios: {
    login: {
      executor: 'per-vu-iterations',
      vus: users.length,
      iterations: 20,
      maxDuration: '1h30m',
    },
  },
};

export default function () {
  // VU identifiers are one-based and arrays are zero-based, thus we need - 1
  console.log(`Users name: ${users[vu.idInTest - 1].username}`);
  sleep(1);
}

If you have a large dataset and want to make sure no two VUs use the same value in the dataset at the same time, while keeping a fixed number of VUs, use the modulo operator (%) with the global iteration index. This gives you a round-robin assignment over the dataset and avoids collisions during a run.

import { sleep } from 'k6';
import { SharedArray } from 'k6/data';
import { scenario } from 'k6/execution';

const users = new SharedArray('users', function () {
  return JSON.parse(open('./data.json')).users;
});

const vus = 100;
export const options = {
  scenarios: {
    login: {
      executor: 'constant-vus',
      vus: vus,
      duration: '1h30m',
    },
  },
};

export default function () {
  console.log(`Users name: ${users[scenario.iterationInTest % vus].username}`);
  sleep(1);
}

Generating data using faker.js

The following articles show how to use faker.js in k6 to generate realistic data during the test execution:

Parse HTML

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

Parse HTML

Examples parsing HTML content. Use the k6/html module for HTML parsing.

Name	Type	Description
Selection	Class	A jQuery-like API for accessing HTML DOM elements.
Element	Class	An HTML DOM element as returned by the Selection API.
parseHTML(src)	function	Parse an HTML string and populate a Selection object.

import { parseHTML } from 'k6/html';
import http from 'k6/http';

export default function () {
  const res = http.get('https://k6.io');
  const doc = parseHTML(res.body); // equivalent to res.html()
  const pageTitle = doc.find('head title').text();
  const langAttr = doc.find('html').attr('lang');
}

import { parseHTML } from 'k6/html';
import { sleep } from 'k6';

export default function () {
  const content = `
<dl>
  <dt id="term-1">Value term 1</dt>
  <dt id="term-2">Value term 2</dt>
</dl>
  `;
  const sel = parseHTML(content).find('dl').children();

  const el1 = sel.get(0);
  const el2 = sel.get(1);

  console.log(el1.nodeName());
  console.log(el1.id());
  console.log(el1.textContent());

  console.log(el2.nodeName());
  console.log(el2.id());
  console.log(el2.textContent());

  sleep(1);
}

HTML Forms

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

HTML Forms

Scripting example on how to handle HTML forms.

In many cases using the Selection API (jQuery API clone) to interact with HTML data is enough, but for some use cases, like with forms, we can make things easier providing a higher-level API like the Response.submitForm( [params] ) API.

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

export default function () {
  // Request page containing a form
  let res = http.get('https://quickpizza.grafana.com/admin');

  // Now, submit form setting/overriding some fields of the form
  res = res.submitForm({
    formSelector: 'form',
    fields: { username: 'admin', password: 'admin' },
  });
  sleep(3);
}

Relevant k6 APIs:

Response.submitForm([params])
Selection.find(selector) (the jQuery Selector API docs are also a good resource on what possible selector queries can be made)

Cookies Example

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

Cookies Example

Scripting examples on how you can interact with cookies during your load test if required.

Cookies

As HTTP is a stateless protocol, cookies are used by server-side applications to persist data on client machines. This is used more or less everywhere on the web, commonly for user session tracking purposes. In k6 cookies are managed automatically by default, however, there are use cases where access to read and manipulate cookies are required.

From the response headers

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

export default function () {
  // Since this request redirects the `res.cookies` property won't contain the cookies
  const res = http.post('https://quickpizza.grafana.com/api/cookies?name1=value1&name2=value2');
  check(res, {
    'status is 200': (r) => r.status === 200,
  });

  // Make sure cookies have been added to VU cookie jar
  const vuJar = http.cookieJar();
  const cookiesForURL = vuJar.cookiesForURL(res.url);
  check(null, {
    "vu jar has cookie 'name1'": () => cookiesForURL.name1.length > 0,
    "vu jar has cookie 'name2'": () => cookiesForURL.name2.length > 0,
  });
}

Log all the cookies in a response

⚠️ Note that this only works when using k6 locally

The console.log() family of APIs are currently only usable when running k6 locally. When running k6 tests with LoadImpact Cloud Execution the logs will be discarded.

// Example showing two methods how to log all cookies (with attributes) from a HTTP response.

import http from 'k6/http';

function logCookie(cookie) {
  // Here we log the name and value of the cookie along with additional attributes.
  // For full list of attributes see: https:///grafana.com/docs/k6/using-k6/cookies#properties-of-a-response-cookie-object
  console.log(
    `${cookie.name}: ${cookie.value}\n\tdomain: ${cookie.domain}\n\tpath: ${cookie.path}\n\texpires: ${cookie.expires}\n\thttpOnly: ${cookie.http_only}`
  );
}

export default function () {
  const res = http.get('https://www.google.com/');

  // Method 1: Use for-loop and check for non-inherited properties
  for (const name in res.cookies) {
    if (res.cookies.hasOwnProperty(name) !== undefined) {
      logCookie(res.cookies[name][0]);
    }
  }

  // Method 2: Use ES6 Map to loop over Object entries
  new Map(Object.entries(res.cookies)).forEach((v, k) => logCookie(v[0]));
}

To set a cookie that should be sent with every request matching a particular domain, path, etc. you’d do something like this:

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

export default function () {
  // Get VU cookie jar and add a cookie to it providing the parameters
  // that a request must match (domain, path, HTTPS or not etc.)
  // to have the cookie attached to it when sent to the server.
  const jar = http.cookieJar();
  jar.set('https://quickpizza.grafana.com/api/cookies', 'my_cookie', 'hello world', {
    domain: 'quickpizza.grafana.com',
    path: '/api/cookies',
    secure: true,
    max_age: 600,
  });

  // As the following request is matching the above cookie in terms of domain,
  // path, HTTPS (secure) and will happen within the specified "age" limit, the
  // cookie will be attached to this request.
  const res = http.get('https://quickpizza.grafana.com/api/cookies');
  check(res, {
    'has status 200': (r) => r.status === 200,
    "has cookie 'my_cookie'": (r) => r.json().cookies.my_cookie !== null,
    'cookie has correct value': (r) => r.json().cookies.my_cookie == 'hello world',
  });
}

To delete a cookie in the jar for a specific URL and name, use the delete method.

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

export default function () {
  const jar = http.cookieJar();
  jar.set('https://quickpizza.grafana.com/api/cookies', 'my_cookie_1', 'hello world_1');
  jar.set('https://quickpizza.grafana.com/api/cookies', 'my_cookie_2', 'hello world_2');

  const res1 = http.get('https://quickpizza.grafana.com/api/cookies');
  check(res1, {
    'res1 has status 200': (r) => r.status === 200,
    "res1 has cookie 'my_cookie_1'": (r) => r.json().cookies.my_cookie_1 !== null,
    'res1 cookie has correct value_1': (r) => r.json().cookies.my_cookie_1 == 'hello world_1',
    "res1 has cookie 'my_cookie_2'": (r) => r.json().cookies.my_cookie_2 !== null,
    'res1 cookie has correct value_2': (r) => r.json().cookies.my_cookie_2 == 'hello world_2',
  });

  jar.delete('https://quickpizza.grafana.com/api/cookies', 'my_cookie_1');

  const res2 = http.get('https://quickpizza.grafana.com/api/cookies');
  check(res2, {
    'res2 has status 200': (r) => r.status === 200,
    "res2 hasn't cookie 'my_cookie_1'": (r) => r.json().cookies.my_cookie_1 == null,
    "res2 has cookie 'my_cookie_2'": (r) => r.json().cookies.my_cookie_2 !== null,
    'res2 cookie has correct value_2': (r) => r.json().cookies.my_cookie_2 == 'hello world_2',
  });
}

To clear all cookies in the jar by specifying url, use the clear method.

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

export default function () {
  const jar = http.cookieJar();
  jar.set('https://quickpizza.grafana.com/api/cookies', 'my_cookie', 'hello world');
  const res1 = http.get('https://quickpizza.grafana.com/api/cookies');
  check(res1, {
    'has status 200': (r) => r.status === 200,
    "has cookie 'my_cookie'": (r) => r.json().cookies.my_cookie !== null,
    'cookie has correct value': (r) => r.json().cookies.my_cookie == 'hello world',
  });

  jar.clear('https://quickpizza.grafana.com/api/cookies');

  const res2 = http.get('https://quickpizza.grafana.com/api/cookies');
  check(res2, {
    'has status 200': (r) => r.status === 200,
    "hasn't cookie 'my_cookie'": (r) => r.json().cookies.my_cookie == null,
  });
}

Relevant k6 APIs:

Data Uploads

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

Data Uploads

Example to execute a load test that will upload a file to the System Under Test (SUT).

The open() function

Using the built-in function open(), we can read the contents of a file given a filename or URL.

Below is a simple example showing how to load the contents of a local file data.json.

{
  "my_key": "has a value"
}

const data = JSON.parse(open('./data.json'));

export default function () {
  console.log(data.my_key);
}

If you want to open a binary file you need to pass in "b" as the second argument.

const binFile = open('./image.png', 'b');

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

Multipart request (uploading a file)

Now that you know how to load a local file, let’s look at a script that creates a POST request to upload this data to an API endpoint along with a regular text field (field in the example below):

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

const binFile = open('/path/to/file.bin', 'b');

export default function () {
  const data = {
    field: 'this is a standard form field',
    file: http.file(binFile, 'test.bin'),
  };

  const res = http.post('https://example.com/upload', data);
  sleep(3);
}

In the example above we use the http.file() API to wrap the file contents in a FileData object. When passing a JS object as the body parameter to http.post(), or any of the other HTTP request functions, where one of the property values is a FileData a multipart request will be constructed and sent.

Relevant k6 APIs

Advanced multipart request

The previous multipart request example has some limitations:

It’s not possible to assemble the parts in a specific order, because of the unordered nature of JS objects when they’re converted to Golang maps, which k6 uses internally. Uploading files in a specific order is a requirement for some APIs (e.g. AWS S3).
It’s not possible to upload multiple files as part of the same form field, because JS object keys must be unique.

To address this we suggest using the FormData polyfill for k6.

Here’s an example of uploading several binary files and a text file using the polyfill:

import http from 'k6/http';
import { check } from 'k6';
import { FormData } from 'https://jslib.k6.io/formdata/0.0.2/index.js';

const img1 = open('/path/to/image1.png', 'b');
const img2 = open('/path/to/image2.jpg', 'b');
const txt = open('/path/to/text.txt');

export default function () {
  const fd = new FormData();
  fd.append('someTextField', 'someValue');
  fd.append('aBinaryFile', {
    data: new Uint8Array(img1).buffer,
    filename: 'logo.png',
    content_type: 'image/png',
  });
  fd.append('anotherTextField', 'anotherValue');
  fd.append('images', http.file(img1, 'image1.png', 'image/png'));
  fd.append('images', http.file(img2, 'image2.jpg', 'image/jpeg'));
  fd.append('text', http.file(txt, 'text.txt', 'text/plain'));

  const res = http.post('https://quickpizza.grafana.com/api/post', fd.body(), {
    headers: { 'Content-Type': 'multipart/form-data; boundary=' + fd.boundary },
  });
  check(res, {
    'is status 200': (r) => r.status === 200,
  });
}

Note that:

Both binary files will be uploaded under the images form field, and the text file will appear last in the request under the text form field.
It’s required to specify the multipart boundary in the Content-Type header, so you must assemble the header manually as shown.
Blob is not supported or implemented. For the same functionality, use a simple object with the fields data, content_type (defaulting to “application/octet-stream”) and optionally filename as shown for aBinaryFile above.

API CRUD Operations

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

API CRUD Operations

The examples showcase the testing of CRUD operations on a REST API.

CRUD refers to the basic operations in a database: Create, Read, Update, and Delete. We can map these operations to HTTP methods in REST APIs:

Create: HTTP POST operation to create a new resource.
Read: HTTP GET to retrieve a resource.
Update: HTTP PUTor PATCH to change an existing resource.
Delete: HTTP DELETE to remove a resource.

This document has two examples, one that uses the core k6 APIs (k6/http and checks) and another to show the more recent APIs httpx and k6chaijs).

Test steps

In the setup() stage we create a user for QuickPizza. We then retrieve and return a bearer token to authenticate the next CRUD requests.

The steps implemented in the VU stage are as follows:

Create a new resource, a pizza rating.
Read the list of ratings.
Update the rating’s stars (e.g. to 5 stars) and read the rating to confirm the update operation.
Delete the rating resource.

Core k6 APIs example

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

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

// Create a random string of given length
function randomString(length, charset = '') {
  if (!charset) charset = 'abcdefghijklmnopqrstuvwxyz';
  let res = '';
  while (length--) res += charset[(Math.random() * charset.length) | 0];
  return res;
}

const USERNAME = `${randomString(10)}@example.com`; // Set your own email or `${randomString(10)}@example.com`;
const PASSWORD = 'secret';

const BASE_URL = 'https://quickpizza.grafana.com';

// Register a new user and retrieve authentication token for subsequent API requests
export function setup() {
  const res = http.post(
    `${BASE_URL}/api/users`,
    JSON.stringify({
      username: USERNAME,
      password: PASSWORD,
    })
  );

  check(res, { 'created user': (r) => r.status === 201 });

  const loginRes = http.post(
    `${BASE_URL}/api/users/token/login`,
    JSON.stringify({
      username: USERNAME,
      password: PASSWORD,
    })
  );

  const authToken = loginRes.json('token');
  check(authToken, { 'logged in successfully': () => authToken.length > 0 });

  return authToken;
}

export default function (authToken) {
  // set the authorization header on the session for the subsequent requests
  const requestConfigWithTag = (tag) => ({
    headers: {
      Authorization: `Bearer ${authToken}`,
    },
    tags: Object.assign(
      {},
      {
        name: 'PrivateRatings',
      },
      tag
    ),
  });

  let URL = `${BASE_URL}/api/ratings`;

  group('01. Create a new rating', () => {
    const payload = {
      stars: 2,
      pizza_id: 1, // Pizza ID 1 already exists in the database.
    };

    const res = http.post(URL, JSON.stringify(payload), requestConfigWithTag({ name: 'Create' }));

    if (check(res, { 'Rating created correctly': (r) => r.status === 201 })) {
      URL = `${URL}/${res.json('id')}`;
    } else {
      console.log(`Unable to create rating ${res.status} ${res.body}`);
      return;
    }
  });

  group('02. Fetch my ratings', () => {
    const res = http.get(`${BASE_URL}/api/ratings`, requestConfigWithTag({ name: 'Fetch' }));
    check(res, { 'retrieve ratings status': (r) => r.status === 200 });
    check(res.json(), { 'retrieved ratings list': (r) => r.ratings.length > 0 });
  });

  group('03. Update the rating', () => {
    const payload = { stars: 5 };
    const res = http.put(URL, JSON.stringify(payload), requestConfigWithTag({ name: 'Update' }));
    const isSuccessfulUpdate = check(res, {
      'Update worked': () => res.status === 200,
      'Updated stars number is correct': () => res.json('stars') === 5,
    });

    if (!isSuccessfulUpdate) {
      console.log(`Unable to update the rating ${res.status} ${res.body}`);
      return;
    }
  });

  group('04. Delete the rating', () => {
    const delRes = http.del(URL, null, requestConfigWithTag({ name: 'Delete' }));

    const isSuccessfulDelete = check(null, {
      'Rating was deleted correctly': () => delRes.status === 204,
    });

    if (!isSuccessfulDelete) {
      console.log('Rating was not deleted properly');
      return;
    }
  });
}

httpx and k6chaijs example

import { describe, expect } from 'https://jslib.k6.io/k6chaijs/4.3.4.3/index.js';
import { Httpx } from 'https://jslib.k6.io/httpx/0.1.0/index.js';
import {
  randomIntBetween,
  randomItem,
  randomString,
} from 'https://jslib.k6.io/k6-utils/1.2.0/index.js';

export const options = {
  // for the example, let's run only 1 VU with 1 iteration
  vus: 1,
  iterations: 1,
};

const USERNAME = `user${randomIntBetween(1, 100000)}@example.com`; // Set your own email;
const PASSWORD = 'secret';

const session = new Httpx({ baseURL: 'https://quickpizza.grafana.com' });

// Register a new user and retrieve authentication token for subsequent API requests
export function setup() {
  let authToken = null;

  describe(`setup - create a test user ${USERNAME}`, () => {
    const resp = session.post(
      `/api/users`,
      JSON.stringify({
        username: USERNAME,
        password: PASSWORD,
      })
    );

    expect(resp.status, 'User create status').to.equal(201);
    expect(resp, 'User create valid json response').to.have.validJsonBody();
  });

  describe(`setup - Authenticate the new user ${USERNAME}`, () => {
    const resp = session.post(
      `/api/users/token/login`,
      JSON.stringify({
        username: USERNAME,
        password: PASSWORD,
      })
    );

    expect(resp.status, 'Authenticate status').to.equal(200);
    expect(resp, 'Authenticate valid json response').to.have.validJsonBody();
    authToken = resp.json('token');
    expect(authToken, 'Authentication token').to.be.a('string');
  });

  return authToken;
}

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

  describe('01. Create a new rating', (t) => {
    const payload = {
      stars: 2,
      pizza_id: 1, // Pizza ID 1 already exists in the database
    };

    session.addTag('name', 'Create');
    const resp = session.post(`/api/ratings`, JSON.stringify(payload));

    expect(resp.status, 'Rating creation status').to.equal(201);
    expect(resp, 'Rating creation valid json response').to.have.validJsonBody();

    session.newRatingId = resp.json('id');
  });

  describe('02. Fetch my ratings', (t) => {
    session.clearTag('name');
    const resp = session.get('/api/ratings');

    expect(resp.status, 'Fetch ratings status').to.equal(200);
    expect(resp, 'Fetch ratings valid json response').to.have.validJsonBody();
    expect(resp.json('ratings').length, 'Number of ratings').to.be.above(0);
  });

  describe('03. Update the rating', (t) => {
    const payload = {
      stars: 5,
    };

    const resp = session.patch(`/api/ratings/${session.newRatingId}`, JSON.stringify(payload));

    expect(resp.status, 'Rating patch status').to.equal(200);
    expect(resp, 'Fetch rating valid json response').to.have.validJsonBody();
    expect(resp.json('stars'), 'Stars').to.equal(payload.stars);

    // read rating again to verify the update worked
    const resp1 = session.get(`/api/ratings/${session.newRatingId}`);

    expect(resp1.status, 'Fetch rating status').to.equal(200);
    expect(resp1, 'Fetch rating valid json response').to.have.validJsonBody();
    expect(resp1.json('stars'), 'Stars').to.equal(payload.stars);
  });

  describe('04. Delete the rating', (t) => {
    const resp = session.delete(`/api/ratings/${session.newRatingId}`);

    expect(resp.status, 'Rating delete status').to.equal(204);
  });
}

Generating UUIDs

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

Generating UUIDs

If you want to make a version 4 UUID, you can use the uuidv4 function from the k6 JS lib repository.

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
}

If you really need other UUID versions, you must rely on an external library.

Generate v1 UUIDs

As k6 doesn’t have built-in support for version 1 UUID, you’ll have to use a third-party library.

This example uses a Node.js library called uuid and Browserify (to make it work in k6). For this to work, we first need to go through a few required steps:

Make sure you have the necessary prerequisites installed: Node.js and Browserify
Install the uuid library:
Bash
```
npm install uuid@3.4.0
```

Run it through browserify:

browserify node_modules/uuid/index.js -s uuid > uuid.js

Move the uuid.js file to the same folder as your script file. Now you can import it into your test script:
JavaScript
```
import uuid from './uuid.js';
```

This example generates a v1 UUID:

import uuid from './uuid.js';

export default function () {
  // Generate a UUID v1
  const uuid1 = uuid.v1();
  console.log(uuid1);
}

HTTP2

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

HTTP2

If the target system indicates that a connection can be upgraded from HTTP/1.1 to HTTP/2, k6 will do so automatically.

Making HTTP/2 requests

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

export default function () {
  const res = http.get('https://quickpizza.grafana.com');
  check(res, {
    'status is 200': (r) => r.status === 200,
    'protocol is HTTP/2': (r) => r.proto === 'HTTP/2.0',
  });
}

Use global variables in k6

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

Use global variables in k6

A global variable is a variable that can be accessed from any scope. In the context of k6, global variables can be used to persist and pass information across iterations of a test run, and must be declared in the init stage.

A common use case is when you need to extract a value from a page, such as a CSRF or an API token, and reuse that across iterations of your test.

There are multiple ways to use global variables in JavaScript, each with benefits and drawbacks.

Before going into the examples, it’s important to note a caveat with how the k6 test lifecycle works, and how that can affect the usage of global variables.

VU isolation and global variables

In k6, variables defined in the init context are copied to each Virtual User (VU) when the test starts. Each VU runs in complete isolation from the others, so any changes made to global variables during the test are local to the VU making them.

This means that if you have, for example, 2 VUs and 4 iterations, and you increment a property on a global variable in each iteration, you might expect the final value to be 8. However, in reality, each VU will have its own copy, and the value will be 4 for each VU.

For read-only use-cases where you only use static values or set them once at the beginning, for example, in the setup() function, this is not a problem. But if you modify global variables during the test, remember that each VU has its own instance, and changes are not shared between VUs.

Refer to Test lifecycle for more details about the test lifecycle stages.

Option 1: use `import` and `export`

The first option is to declare a global variables object in your main script and export it.

import { doSomething, doSomethingElse } from './imported-script.js';

export const VARS = {};

export default function () {
  VARS.prop = 'prop1';

  doSomething();

  doSomethingElse();
  console.log(JSON.stringify(VARS));
}

You can then import the variable in your script, and use it across functions or alter the values:

import { VARS } from './main.js';

export function doSomething() {
  console.log(JSON.stringify(VARS));
}

export function doSomethingElse() {
  VARS.prop2 = 'prop2';
}

The advantage of using this method is the fact that you need to explicitly use the import and export statements. That can make it easier when working in a team, so other developers can understand your script logic and see where the variables and values came from.

Option 2: use `globalThis`

The second option is to use the globalThis JavaScript object, which is available in any JavaScript environment, not just k6.

For example, in your main script you can add a property to globalThis:

import { doSomething, doSomethingElse } from './imported-script.js';

globalThis.VARS = {};

export default function () {
  globalThis.VARS.prop = 'prop1';

  doSomething();

  doSomethingElse();
  console.log(JSON.stringify(globalThis.VARS));
}

And, similarly to the previous option, you can use access it from anywhere in that script or in imported scripts as well:

export function doSomething() {
  console.log(JSON.stringify(globalThis.VARS));
}

export function doSomethingElse() {
  globalThis.VARS.prop2 = 'prop2';
}

The advantage to using the globalThis object is that you don’t need to import or export a global variable. The downside is that, depending on how complex or extensive your test scripts are, using the globalThis variable can make your script more verbose, and cause unintended behavior if you’re not careful about how you’re using and setting global variables.

WebSockets

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

WebSockets

Here’s a load test for the QuickPizza WebSocket API, available on https://quickpizza.grafana.com/ws.

Multiple VUs connect using a VU-indexed user name, and send random messages.

Each VU receives messages sent by all other VUs.

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

const sessionDuration = randomIntBetween(3000, 6000); // user session between 3s and 6s

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

export default function () {
  const url = `wss://quickpizza.grafana.com/ws`;
  const params = { tags: { my_tag: 'my ws session' } };
  const user = `user_${__VU}`;

  const res = ws.connect(url, params, function (socket) {
    socket.on('open', function open() {
      console.log(`VU ${__VU}: connected`);

      socket.send(JSON.stringify({ msg: 'Hello!', user: user }));

      socket.setInterval(function timeout() {
        socket.send(
          JSON.stringify({
            user: user,
            msg: `I'm saying ${randomString(5)}`,
            foo: 'bar',
          })
        );
      }, randomIntBetween(1000, 2000)); // say something every 1-2 seconds
    });

    socket.on('ping', function () {
      console.log('PING!');
    });

    socket.on('pong', function () {
      console.log('PONG!');
    });

    socket.on('close', function () {
      console.log(`VU ${__VU}: disconnected`);
    });

    socket.on('message', function (message) {
      const data = JSON.parse(message);
      console.log(`VU ${__VU} received message: ${data.msg}`);
    });

    socket.setTimeout(function () {
      console.log(`VU ${__VU}: ${sessionDuration}ms passed, leaving the website`);
      socket.send(JSON.stringify({ msg: 'Goodbye!', user: user }));
    }, sessionDuration);

    socket.setTimeout(function () {
      console.log(`Closing the socket forcefully 3s after graceful LEAVE`);
      socket.close();
    }, sessionDuration + 3000);
  });

  check(res, { 'Connected successfully': (r) => r && r.status === 101 });
  sleep(1);
}

SOAP

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

SOAP

Although k6 doesn’t have any built-in APIs for working with SOAP or XML data in general, you can still easily load test a SOAP-based API by crafting SOAP messages and using the HTTP request APIs.

Making SOAP requests

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

const soapReqBody = `
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:hs="http://www.holidaywebservice.com/HolidayService_v2/">
    <soapenv:Body>
        <hs:GetHolidaysAvailable>
            <hs:countryCode>UnitedStates</hs:countryCode>
        </hs:GetHolidaysAvailable>
    </soapenv:Body>
</soapenv:Envelope>`;

export default function () {
  // When making a SOAP POST request we must not forget to set the content type to text/xml
  const res = http.post(
    'http://www.holidaywebservice.com/HolidayService_v2/HolidayService2.asmx',
    soapReqBody,
    {
      headers: { 'Content-Type': 'text/xml' },
    }
  );

  // Make sure the response is correct
  check(res, {
    'status is 200': (r) => r.status === 200,
    'black friday is present': (r) => r.body.indexOf('BLACK-FRIDAY') !== -1,
  });

  sleep(1);
}

Transport Layer Security (TLS)

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

Transport Layer Security (TLS)

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

export const options = {
  tlsCipherSuites: ['TLS_RSA_WITH_RC4_128_SHA', 'TLS_RSA_WITH_AES_128_GCM_SHA256'],
  tlsVersion: {
    min: 'ssl3.0',
    max: 'tls1.2',
  },
};

export default function () {
  const res = http.get('https://sha256.badssl.com');
  check(res, {
    'is TLSv1.2': (r) => r.tls_version === http.TLS_1_2,
    'is sha256 cipher suite': (r) => r.tls_cipher_suite === 'TLS_RSA_WITH_AES_128_GCM_SHA256',
  });
}

Generating realistic data

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

Generating realistic data

Refer to the grafana/k6-example-data-generation GitHub repository for an example of how to utilize k6 and Faker to generate realistic data for a load test.

Bundling and transpiling

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

Bundling and transpiling

For more details about bundling and transpiling, refer to JavaScript and TypeScript compatibility mode.

Functional testing

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

Functional testing

Most basic integration test

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

export const options = {
  thresholds: {
    checks: ['rate == 1.00'],
  },
};

export default function () {
  describe('Hello world!', () => {
    const response = http.get('https://quickpizza.grafana.com/api/ratings', {
      headers: { Authorization: 'Token abcdef0123456789' },
    });

    expect(response.status, 'response status').to.equal(200);
    expect(response).to.have.validJsonBody();
    expect(response.json('ratings'), 'ratings list').to.be.an('array');
  });
}

Sample integration test

This test goes through several steps. It creates a new user account, authenticates, and interacts with protected resources.

import chai, { describe, expect } from 'https://jslib.k6.io/k6chaijs/4.3.4.3/index.js';
import { Httpx, Get } from 'https://jslib.k6.io/httpx/0.0.6/index.js';
import { randomString } from 'https://jslib.k6.io/k6-utils/1.0.0/index.js';

chai.config.logFailures = true;

export let options = {
  thresholds: {
    // fail the test if any checks fail or any requests fail
    checks: ['rate == 1.00'],
    http_req_failed: ['rate == 0.00'],
  },
  vus: 1,
  iterations: 1,
};

let session = new Httpx({
  baseURL: 'https://quickpizza.grafana.com',
  headers: { Authorization: 'Token abcdef0123456789' },
});

function retrieveIndividualRatingsInABatch() {
  describe('[Ratings service] Fetch public ratings one by one', () => {
    let responses = session.batch([
      new Get('/api/ratings/1'),
      new Get('/api/ratings/2'),
      new Get('/api/ratings/3'),
    ]);

    expect(responses, 'responses').to.be.an('array');

    responses.forEach((response) => {
      expect(response.status, 'response status').to.equal(200);
      expect(response).to.have.validJsonBody();
      expect(response.json(), 'rating').to.be.an('object');
      expect(response.json(), 'rating').to.include.keys('id', 'stars', 'pizza_id');
      expect(response.json(), 'rating').to.not.have.a.property('language');
    });
  });
}

function retrieveAllPublicRatings() {
  describe('[Crocs service] Fetch a list of crocs', () => {
    let response = session.get('/api/ratings');

    expect(response.status, 'response status').to.equal(200);
    expect(response).to.have.validJsonBody();
    expect(response.json('ratings'), 'ratings list').to.be.an('array').lengthOf.above(2);
  });
}

function validateAuthService() {
  const USERNAME = `${randomString(10)}@example.com`;
  const PASSWORD = 'superCroc2021';

  describe('[Registration service] user registration', () => {
    let sampleUser = {
      username: USERNAME,
      password: PASSWORD,
    };

    let response = session.post(`/api/users`, JSON.stringify(sampleUser));

    expect(response.status, 'registration status').to.equal(201);
    expect(response).to.have.validJsonBody();
  });

  describe('[Auth service] user authentication', () => {
    let authData = {
      username: USERNAME,
      password: PASSWORD,
    };

    let resp = session.post(`/api/users/token/login`, JSON.stringify(authData));

    expect(resp.status, 'Auth status').to.be.within(200, 204);
    expect(resp).to.have.validJsonBody();
    expect(resp.json()).to.have.a.property('token');
    expect(resp.json('token'), 'auth token').to.be.a('string');

    let authToken = resp.json('token');
    // set the authorization header on the session for the subsequent requests.
    session.addHeader('Authorization', `Token ${authToken}`);
  });
}

function validateRatingCreation() {
  // authentication happened before this call.

  describe('[Ratings service] Create a new rating', () => {
    let payload = {
      stars: 2,
      pizza_id: 1,
    };

    let resp = session.post(`/api/ratings`, JSON.stringify(payload));

    expect(resp.status, 'Rating creation status').to.equal(201);
    expect(resp).to.have.validJsonBody();

    session.newRatingId = resp.json('id'); // caching ID for the future
  });

  describe('[Ratings service] Fetch private ratings', () => {
    let response = session.get('/api/ratings');

    expect(response.status, 'response status').to.equal(200);
    expect(response, 'ratings').to.have.validJsonBody();
    expect(response.json('ratings'), 'ratings').to.not.be.empty;
  });
}

export default function testSuite() {
  retrieveIndividualRatingsInABatch();
  retrieveAllPublicRatings();
  validateAuthService();
  validateRatingCreation();
}

Full example showcasing all functionality

Here’s an auto-generated k6 test script showcasing all examples from the Chaijs API documentation.

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

chai.config.aggregateChecks = false;
chai.config.logFailures = true;

export default function testSuite() {
  describe('docs example 0', () => {
    expect(function () {}).to.not.throw();
    expect({ a: 1 }).to.not.have.property('b');
    expect([1, 2]).to.be.an('array').that.does.not.include(3);
  });

  describe('docs example 1', () => {
    expect(2).to.equal(2); // Recommended
    expect(2).to.not.equal(1); // Not recommended
  });

  describe('docs example 2', () => {
    // Target object deeply (but not strictly) equals `{a: 1}`
    expect({ a: 1 }).to.deep.equal({ a: 1 });
    expect({ a: 1 }).to.not.equal({ a: 1 });

    // Target array deeply (but not strictly) includes `{a: 1}`
    expect([{ a: 1 }]).to.deep.include({ a: 1 });
    expect([{ a: 1 }]).to.not.include({ a: 1 });

    // Target object deeply (but not strictly) includes `x: {a: 1}`
    expect({ x: { a: 1 } }).to.deep.include({ x: { a: 1 } });
    expect({ x: { a: 1 } }).to.not.include({ x: { a: 1 } });

    // Target array deeply (but not strictly) has member `{a: 1}`
    expect([{ a: 1 }]).to.have.deep.members([{ a: 1 }]);
    expect([{ a: 1 }]).to.not.have.members([{ a: 1 }]);

    // Target set deeply (but not strictly) has key `{a: 1}`
    expect(new Set([{ a: 1 }])).to.have.deep.keys([{ a: 1 }]);
    expect(new Set([{ a: 1 }])).to.not.have.keys([{ a: 1 }]);

    // Target object deeply (but not strictly) has property `x: {a: 1}`
    expect({ x: { a: 1 } }).to.have.deep.property('x', { a: 1 });
    expect({ x: { a: 1 } }).to.not.have.property('x', { a: 1 });
  });

  describe('docs example 3', () => {
    expect({ a: { b: ['x', 'y'] } }).to.have.nested.property('a.b[1]');
    expect({ a: { b: ['x', 'y'] } }).to.nested.include({ 'a.b[1]': 'y' });
  });

  describe('docs example 4', () => {
    expect({ '.a': { '[b]': 'x' } }).to.have.nested.property('\\.a.\\[b\\]');
    expect({ '.a': { '[b]': 'x' } }).to.nested.include({ '\\.a.\\[b\\]': 'x' });
  });

  describe('docs example 5', () => {
    Object.prototype.b = 2;

    expect({ a: 1 }).to.have.own.property('a');
    expect({ a: 1 }).to.have.property('b');
    expect({ a: 1 }).to.not.have.own.property('b');

    expect({ a: 1 }).to.own.include({ a: 1 });
    expect({ a: 1 }).to.include({ b: 2 }).but.not.own.include({ b: 2 });
  });

  describe('docs example 6', () => {
    expect([1, 2]).to.have.ordered.members([1, 2]).but.not.have.ordered.members([2, 1]);
  });

  describe('docs example 7', () => {
    expect([1, 2, 3]).to.include.ordered.members([1, 2]).but.not.include.ordered.members([2, 3]);
  });

  describe('docs example 8', () => {
    expect({ a: 1, b: 2 }).to.not.have.any.keys('c', 'd');
  });

  describe('docs example 9', () => {
    expect({ a: 1, b: 2 }).to.have.all.keys('a', 'b');
  });

  describe('docs example 10', () => {
    expect('foo').to.be.a('string');
    expect({ a: 1 }).to.be.an('object');
    expect(null).to.be.a('null');
    expect(undefined).to.be.an('undefined');
    expect(new Error()).to.be.an('error');
    expect(Promise.resolve()).to.be.a('promise');
    expect(new Float32Array()).to.be.a('float32array');
    expect(Symbol()).to.be.a('symbol');
  });

  describe('docs example 11', () => {
    var myObj = {
      [Symbol.toStringTag]: 'myCustomType',
    };

    expect(myObj).to.be.a('myCustomType').but.not.an('object');
  });

  describe('docs example 12', () => {
    expect([1, 2, 3]).to.be.an('array').that.includes(2);
    expect([]).to.be.an('array').that.is.empty;
  });

  describe('docs example 13', () => {
    expect('foo').to.be.a('string'); // Recommended
    expect('foo').to.not.be.an('array'); // Not recommended
  });

  describe('docs example 14', () => {
    expect(1).to.be.a('string', 'nooo why fail??');
    expect(1, 'nooo why fail??').to.be.a('string');
  });

  describe('docs example 15', () => {
    expect({ b: 2 }).to.have.a.property('b');
  });

  describe('docs example 16', () => {
    expect('foobar').to.include('foo');
  });

  describe('docs example 17', () => {
    expect([1, 2, 3]).to.include(2);
  });

  describe('docs example 18', () => {
    expect({ a: 1, b: 2, c: 3 }).to.include({ a: 1, b: 2 });
  });

  describe('docs example 19', () => {
    expect(new Set([1, 2])).to.include(2);
  });

  describe('docs example 20', () => {
    expect(
      new Map([
        ['a', 1],
        ['b', 2],
      ])
    ).to.include(2);
  });

  describe('docs example 21', () => {
    expect([1, 2, 3]).to.be.an('array').that.includes(2);
  });

  describe('docs example 22', () => {
    // Target array deeply (but not strictly) includes `{a: 1}`
    expect([{ a: 1 }]).to.deep.include({ a: 1 });
    expect([{ a: 1 }]).to.not.include({ a: 1 });

    // Target object deeply (but not strictly) includes `x: {a: 1}`
    expect({ x: { a: 1 } }).to.deep.include({ x: { a: 1 } });
    expect({ x: { a: 1 } }).to.not.include({ x: { a: 1 } });
  });

  describe('docs example 23', () => {
    Object.prototype.b = 2;

    expect({ a: 1 }).to.own.include({ a: 1 });
    expect({ a: 1 }).to.include({ b: 2 }).but.not.own.include({ b: 2 });
  });

  describe('docs example 24', () => {
    expect({ a: { b: 2 } }).to.deep.own.include({ a: { b: 2 } });
  });

  describe('docs example 25', () => {
    expect({ a: { b: ['x', 'y'] } }).to.nested.include({ 'a.b[1]': 'y' });
  });

  describe('docs example 26', () => {
    expect({ '.a': { '[b]': 2 } }).to.nested.include({ '\\.a.\\[b\\]': 2 });
  });

  describe('docs example 27', () => {
    expect({ a: { b: [{ c: 3 }] } }).to.deep.nested.include({ 'a.b[0]': { c: 3 } });
  });

  describe('docs example 28', () => {
    expect('foobar').to.not.include('taco');
    expect([1, 2, 3]).to.not.include(4);
  });

  describe('docs example 29', () => {
    expect({ c: 3 }).to.not.have.any.keys('a', 'b'); // Recommended
    expect({ c: 3 }).to.not.include({ a: 1, b: 2 }); // Not recommended
  });

  describe('docs example 30', () => {
    expect({ a: 3, b: 4 }).to.include({ a: 3, b: 4 }); // Recommended
    expect({ a: 3, b: 4 }).to.not.include({ a: 1, b: 2 }); // Not recommended
  });

  describe('docs example 31', () => {
    expect([1, 2, 3]).to.include(4, 'nooo why fail??');
    expect([1, 2, 3], 'nooo why fail??').to.include(4);
  });

  describe('docs example 32', () => {
    // Target object's keys are a superset of ['a', 'b'] but not identical
    expect({ a: 1, b: 2, c: 3 }).to.include.all.keys('a', 'b');
    expect({ a: 1, b: 2, c: 3 }).to.not.have.all.keys('a', 'b');

    // Target array is a superset of [1, 2] but not identical
    expect([1, 2, 3]).to.include.members([1, 2]);
    expect([1, 2, 3]).to.not.have.members([1, 2]);

    // Duplicates in the subset are ignored
    expect([1, 2, 3]).to.include.members([1, 2, 2, 2]);
  });

  describe('docs example 33', () => {
    // Both assertions are identical
    expect({ a: 1 }).to.include.any.keys('a', 'b');
    expect({ a: 1 }).to.have.any.keys('a', 'b');
  });

  describe('docs example 34', () => {
    expect(1).to.equal(1); // Recommended
    expect(1).to.be.ok; // Not recommended

    expect(true).to.be.true; // Recommended
    expect(true).to.be.ok; // Not recommended
  });

  describe('docs example 35', () => {
    expect(0).to.equal(0); // Recommended
    expect(0).to.not.be.ok; // Not recommended

    expect(false).to.be.false; // Recommended
    expect(false).to.not.be.ok; // Not recommended

    expect(null).to.be.null; // Recommended
    expect(null).to.not.be.ok; // Not recommended

    expect(undefined).to.be.undefined; // Recommended
    expect(undefined).to.not.be.ok; // Not recommended
  });

  describe('docs example 36', () => {
    expect(false, 'nooo why fail??').to.be.ok;
  });

  describe('docs example 37', () => {
    expect(true).to.be.true;
  });

  describe('docs example 38', () => {
    expect(false).to.be.false; // Recommended
    expect(false).to.not.be.true; // Not recommended

    expect(1).to.equal(1); // Recommended
    expect(1).to.not.be.true; // Not recommended
  });

  describe('docs example 39', () => {
    expect(false, 'nooo why fail??').to.be.true;
  });

  describe('docs example 40', () => {
    expect(false).to.be.false;
  });

  describe('docs example 41', () => {
    expect(true).to.be.true; // Recommended
    expect(true).to.not.be.false; // Not recommended

    expect(1).to.equal(1); // Recommended
    expect(1).to.not.be.false; // Not recommended
  });

  describe('docs example 42', () => {
    expect(true, 'nooo why fail??').to.be.false;
  });

  describe('docs example 43', () => {
    expect(null).to.be.null;
  });

  describe('docs example 44', () => {
    expect(1).to.equal(1); // Recommended
    expect(1).to.not.be.null; // Not recommended
  });

  describe('docs example 45', () => {
    expect(42, 'nooo why fail??').to.be.null;
  });

  describe('docs example 46', () => {
    expect(undefined).to.be.undefined;
  });

  describe('docs example 47', () => {
    expect(1).to.equal(1); // Recommended
    expect(1).to.not.be.undefined; // Not recommended
  });

  describe('docs example 48', () => {
    expect(42, 'nooo why fail??').to.be.undefined;
  });

  describe('docs example 49', () => {
    expect(NaN).to.be.NaN;
  });

  describe('docs example 50', () => {
    expect('foo').to.equal('foo'); // Recommended
    expect('foo').to.not.be.NaN; // Not recommended
  });

  describe('docs example 51', () => {
    expect(42, 'nooo why fail??').to.be.NaN;
  });

  describe('docs example 52', () => {
    expect(1).to.equal(1); // Recommended
    expect(1).to.exist; // Not recommended

    expect(0).to.equal(0); // Recommended
    expect(0).to.exist; // Not recommended
  });

  describe('docs example 53', () => {
    expect(null).to.be.null; // Recommended
    expect(null).to.not.exist; // Not recommended

    expect(undefined).to.be.undefined; // Recommended
    expect(undefined).to.not.exist; // Not recommended
  });

  describe('docs example 54', () => {
    expect(null, 'nooo why fail??').to.exist;
  });

  describe('docs example 55', () => {
    expect([]).to.be.empty;
    expect('').to.be.empty;
  });

  describe('docs example 56', () => {
    expect(new Set()).to.be.empty;
    expect(new Map()).to.be.empty;
  });

  describe('docs example 57', () => {
    expect({}).to.be.empty;
  });

  describe('docs example 58', () => {
    expect([]).to.be.an('array').that.is.empty;
  });

  describe('docs example 59', () => {
    expect([1, 2, 3]).to.have.lengthOf(3); // Recommended
    expect([1, 2, 3]).to.not.be.empty; // Not recommended

    expect(new Set([1, 2, 3])).to.have.property('size', 3); // Recommended
    expect(new Set([1, 2, 3])).to.not.be.empty; // Not recommended

    expect(Object.keys({ a: 1 })).to.have.lengthOf(1); // Recommended
    expect({ a: 1 }).to.not.be.empty; // Not recommended
  });

  describe('docs example 60', () => {
    expect([1, 2, 3], 'nooo why fail??').to.be.empty;
  });

  describe('docs example 61', () => {
    function test() {
      expect(arguments).to.be.arguments;
    }

    test();
  });

  describe('docs example 62', () => {
    expect('foo').to.be.a('string'); // Recommended
    expect('foo').to.not.be.arguments; // Not recommended
  });

  describe('docs example 63', () => {
    expect({}, 'nooo why fail??').to.be.arguments;
  });

  describe('docs example 64', () => {
    expect(1).to.equal(1);
    expect('foo').to.equal('foo');
  });

  describe('docs example 65', () => {
    // Target object deeply (but not strictly) equals `{a: 1}`
    expect({ a: 1 }).to.deep.equal({ a: 1 });
    expect({ a: 1 }).to.not.equal({ a: 1 });

    // Target array deeply (but not strictly) equals `[1, 2]`
    expect([1, 2]).to.deep.equal([1, 2]);
    expect([1, 2]).to.not.equal([1, 2]);
  });

  describe('docs example 66', () => {
    expect(1).to.equal(1); // Recommended
    expect(1).to.not.equal(2); // Not recommended
  });

  describe('docs example 67', () => {
    expect(1).to.equal(2, 'nooo why fail??');
    expect(1, 'nooo why fail??').to.equal(2);
  });

  describe('docs example 68', () => {
    // Target object is deeply (but not strictly) equal to {a: 1}
    expect({ a: 1 }).to.eql({ a: 1 }).but.not.equal({ a: 1 });

    // Target array is deeply (but not strictly) equal to [1, 2]
    expect([1, 2]).to.eql([1, 2]).but.not.equal([1, 2]);
  });

  describe('docs example 69', () => {
    expect({ a: 1 }).to.eql({ a: 1 }); // Recommended
    expect({ a: 1 }).to.not.eql({ b: 2 }); // Not recommended
  });

  describe('docs example 70', () => {
    expect({ a: 1 }).to.eql({ b: 2 }, 'nooo why fail??');
    expect({ a: 1 }, 'nooo why fail??').to.eql({ b: 2 });
  });

  describe('docs example 71', () => {
    expect(2).to.equal(2); // Recommended
    expect(2).to.be.above(1); // Not recommended
  });

  describe('docs example 72', () => {
    expect('foo').to.have.lengthOf(3); // Recommended
    expect('foo').to.have.lengthOf.above(2); // Not recommended

    expect([1, 2, 3]).to.have.lengthOf(3); // Recommended
    expect([1, 2, 3]).to.have.lengthOf.above(2); // Not recommended
  });

  describe('docs example 73', () => {
    expect(2).to.equal(2); // Recommended
    expect(1).to.not.be.above(2); // Not recommended
  });

  describe('docs example 74', () => {
    expect(1).to.be.above(2, 'nooo why fail??');
    expect(1, 'nooo why fail??').to.be.above(2);
  });

  describe('docs example 75', () => {
    expect(2).to.equal(2); // Recommended
    expect(2).to.be.at.least(1); // Not recommended
    expect(2).to.be.at.least(2); // Not recommended
  });

  describe('docs example 76', () => {
    expect('foo').to.have.lengthOf(3); // Recommended
    expect('foo').to.have.lengthOf.at.least(2); // Not recommended

    expect([1, 2, 3]).to.have.lengthOf(3); // Recommended
    expect([1, 2, 3]).to.have.lengthOf.at.least(2); // Not recommended
  });

  describe('docs example 77', () => {
    expect(1).to.equal(1); // Recommended
    expect(1).to.not.be.at.least(2); // Not recommended
  });

  describe('docs example 78', () => {
    expect(1).to.be.at.least(2, 'nooo why fail??');
    expect(1, 'nooo why fail??').to.be.at.least(2);
  });

  describe('docs example 79', () => {
    expect(1).to.equal(1); // Recommended
    expect(1).to.be.below(2); // Not recommended
  });

  describe('docs example 80', () => {
    expect('foo').to.have.lengthOf(3); // Recommended
    expect('foo').to.have.lengthOf.below(4); // Not recommended

    expect([1, 2, 3]).to.have.length(3); // Recommended
    expect([1, 2, 3]).to.have.lengthOf.below(4); // Not recommended
  });

  describe('docs example 81', () => {
    expect(2).to.equal(2); // Recommended
    expect(2).to.not.be.below(1); // Not recommended
  });

  describe('docs example 82', () => {
    expect(2).to.be.below(1, 'nooo why fail??');
    expect(2, 'nooo why fail??').to.be.below(1);
  });

  describe('docs example 83', () => {
    expect(1).to.equal(1); // Recommended
    expect(1).to.be.at.most(2); // Not recommended
    expect(1).to.be.at.most(1); // Not recommended
  });

  describe('docs example 84', () => {
    expect('foo').to.have.lengthOf(3); // Recommended
    expect('foo').to.have.lengthOf.at.most(4); // Not recommended

    expect([1, 2, 3]).to.have.lengthOf(3); // Recommended
    expect([1, 2, 3]).to.have.lengthOf.at.most(4); // Not recommended
  });

  describe('docs example 85', () => {
    expect(2).to.equal(2); // Recommended
    expect(2).to.not.be.at.most(1); // Not recommended
  });

  describe('docs example 86', () => {
    expect(2).to.be.at.most(1, 'nooo why fail??');
    expect(2, 'nooo why fail??').to.be.at.most(1);
  });

  describe('docs example 87', () => {
    expect(2).to.equal(2); // Recommended
    expect(2).to.be.within(1, 3); // Not recommended
    expect(2).to.be.within(2, 3); // Not recommended
    expect(2).to.be.within(1, 2); // Not recommended
  });

  describe('docs example 88', () => {
    expect('foo').to.have.lengthOf.within(2, 4); // Not recommended

    expect([1, 2, 3]).to.have.lengthOf(3); // Recommended
    expect([1, 2, 3]).to.have.lengthOf.within(2, 4); // Not recommended
  });

  describe('docs example 89', () => {
    expect(1).to.equal(1); // Recommended
    expect(1).to.not.be.within(2, 4); // Not recommended
  });

  describe('docs example 90', () => {
    expect(4).to.be.within(1, 3, 'nooo why fail??');
    expect(4, 'nooo why fail??').to.be.within(1, 3);
  });

  describe('docs example 91', () => {
    function Cat() {}

    expect(new Cat()).to.be.an.instanceof(Cat);
    expect([1, 2]).to.be.an.instanceof(Array);
  });

  describe('docs example 92', () => {
    expect({ a: 1 }).to.not.be.an.instanceof(Array);
  });

  describe('docs example 93', () => {
    expect(1).to.be.an.instanceof(Array, 'nooo why fail??');
    expect(1, 'nooo why fail??').to.be.an.instanceof(Array);
  });

  describe('docs example 94', () => {
    expect({ a: 1 }).to.have.property('a');
  });

  describe('docs example 95', () => {
    expect({ a: 1 }).to.have.property('a', 1);
  });

  describe('docs example 96', () => {
    // Target object deeply (but not strictly) has property `x: {a: 1}`
    expect({ x: { a: 1 } }).to.have.deep.property('x', { a: 1 });
    expect({ x: { a: 1 } }).to.not.have.property('x', { a: 1 });
  });

  describe('docs example 97', () => {
    Object.prototype.b = 2;

    expect({ a: 1 }).to.have.own.property('a');
    expect({ a: 1 }).to.have.own.property('a', 1);
    expect({ a: 1 }).to.have.property('b');
    expect({ a: 1 }).to.not.have.own.property('b');
  });

  describe('docs example 98', () => {
    expect({ x: { a: 1 } }).to.have.deep.own.property('x', { a: 1 });
  });

  describe('docs example 99', () => {
    expect({ a: { b: ['x', 'y'] } }).to.have.nested.property('a.b[1]');
    expect({ a: { b: ['x', 'y'] } }).to.have.nested.property('a.b[1]', 'y');
  });

  describe('docs example 100', () => {
    expect({ '.a': { '[b]': 'x' } }).to.have.nested.property('\\.a.\\[b\\]');
  });

  describe('docs example 101', () => {
    expect({ a: { b: [{ c: 3 }] } }).to.have.deep.nested.property('a.b[0]', { c: 3 });
  });

  describe('docs example 102', () => {
    expect({ a: 1 }).to.not.have.property('b');
  });

  describe('docs example 103', () => {
    expect({ b: 2 }).to.not.have.property('a'); // Recommended
    expect({ b: 2 }).to.not.have.property('a', 1); // Not recommended
  });

  describe('docs example 104', () => {
    expect({ a: 3 }).to.have.property('a', 3); // Recommended
    expect({ a: 3 }).to.not.have.property('a', 1); // Not recommended
  });

  describe('docs example 105', () => {
    expect({ a: 1 }).to.have.property('a').that.is.a('number');
  });

  describe('docs example 106', () => {
    // Recommended
    expect({ a: 1 }).to.have.property('a', 2, 'nooo why fail??');
    expect({ a: 1 }, 'nooo why fail??').to.have.property('a', 2);
    expect({ a: 1 }, 'nooo why fail??').to.have.property('b');

    // Not recommended
    expect({ a: 1 }).to.have.property('b', undefined, 'nooo why fail??');
  });

  describe('docs example 107', () => {
    expect({ a: 1 }).to.have.ownPropertyDescriptor('a');
  });

  describe('docs example 108', () => {
    expect({ a: 1 }).to.have.ownPropertyDescriptor('a', {
      configurable: true,
      enumerable: true,
      writable: true,
      value: 1,
    });
  });

  describe('docs example 109', () => {
    expect({ a: 1 }).to.not.have.ownPropertyDescriptor('b');
  });

  describe('docs example 110', () => {
    // Recommended
    expect({ b: 2 }).to.not.have.ownPropertyDescriptor('a');

    // Not recommended
    expect({ b: 2 }).to.not.have.ownPropertyDescriptor('a', {
      configurable: true,
      enumerable: true,
      writable: true,
      value: 1,
    });
  });

  describe('docs example 111', () => {
    // Recommended
    expect({ a: 3 }).to.have.ownPropertyDescriptor('a', {
      configurable: true,
      enumerable: true,
      writable: true,
      value: 3,
    });

    // Not recommended
    expect({ a: 3 }).to.not.have.ownPropertyDescriptor('a', {
      configurable: true,
      enumerable: true,
      writable: true,
      value: 1,
    });
  });

  describe('docs example 112', () => {
    expect({ a: 1 }).to.have.ownPropertyDescriptor('a').that.has.property('enumerable', true);
  });

  describe('docs example 113', () => {
    // Recommended
    expect({ a: 1 }).to.have.ownPropertyDescriptor(
      'a',
      {
        configurable: true,
        enumerable: true,
        writable: true,
        value: 2,
      },
      'nooo why fail??'
    );

    // Recommended
    expect({ a: 1 }, 'nooo why fail??').to.have.ownPropertyDescriptor('a', {
      configurable: true,
      enumerable: true,
      writable: true,
      value: 2,
    });

    // Recommended
    expect({ a: 1 }, 'nooo why fail??').to.have.ownPropertyDescriptor('b');

    // Not recommended
    expect({ a: 1 }).to.have.ownPropertyDescriptor('b', undefined, 'nooo why fail??');
  });

  describe('docs example 114', () => {
    expect([1, 2, 3]).to.have.lengthOf(3);
    expect('foo').to.have.lengthOf(3);
    expect(new Set([1, 2, 3])).to.have.lengthOf(3);
    expect(
      new Map([
        ['a', 1],
        ['b', 2],
        ['c', 3],
      ])
    ).to.have.lengthOf(3);
  });

  describe('docs example 115', () => {
    expect('foo').to.have.lengthOf(3); // Recommended
    expect('foo').to.not.have.lengthOf(4); // Not recommended
  });

  describe('docs example 116', () => {
    expect([1, 2, 3]).to.have.lengthOf(2, 'nooo why fail??');
    expect([1, 2, 3], 'nooo why fail??').to.have.lengthOf(2);
  });

  describe('docs example 117', () => {
    // Recommended
    expect([1, 2, 3]).to.have.lengthOf(3);

    // Not recommended
    expect([1, 2, 3]).to.have.lengthOf.above(2);
    expect([1, 2, 3]).to.have.lengthOf.below(4);
    expect([1, 2, 3]).to.have.lengthOf.at.least(3);
    expect([1, 2, 3]).to.have.lengthOf.at.most(3);
    expect([1, 2, 3]).to.have.lengthOf.within(2, 4);
  });

  describe('docs example 118', () => {
    expect([1, 2, 3]).to.have.a.length(3); // incompatible; throws error
    expect([1, 2, 3]).to.have.a.lengthOf(3); // passes as expected
  });

  describe('docs example 119', () => {
    expect('foobar').to.match(/^foo/);
  });

  describe('docs example 120', () => {
    expect('foobar').to.not.match(/taco/);
  });

  describe('docs example 121', () => {
    expect('foobar').to.match(/taco/, 'nooo why fail??');
    expect('foobar', 'nooo why fail??').to.match(/taco/);
  });

  describe('docs example 122', () => {
    expect('foobar').to.have.string('bar');
  });

  describe('docs example 123', () => {
    expect('foobar').to.not.have.string('taco');
  });

  describe('docs example 124', () => {
    expect('foobar').to.have.string('taco', 'nooo why fail??');
    expect('foobar', 'nooo why fail??').to.have.string('taco');
  });

  describe('docs example 125', () => {
    expect({ a: 1, b: 2 }).to.have.all.keys('a', 'b');
    expect(['x', 'y']).to.have.all.keys(0, 1);

    expect({ a: 1, b: 2 }).to.have.all.keys(['a', 'b']);
    expect(['x', 'y']).to.have.all.keys([0, 1]);

    expect({ a: 1, b: 2 }).to.have.all.keys({ a: 4, b: 5 }); // ignore 4 and 5
    expect(['x', 'y']).to.have.all.keys({ 0: 4, 1: 5 }); // ignore 4 and 5
  });

  describe('docs example 126', () => {
    expect(
      new Map([
        ['a', 1],
        ['b', 2],
      ])
    ).to.have.all.keys('a', 'b');
    expect(new Set(['a', 'b'])).to.have.all.keys('a', 'b');
  });

  describe('docs example 127', () => {
    expect({ a: 1, b: 2 }).to.be.an('object').that.has.all.keys('a', 'b');
  });

  describe('docs example 128', () => {
    // Target set deeply (but not strictly) has key `{a: 1}`
    expect(new Set([{ a: 1 }])).to.have.all.deep.keys([{ a: 1 }]);
    expect(new Set([{ a: 1 }])).to.not.have.all.keys([{ a: 1 }]);
  });

  describe('docs example 129', () => {
    // Recommended; asserts that target doesn't have any of the given keys
    expect({ a: 1, b: 2 }).to.not.have.any.keys('c', 'd');

    // Not recommended; asserts that target doesn't have all of the given
    // keys but may or may not have some of them
    expect({ a: 1, b: 2 }).to.not.have.all.keys('c', 'd');
  });

  describe('docs example 130', () => {
    // Recommended; asserts that target has all the given keys
    expect({ a: 1, b: 2 }).to.have.all.keys('a', 'b');

    // Not recommended; asserts that target has at least one of the given
    // keys but may or may not have more of them
    expect({ a: 1, b: 2 }).to.have.any.keys('a', 'b');
  });

  describe('docs example 131', () => {
    // Both assertions are identical
    expect({ a: 1, b: 2 }).to.have.all.keys('a', 'b'); // Recommended
    expect({ a: 1, b: 2 }).to.have.keys('a', 'b'); // Not recommended
  });

  describe('docs example 132', () => {
    // Target object's keys are a superset of ['a', 'b'] but not identical
    expect({ a: 1, b: 2, c: 3 }).to.include.all.keys('a', 'b');
    expect({ a: 1, b: 2, c: 3 }).to.not.have.all.keys('a', 'b');
  });

  describe('docs example 133', () => {
    // Both assertions are identical
    expect({ a: 1 }).to.have.any.keys('a', 'b');
    expect({ a: 1 }).to.include.any.keys('a', 'b');
  });

  describe('docs example 134', () => {
    expect({ a: 1 }, 'nooo why fail??').to.have.key('b');
  });

  describe('docs example 135', () => {
    var badFn = function () {
      throw new TypeError('Illegal salmon!');
    };

    expect(badFn).to.throw();
  });

  describe('docs example 136', () => {
    var badFn = function () {
      throw new TypeError('Illegal salmon!');
    };

    expect(badFn).to.throw(TypeError);
  });

  describe('docs example 137', () => {
    var err = new TypeError('Illegal salmon!');
    var badFn = function () {
      throw err;
    };

    expect(badFn).to.throw(err);
  });

  describe('docs example 138', () => {
    var badFn = function () {
      throw new TypeError('Illegal salmon!');
    };

    expect(badFn).to.throw('salmon');
  });

  describe('docs example 139', () => {
    var badFn = function () {
      throw new TypeError('Illegal salmon!');
    };

    expect(badFn).to.throw(/salmon/);
  });

  describe('docs example 140', () => {
    var err = new TypeError('Illegal salmon!');
    var badFn = function () {
      throw err;
    };

    expect(badFn).to.throw(TypeError, 'salmon');
    expect(badFn).to.throw(TypeError, /salmon/);
    expect(badFn).to.throw(err, 'salmon');
    expect(badFn).to.throw(err, /salmon/);
  });

  describe('docs example 141', () => {
    var goodFn = function () {};

    expect(goodFn).to.not.throw();
  });

  describe('docs example 142', () => {
    var goodFn = function () {};

    expect(goodFn).to.not.throw(); // Recommended
    expect(goodFn).to.not.throw(ReferenceError, 'x'); // Not recommended
  });

  describe('docs example 143', () => {
    var badFn = function () {
      throw new TypeError('Illegal salmon!');
    };

    expect(badFn).to.throw(TypeError, 'salmon'); // Recommended
    expect(badFn).to.not.throw(ReferenceError, 'x'); // Not recommended
  });

  describe('docs example 144', () => {
    var err = new TypeError('Illegal salmon!');
    err.code = 42;
    var badFn = function () {
      throw err;
    };

    expect(badFn).to.throw(TypeError).with.property('code', 42);
  });

  describe('docs example 145', () => {
    var goodFn = function () {};

    expect(goodFn).to.throw(TypeError, 'x', 'nooo why fail??');
    expect(goodFn, 'nooo why fail??').to.throw();
  });

  describe('docs example 146', () => {
    var fn = function () {
      throw new TypeError('Illegal salmon!');
    };

    expect(fn).to.throw(); // Good! Tests `fn` as desired
    expect(fn()).to.throw(); // Bad! Tests result of `fn()`, not `fn`
  });

  describe('docs example 147', () => {
    expect(function () {
      fn(42);
    }).to.throw(); // Function expression
    expect(() => fn(42)).to.throw(); // ES6 arrow function
  });

  describe('docs example 148', () => {
    expect(function () {
      cat.meow();
    }).to.throw(); // Function expression
    expect(() => cat.meow()).to.throw(); // ES6 arrow function
    expect(cat.meow.bind(cat)).to.throw(); // Bind
  });

  describe('docs example 149', () => {
    function Cat() {}
    Cat.prototype.meow = function () {};

    expect(new Cat()).to.respondTo('meow');
  });

  describe('docs example 150', () => {
    function Cat() {}
    Cat.prototype.meow = function () {};

    expect(Cat).to.respondTo('meow');
  });

  describe('docs example 151', () => {
    function Cat() {}
    Cat.prototype.meow = function () {};
    Cat.hiss = function () {};

    expect(Cat).itself.to.respondTo('hiss').but.not.respondTo('meow');
  });

  describe('docs example 152', () => {
    function Cat() {}
    Cat.prototype.meow = function () {};

    expect(new Cat()).to.be.an('object').that.respondsTo('meow');
  });

  describe('docs example 153', () => {
    function Dog() {}
    Dog.prototype.bark = function () {};

    expect(new Dog()).to.not.respondTo('meow');
  });

  describe('docs example 154', () => {
    expect({}).to.respondTo('meow', 'nooo why fail??');
    expect({}, 'nooo why fail??').to.respondTo('meow');
  });

  describe('docs example 155', () => {
    function Cat() {}
    Cat.prototype.meow = function () {};
    Cat.hiss = function () {};

    expect(Cat).itself.to.respondTo('hiss').but.not.respondTo('meow');
  });

  describe('docs example 156', () => {
    expect(1).to.satisfy(function (num) {
      return num > 0;
    });
  });

  describe('docs example 157', () => {
    expect(1).to.not.satisfy(function (num) {
      return num > 2;
    });
  });

  describe('docs example 158', () => {
    expect(1).to.satisfy(function (num) {
      return num > 2;
    }, 'nooo why fail??');

    expect(1, 'nooo why fail??').to.satisfy(function (num) {
      return num > 2;
    });
  });

  describe('docs example 159', () => {
    // Recommended
    expect(1.5).to.equal(1.5);

    // Not recommended
    expect(1.5).to.be.closeTo(1, 0.5);
    expect(1.5).to.be.closeTo(2, 0.5);
    expect(1.5).to.be.closeTo(1, 1);
  });

  describe('docs example 160', () => {
    expect(1.5).to.equal(1.5); // Recommended
    expect(1.5).to.not.be.closeTo(3, 1); // Not recommended
  });

  describe('docs example 161', () => {
    expect(1.5).to.be.closeTo(3, 1, 'nooo why fail??');
    expect(1.5, 'nooo why fail??').to.be.closeTo(3, 1);
  });

  describe('docs example 162', () => {
    expect([1, 2, 3]).to.have.members([2, 1, 3]);
    expect([1, 2, 2]).to.have.members([2, 1, 2]);
  });

  describe('docs example 163', () => {
    // Target array deeply (but not strictly) has member `{a: 1}`
    expect([{ a: 1 }]).to.have.deep.members([{ a: 1 }]);
    expect([{ a: 1 }]).to.not.have.members([{ a: 1 }]);
  });

  describe('docs example 164', () => {
    expect([1, 2, 3]).to.have.ordered.members([1, 2, 3]);
    expect([1, 2, 3]).to.have.members([2, 1, 3]).but.not.ordered.members([2, 1, 3]);
  });

  describe('docs example 165', () => {
    // Target array is a superset of [1, 2] but not identical
    expect([1, 2, 3]).to.include.members([1, 2]);
    expect([1, 2, 3]).to.not.have.members([1, 2]);

    // Duplicates in the subset are ignored
    expect([1, 2, 3]).to.include.members([1, 2, 2, 2]);
  });

  describe('docs example 166', () => {
    expect([{ a: 1 }, { b: 2 }, { c: 3 }])
      .to.include.deep.ordered.members([{ a: 1 }, { b: 2 }])
      .but.not.include.deep.ordered.members([{ b: 2 }, { c: 3 }]);
  });

  describe('docs example 167', () => {
    expect([1, 2]).to.not.include(3).and.not.include(4); // Recommended
    expect([1, 2]).to.not.have.members([3, 4]); // Not recommended
  });

  describe('docs example 168', () => {
    expect([1, 2]).to.have.members([1, 2, 3], 'nooo why fail??');
    expect([1, 2], 'nooo why fail??').to.have.members([1, 2, 3]);
  });

  describe('docs example 169', () => {
    expect(1).to.equal(1); // Recommended
    expect(1).to.be.oneOf([1, 2, 3]); // Not recommended
  });

  describe('docs example 170', () => {
    expect(1).to.equal(1); // Recommended
    expect(1).to.not.be.oneOf([2, 3, 4]); // Not recommended
  });

  describe('docs example 171', () => {
    expect('Today is sunny').to.contain.oneOf(['sunny', 'cloudy']);
    expect('Today is rainy').to.not.contain.oneOf(['sunny', 'cloudy']);
    expect([1, 2, 3]).to.contain.oneOf([3, 4, 5]);
    expect([1, 2, 3]).to.not.contain.oneOf([4, 5, 6]);
  });

  describe('docs example 172', () => {
    expect(1).to.be.oneOf([2, 3, 4], 'nooo why fail??');
    expect(1, 'nooo why fail??').to.be.oneOf([2, 3, 4]);
  });

  describe('docs example 173', () => {
    var dots = '',
      addDot = function () {
        dots += '.';
      },
      getDots = function () {
        return dots;
      };

    // Recommended
    expect(getDots()).to.equal('');
    addDot();
    expect(getDots()).to.equal('.');

    // Not recommended
    expect(addDot).to.change(getDots);
  });

  describe('docs example 174', () => {
    var myObj = { dots: '' },
      addDot = function () {
        myObj.dots += '.';
      };

    // Recommended
    expect(myObj).to.have.property('dots', '');
    addDot();
    expect(myObj).to.have.property('dots', '.');

    // Not recommended
    expect(addDot).to.change(myObj, 'dots');
  });

  describe('docs example 175', () => {
    var dots = '',
      noop = function () {},
      getDots = function () {
        return dots;
      };

    expect(noop).to.not.change(getDots);

    var myObj = { dots: '' },
      noop = function () {};

    expect(noop).to.not.change(myObj, 'dots');
  });

  describe('docs example 176', () => {
    var myObj = { dots: '' },
      addDot = function () {
        myObj.dots += '.';
      };

    expect(addDot).to.not.change(myObj, 'dots', 'nooo why fail??');

    var dots = '',
      addDot = function () {
        dots += '.';
      },
      getDots = function () {
        return dots;
      };

    expect(addDot, 'nooo why fail??').to.not.change(getDots);
  });

  describe('docs example 177', () => {
    var myObj = { val: 1 },
      addTwo = function () {
        myObj.val += 2;
      },
      subtractTwo = function () {
        myObj.val -= 2;
      };

    expect(addTwo).to.increase(myObj, 'val').by(2); // Recommended
    expect(addTwo).to.change(myObj, 'val').by(2); // Not recommended

    expect(subtractTwo).to.decrease(myObj, 'val').by(2); // Recommended
    expect(subtractTwo).to.change(myObj, 'val').by(2); // Not recommended
  });

  describe('docs example 178', () => {
    var val = 1,
      addTwo = function () {
        val += 2;
      },
      getVal = function () {
        return val;
      };

    expect(addTwo).to.increase(getVal).by(2); // Recommended
    expect(addTwo).to.increase(getVal); // Not recommended
  });

  describe('docs example 179', () => {
    var myObj = { val: 1 },
      addTwo = function () {
        myObj.val += 2;
      };

    expect(addTwo).to.increase(myObj, 'val').by(2); // Recommended
    expect(addTwo).to.increase(myObj, 'val'); // Not recommended
  });

  describe('docs example 180', () => {
    var myObj = { val: 1 },
      subtractTwo = function () {
        myObj.val -= 2;
      };

    expect(subtractTwo).to.decrease(myObj, 'val').by(2); // Recommended
    expect(subtractTwo).to.not.increase(myObj, 'val'); // Not recommended
  });

  describe('docs example 181', () => {
    var myObj = { val: 1 },
      noop = function () {};

    expect(noop).to.not.change(myObj, 'val'); // Recommended
    expect(noop).to.not.increase(myObj, 'val'); // Not recommended
  });

  describe('docs example 182', () => {
    var myObj = { val: 1 },
      noop = function () {};

    expect(noop).to.increase(myObj, 'val', 'nooo why fail??');

    var val = 1,
      noop = function () {},
      getVal = function () {
        return val;
      };

    expect(noop, 'nooo why fail??').to.increase(getVal);
  });

  describe('docs example 183', () => {
    var val = 1,
      subtractTwo = function () {
        val -= 2;
      },
      getVal = function () {
        return val;
      };

    expect(subtractTwo).to.decrease(getVal).by(2); // Recommended
    expect(subtractTwo).to.decrease(getVal); // Not recommended
  });

  describe('docs example 184', () => {
    var myObj = { val: 1 },
      subtractTwo = function () {
        myObj.val -= 2;
      };

    expect(subtractTwo).to.decrease(myObj, 'val').by(2); // Recommended
    expect(subtractTwo).to.decrease(myObj, 'val'); // Not recommended
  });

  describe('docs example 185', () => {
    var myObj = { val: 1 },
      addTwo = function () {
        myObj.val += 2;
      };

    expect(addTwo).to.increase(myObj, 'val').by(2); // Recommended
    expect(addTwo).to.not.decrease(myObj, 'val'); // Not recommended
  });

  describe('docs example 186', () => {
    var myObj = { val: 1 },
      noop = function () {};

    expect(noop).to.not.change(myObj, 'val'); // Recommended
    expect(noop).to.not.decrease(myObj, 'val'); // Not recommended
  });

  describe('docs example 187', () => {
    var myObj = { val: 1 },
      noop = function () {};

    expect(noop).to.decrease(myObj, 'val', 'nooo why fail??');

    var val = 1,
      noop = function () {},
      getVal = function () {
        return val;
      };

    expect(noop, 'nooo why fail??').to.decrease(getVal);
  });

  describe('docs example 188', () => {
    var myObj = { val: 1 },
      addTwo = function () {
        myObj.val += 2;
      };

    expect(addTwo).to.increase(myObj, 'val').by(2);
  });

  describe('docs example 189', () => {
    var myObj = { val: 1 },
      subtractTwo = function () {
        myObj.val -= 2;
      };

    expect(subtractTwo).to.decrease(myObj, 'val').by(2);
  });

  describe('docs example 190', () => {
    var myObj = { val: 1 },
      addTwo = function () {
        myObj.val += 2;
      },
      subtractTwo = function () {
        myObj.val -= 2;
      };

    expect(addTwo).to.increase(myObj, 'val').by(2); // Recommended
    expect(addTwo).to.change(myObj, 'val').by(2); // Not recommended

    expect(subtractTwo).to.decrease(myObj, 'val').by(2); // Recommended
    expect(subtractTwo).to.change(myObj, 'val').by(2); // Not recommended
  });

  describe('docs example 191', () => {
    var myObj = { val: 1 },
      addTwo = function () {
        myObj.val += 2;
      };

    // Recommended
    expect(addTwo).to.increase(myObj, 'val').by(2);

    // Not recommended
    expect(addTwo).to.increase(myObj, 'val').but.not.by(3);
  });

  describe('docs example 192', () => {
    var myObj = { val: 1 },
      addTwo = function () {
        myObj.val += 2;
      };

    expect(addTwo).to.increase(myObj, 'val').by(3, 'nooo why fail??');
    expect(addTwo, 'nooo why fail??').to.increase(myObj, 'val').by(3);
  });

  describe('docs example 193', () => {
    expect({ a: 1 }).to.be.extensible;
  });

  describe('docs example 194', () => {
    var nonExtensibleObject = Object.preventExtensions({}),
      sealedObject = Object.seal({}),
      frozenObject = Object.freeze({});

    expect(nonExtensibleObject).to.not.be.extensible;
    expect(sealedObject).to.not.be.extensible;
    expect(frozenObject).to.not.be.extensible;
    expect(1).to.not.be.extensible;
  });

  describe('docs example 195', () => {
    expect(1, 'nooo why fail??').to.be.extensible;
  });

  describe('docs example 196', () => {
    var sealedObject = Object.seal({});
    var frozenObject = Object.freeze({});

    expect(sealedObject).to.be.sealed;
    expect(frozenObject).to.be.sealed;
    expect(1).to.be.sealed;
  });

  describe('docs example 197', () => {
    expect({ a: 1 }).to.not.be.sealed;
  });

  describe('docs example 198', () => {
    expect({ a: 1 }, 'nooo why fail??').to.be.sealed;
  });

  describe('docs example 199', () => {
    var frozenObject = Object.freeze({});

    expect(frozenObject).to.be.frozen;
    expect(1).to.be.frozen;
  });

  describe('docs example 200', () => {
    expect({ a: 1 }).to.not.be.frozen;
  });

  describe('docs example 201', () => {
    expect({ a: 1 }, 'nooo why fail??').to.be.frozen;
  });

  describe('docs example 202', () => {
    expect(1).to.be.finite;
  });

  describe('docs example 203', () => {
    expect('foo').to.be.a('string'); // Recommended
    expect('foo').to.not.be.finite; // Not recommended
  });

  describe('docs example 204', () => {
    expect(NaN).to.be.NaN; // Recommended
    expect(NaN).to.not.be.finite; // Not recommended
  });

  describe('docs example 205', () => {
    expect(Infinity).to.equal(Infinity); // Recommended
    expect(Infinity).to.not.be.finite; // Not recommended
  });

  describe('docs example 206', () => {
    expect(-Infinity).to.equal(-Infinity); // Recommended
    expect(-Infinity).to.not.be.finite; // Not recommended
  });

  describe('docs example 207', () => {
    expect('foo', 'nooo why fail??').to.be.finite;
  });

  describe('docs example 208', () => {
    expect.fail();
    expect.fail('custom error message');
    expect.fail(1, 2);
    expect.fail(1, 2, 'custom error message');
    expect.fail(1, 2, 'custom error message', '>');
    expect.fail(1, 2, undefined, '>');
  });

  // describe('docs example 209', () => {
  //   should.fail();
  //   should.fail("custom error message");
  //   should.fail(1, 2);
  //   should.fail(1, 2, "custom error message");
  //   should.fail(1, 2, "custom error message", ">");
  //   should.fail(1, 2, undefined, ">");

  // });
}

Track transmitted data per URL

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

Track transmitted data per URL

By default, k6 collects automatically two built-in metrics related to the transmitted data during the test execution:

data_received: the amount of received data.
data_sent: the amount of data sent.

However, the reported values of these metrics don’t tag the particular request or URL. Therefore, you cannot know the amount of data transmitted for a specific request or URL.

This example shows how to track data sent and received for an individual URL.

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

// Two custom metrics to track data sent and received. We will tag data points added with the corresponding URL
// so we can filter these metrics down to see the data for individual URLs and set threshold across all or per-URL as well.
export const epDataSent = new Counter('endpoint_data_sent');
export const epDataRecv = new Counter('endpoint_data_recv');

export const options = {
  duration: '10s',
  vus: 10,
  thresholds: {
    // We can setup thresholds on these custom metrics, "count" means bytes in this case.
    'endpoint_data_sent': ['count < 2048'],

    // The above threshold would look at all data points added to the custom metric.
    // If we want to only consider data points for a particular URL/endpoint we can filter by URL.
    'endpoint_data_sent{url:https://test.k6.io/contacts.php}': ['count < 1024'],
    'endpoint_data_recv{url:https://test.k6.io/}': ['count < 2048'], // "count" means bytes in this case
  },
};

function sizeOfHeaders(hdrs) {
  return Object.keys(hdrs).reduce((sum, key) => sum + key.length + hdrs[key].length, 0);
}

function trackDataMetricsPerURL(res) {
  // Add data points for sent and received data
  epDataSent.add(sizeOfHeaders(res.request.headers) + res.request.body.length, {
    url: res.url,
  });
  epDataRecv.add(sizeOfHeaders(res.headers) + res.body.length, {
    url: res.url,
  });
}

export default function () {
  let res;

  res = http.get('https://test.k6.io/');
  trackDataMetricsPerURL(res);

  res = http.get('https://test.k6.io/contacts.php');
  trackDataMetricsPerURL(res);

  sleep(1);
}

URLs with query parameters

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

URLs with query parameters

How to use URL and URLSearchParams imported from jslib.k6.io to construct URLs with/without query parameters.

URL

import { URL } from 'https://jslib.k6.io/url/1.0.0/index.js';
import http from 'k6/http';

export default function () {
  const url = new URL('https://k6.io');

  url.searchParams.append('utm_medium', 'organic');
  url.searchParams.append('utm_source', 'test');
  url.searchParams.append('multiple', ['foo', 'bar']);

  const res = http.get(url.toString());
  // https://k6.io?utm_medium=organic&utm_source=test&multiple=foo%2Cbar
}

Name	Type	Description
URLSearchParams(init)	Constructor	`init` Optional: One of [USVString, sequence of pairs or record ]
toString()	Method	Returns a USVString containing the whole URL
hash	Property	A USVString containing a ‘#’ followed by the fragment identifier of the URL.
host	Property	A USVString containing the host, that is the `hostname`, and then, if the port of the URL is nonempty, a ‘:’, followed by the `port` of the URL.
hostname	Property	A USVString containing the domain name of the URL.
href	Property	Returns a USVString containing the whole URL.
origin	Property	Returns a USVString containing the origin of the URL, that is its scheme, its domain and its port.
password	Property	A USVString containing the password specified before the domain name.
pathname	Property	Is a USVString containing an initial ‘/’ followed by the path of the URL, not including the query string or fragment.
port	Property	A USVString containing the port number of the URL.
protocol	Property	A USVString containing the protocol scheme of the URL, including the final ‘:’.
search	Property	A USVString indicating the URL’s parameter string; if any parameters are provided, this string includes all of them, beginning with the leading ? character.
searchParams	Property	A URLSearchParams object which can be used to access the individual query parameters found in search.
username	Property	A USVString containing the username specified before the domain name.

URLSearchParams

import { URLSearchParams } from 'https://jslib.k6.io/url/1.0.0/index.js';
import http from 'k6/http';

export default function () {
  const searchParams = new URLSearchParams([
    ['utm_medium', 'organic'],
    ['utm_source', 'test'],
    ['multiple', 'foo'],
    ['multiple', 'bar'],
  ]);

  const res = http.get(`${'https://k6.io'}?${searchParams.toString()}`);
  // https://k6.io?utm_medium=organic&utm_source=test&multiple=foo&multiple=bar
}

Name	Type	Description
URLSearchParams(init)	Constructor	`init` Optional: One of [USVString, sequence of pairs or record ]
toString()	Method	Returns a query string (questionmark is omitted).
append()	Method	Appends a specified key/value pair as a new search parameter.
delete()	Method	Deletes the given search parameter, and its associated value, from the list of all search parameters.
entries()	Method	Returns an iterator allowing iteration through all key/value pairs contained in this object.
forEach()	Method	Allows iteration through all values contained in this object via a callback function. `callback(value, key)`.
get()	Method	Returns the first value associated with the given search parameter.
getAll()	Method	Returns all the values associated with a given search parameter.
has()	Method	Returns a Boolean that indicates whether a parameter with the specified name exists.
keys()	Method	Returns an iterator allowing iteration through all keys of the key/value pairs contained in this object.
values()	Method	Returns an iterator allowing iteration through all values of the key/value pairs contained in this object.
set()	Method	Sets the value associated with a given search parameter to the given value. If there were several matching values, this method deletes the others. If the search parameter doesn’t exist, this method creates it.
sort()	Method	Sorts all key/value pairs, if any, by their keys.

Instant load increase

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

Instant load increase

One of the common usages of performance testing tools it’s the so-called stepped arrival rate.

In k6, you can do that by using the options object, and configuring the number of iterations or VUs in different scenarios.

Here’s an example on how to instantly increase the number of iterations and hold them for a period of time.

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

export const options = {
  scenarios: {
    contacts: {
      executor: 'ramping-arrival-rate',
      preAllocatedVUs: 50,
      timeUnit: '1s',
      startRate: 50,
      stages: [
        { target: 200, duration: '30s' }, // linearly go from 50 iters/s to 200 iters/s for 30s
        { target: 500, duration: '0' }, // instantly jump to 500 iters/s
        { target: 500, duration: '10m' }, // continue with 500 iters/s for 10 minutes
      ],
    },
  },
};

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

Here’s an example on how to instantly increase the number of VUs and hold them for a period of time.

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

export const options = {
  scenarios: {
    contacts: {
      executor: 'ramping-vus',
      startVUs: 3,
      stages: [
        { target: 20, duration: '30s' }, // linearly go from 3 VUs to 20 VUs for 30s
        { target: 100, duration: '0' }, // instantly jump to 100 VUs
        { target: 100, duration: '10m' }, // continue with 100 VUs for 10 minutes
      ],
    },
  },
};

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

Get timings for an HTTP metric

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

Get timings for an HTTP metric

To access the timing information from an individual HTTP request, the Response.timings object provides the time spent on the various phases in ms. One use case of this is to use the timings in a Custom metric to make a trend for a specific endpoint.

The timings are as follows:

blocked: equals to http_req_blocked.
connecting: equals to http_req_connecting.
tls_handshaking: equals to http_req_tls_handshaking.
sending: equals to http_req_sending.
waiting: equals to http_req_waiting.
receiving: equals to http_req_receiving.
duration: equals to http_req_duration.

This script gets the request duration timing for a specific GET request and logs it to the console.

import http from 'k6/http';

export default function () {
  const res = http.get('https://quickpizza.grafana.com/');
  console.log('Response time was ' + String(res.timings.duration) + ' ms');
}

The expected (partial) output looks like this:

$ k6 run script.js

  INFO[0001] Response time was 337.962473 ms               source=console

Distribute workloads across VUs

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

Distribute workloads across VUs

k6 can schedule different load patterns for different VU functions. A test with multiple workloads might better simulate traffic in the real world, where user behavior is rarely uniform. For example, most traffic to an e-commerce site might come from users who only search for items and read reviews. A small percentage of users might actively shop, performing actions that involve writes to the database and calls to different APIs.

The following sections provide examples of how to structure k6 scripts to split logic across VUs. To inspect the results for a certain behavior, you can create a custom metric or use Tags to filter by scenario, code block, or individual request.

Note
These techniques can create very complex configurations. However, more complexity creates more ambiguity in result interpretation

Split logic across scenarios

Note
In this context, workload refers to the traffic pattern simulated by a scenario.

One way to distribute traffic is to use scenarios to schedule different workloads for different functions.

Define multiple scenarios in your options.
Use the scenario exec property to execute different VU functions with a workload.

For example, imagine a social media site that typically receives 100 concurrent users. Of those, 80 might visit their contacts page, and 20 might view the news. To configure such a distribution, make two scenarios with different throughput or VUs:

import http from 'k6/http';

export const options = {
  //scenario to view contacts
  scenarios: {
    contacts: {
      executor: 'shared-iterations',
      exec: 'contacts',
      vus: 80,
      iterations: 100,
    },
    //scenario to view news
    news: {
      executor: 'shared-iterations',
      exec: 'news',
      vus: 20,
      iterations: 100,
    },
  },
};

//use the exec property to run different scenarios for different functions

export function contacts() {
  http.get('https://test.k6.io/contacts.php');
}

export function news() {
  http.get('https://test.k6.io/news.php');
}

To run only the contacts workload while developing it, select that scenario:

k6 run --scenario contacts script.js

This keeps the contacts scenario’s 80 VUs and 100 total iterations. Without --scenario, both workloads run.

To view granular results for a specific scenario, you can filter by the built-in scenario tag.

Distribute logic by VU ID

In some cases, writing a scenario for each behavior might be inconvenient or impractical. As an alternative, you can distribute logic across a range of VUs with the execution context variables from the k6/execution module. With the exec object, you can scope logic to a specific instance, scenario, or across all VUs.

For example, this statement assigns behavior to the first 25 VUs in a test.

if (exec.vu.idInTest <= 25) {
   //do something;
  }

For more flexibility, you can use modulo expressions to distribute VUs according to percentages. For example, the following script distributes logic according to different user profiles:

40 percent of users check the news.
60 percent play a coinflip game.
- Half bet heads, and half bet tails.

import http from 'k6/http';
import exec from 'k6/execution';

export const options = {
  scenarios: {
    quickRamp: {
      executor: 'ramping-arrival-rate',
      startRate: 0,
      timeUnit: '1s',
      preAllocatedVUs: 100,
      stages: [
        { target: 10, duration: '10s' },
        { target: 10, duration: '15s' },
        { target: 0, duration: '5s' },
      ],
    },
  },
};

export default function () {
  if (exec.vu.idInTest % 10 < 4) {
    // 0-3 range, read the news
    http.get('http://test.k6.io/news');
  } else if (exec.vu.idInTest % 10 < 7) {
    // 4-6 range, bet heads
    http.get('http://test.k6.io/flip_coin.php?bet=heads');
  } else {
    // 7-9 range, bet tails
    http.get('http://test.k6.io/flip_coin.php?bet=tails');
  }
}

To view results for a specific request or group, you can define tags.

Randomize behavior

To add a degree of random behavior, consider one of the randomizing functions from the k6 utils.

For example, this script randomly assigns one behavior to happen one-third of the time, and another to happen all other times.

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

export default function () {
  if (randomIntBetween(1, 3) % 3 > 1) {
    console.log('1 in 3 times');
  } else {
    console.log('2 in 3 times');
  }
}

For a more sophisticated example of randomizing, read this forum post.

Error handler

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

Error handler

When encountering errors from an application’s backend, gathering additional error information, such as error messages, tracing data, or request and response bodies, is often necessary. The initial suggestion is to leverage your observability solution to find these errors. However, capturing error details directly in k6 can also be useful for troubleshooting.

In k6, there are two common approaches to store additional error information:

Console logs and output k6 logs to Loki, a file, or use Grafana Cloud k6.
Using Tags in a custom counter metric to track error data.

When deciding what error data to store, consider whether it’s a general or specific error, and be aware that high-load tests may generate a substantial volume of error data.

Below is an example using an ErrorHandler class to log error information. It accepts a callback that instructs how to log errors. The example provides instructions for both previously mentioned options: console logs and custom metrics.

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

// General error handler to log error details.
class ErrorHandler {
  // Instruct the error handler how to log errors
  constructor(logErrorDetails) {
    this.logErrorDetails = logErrorDetails;
  }

  // Logs response error details if isError is true.
  logError(isError, res, tags = {}) {
    if (!isError) return;

    // the Traceparent header is a W3C Trace Context
    const traceparentHeader = res.request.headers['Traceparent'];

    // Add any other useful information
    const errorData = Object.assign(
      {
        url: res.url,
        status: res.status,
        error_code: res.error_code,
        traceparent: traceparentHeader && traceparentHeader.toString(),
      },
      tags
    );
    this.logErrorDetails(errorData);
  }
}

// Set up the error handler to log errors to the console
const errorHandler = new ErrorHandler((error) => {
  console.error(error);
});

/* Alternatively, you may log errors using a custom metric or any other option.
const errors = new CounterMetric('errors');
const errorHandler = new ErrorHandler((error) => {errors.add(1, error);});
*/

// Basic example to demonstrate the error handler
export default function () {
  let res, checkStatus;

  res = http.get('https://httpbin.org/status/200');
  checkStatus = check(res, { 'status is 200': (res) => res.status === 200 });
  errorHandler.logError(!checkStatus, res);

  res = http.get('https://httpbin.org/status/300');
  checkStatus = check(res, { 'status is 200': (res) => res.status === 200 });
  errorHandler.logError(!checkStatus, res);
}

Tutorials

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

Examples on Grafana Labs

Get started with k6

Get started with k6

Context: test a new endpoint

Before you start

Tutorials

Single request

Single request

HTTP Authentication

HTTP Authentication

Basic authentication

NTLM authentication

AWS Signature v4 authentication with the k6-jslib-aws

OAuth Authentication

OAuth Authentication

OAuth authentication

Azure Active Directory

Azure B2C

Okta

Correlation and Dynamic Data

Correlation and Dynamic Data

Correlation

Extracting values/tokens from a JSON response

Extracting values/tokens from form fields

Extracting .NET ViewStates, CSRF tokens and other hidden input fields

⚠️ Did you know?

Generic extraction of values/tokens

Extracting a value/token using findBetween

Data parameterization

Data parameterization

Performance implications of SharedArray

From a JSON file

From a CSV file

Retrieving unique data

Generating data using faker.js

Parse HTML

Parse HTML

HTML Forms

HTML Forms

Cookies Example

Cookies Example

Cookies

From the response headers

Log all the cookies in a response

⚠️ Note that this only works when using k6 locally

Setting a cookie in the VU cookie jar

Delete a cookie in the VU cookie jar

Clear all cookies in the VU cookie jar

Data Uploads

Data Uploads

The open() function

Multipart request (uploading a file)

Relevant k6 APIs

Advanced multipart request

API CRUD Operations

API CRUD Operations

Test steps

Core k6 APIs example

httpx and k6chaijs example

Generating UUIDs

Generating UUIDs

Generate v1 UUIDs

HTTP2

HTTP2

Making HTTP/2 requests

Use global variables in k6

Use global variables in k6

VU isolation and global variables

Option 1: use import and export

Option 2: use globalThis

WebSockets

WebSockets

SOAP

SOAP

Making SOAP requests

Transport Layer Security (TLS)

Transport Layer Security (TLS)

Generating realistic data

Generating realistic data

Bundling and transpiling

Performance implications of `SharedArray`

Option 1: use `import` and `export`

Option 2: use `globalThis`