JavaScript API on Grafana Labs

Init context

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

Init context

Before the k6 starts the test logic, code in the init context prepares the script. A few functions are available only in init context. For details about the runtime, refer to the Test lifecycle.

Function	Description
open( filePath, [mode] )	Opens a file and reads all the contents into memory.

k6

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

k6

The k6 module contains k6-specific functionality.

Function	Description
check(val, sets, [tags])	Runs one or more checks on a value and generates a pass/fail result but does not throw errors or otherwise interrupt execution upon failure.
fail([err])	Throws an error, failing and aborting the current VU script iteration immediately.
group(name, fn)	Runs code inside a group. Used to organize results in a test.
randomSeed(int)	Set seed to get a reproducible pseudo-random number using `Math.random`.
sleep(t)	Suspends VU execution for the specified duration.

k6/browser

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

browser

The browser module APIs are inspired by Playwright and other frontend testing frameworks.

You can find examples of using the browser module API in the getting started guide.

Note
To work with the browser module, make sure you are using the latest k6 version.

Asynchronous metric context

The experimental and opt-in async-metric-context feature flag changes how the browser module assigns tags and metadata across asynchronous operations:

Page event handlers, predicates passed to page.waitForEvent() and browserContext.waitForEvent(), and route handlers run with the metric context active when you register them. Promise reactions and await continuations created by a callback keep any context changes made by that callback.
Browser network requests copy the context of the browser operation that most likely initiated them. Request and response metrics keep that context for the request’s lifetime, including redirects.

Browser network attribution is best-effort because the Chrome DevTools Protocol doesn’t always identify the JavaScript operation that caused a request. k6 uses frame and loader information when available, followed by the active or most recently completed page operation, the page’s creation or opener context, and finally the live VU context. Without the feature flag, browser metrics continue to use the context active when k6 emits them.

For details about the affected network metrics and group tags, refer to Browser metrics.

Properties

The table below lists the properties you can import from the browser module ('k6/browser').

Property	Description
browser	The browser module API is the entry point for all your tests. See the example and the API below.
chromium	A Chromium browser type that can attach to an already running Chromium-based browser instead of one that k6 launches. See chromium.connectOverCDP().
devices	Returns predefined emulation settings for many end-user devices that can be used to simulate browser behavior on a mobile device. See the devices example below.

Browser Module API

The browser module is the entry point for all your tests, and it is what interacts with the actual web browser via Chrome DevTools Protocol (CDP). It manages:

BrowserContext which is where you can set a variety of attributes to control the behavior of pages;
and Page which is where your rendered site is displayed.

Method	Description
browser.close()	Closes the connection to the browser. Only available on a browser returned by chromium.connectOverCDP().
browser.closeContext()	Closes the current BrowserContext.
browser.context()	Returns the current BrowserContext.
browser.isConnected	Indicates whether the CDP connection to the browser process is active or not.
browser.newContext([options])	Creates and returns a new BrowserContext.
browser.newPage([options])	Creates a new Page in a new BrowserContext and returns the page. Pages that have been opened ought to be closed using `Page.close`. Pages left open could potentially distort the results of Web Vital metrics.
browser.version()	Returns the browser application’s version.

Example

import { browser } from 'k6/browser';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
  thresholds: {
    checks: ['rate==1.0'],
  },
};

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

  try {
    await page.goto('https://test.k6.io/');
  } finally {
    await page.close();
  }
}

Then, you can run the test with this command. Also, see the browser module options for customizing the browser module’s behavior using environment variables.

Bash

docker

windows

windows-powershell

k6 run script.js

# WARNING!
# The grafana/k6:master-with-browser image launches a Chrome browser by setting the
# 'no-sandbox' argument. Only use it with trustworthy websites.
#
# As an alternative, you can use a Docker SECCOMP profile instead, and overwrite the
# Chrome arguments to not use 'no-sandbox' such as:
# docker container run --rm -i -e K6_BROWSER_ARGS='' --security-opt seccomp=$(pwd)/chrome.json grafana/k6:master-with-browser run - <script.js
#
# You can find an example of a hardened SECCOMP profile in:
# https://raw.githubusercontent.com/jfrazelle/dotfiles/master/etc/docker/seccomp/chrome.json.
docker run --rm -i grafana/k6:master-with-browser run - <script.js

k6 run script.js

k6 run script.js

Devices example

To emulate the browser behaviour on a mobile device and approximately measure the browser performance, you can import devices from k6/browser.

import { browser, devices } from 'k6/browser';

export const options = {
  scenarios: {
    browser: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
    },
  },
  thresholds: {
    checks: ['rate==1.0'],
  },
};

export default async function () {
  const iphoneX = devices['iPhone X'];
  const context = await browser.newContext(iphoneX);
  const page = await context.newPage();

  try {
    await page.goto('https://test.k6.io/');
  } finally {
    page.close();
  }
}

Browser-level APIs

k6 Class	Description
BrowserContext	Enables independent browser sessions with separate Pages, cache, and cookies.
ElementHandle	Represents an in-page DOM element.
Frame	Access and interact with the `Page`.’s `Frame`s.
JSHandle	Represents an in-page JavaScript object.
Keyboard	Used to simulate the keyboard interactions with the associated `Page`.
Locator	The Locator API makes it easier to work with dynamically changing elements.
Mouse	Used to simulate the mouse interactions with the associated `Page`.
Page	Provides methods to interact with a single tab in a browser.
Request	Used to keep track of the request the `Page` makes.
Response	Represents the response received by the `Page`.
Touchscreen	Used to simulate touch interactions with the associated `Page`.
Worker	Represents a WebWorker.

Browser module options

You can customize the behavior of the browser module by providing browser options as environment variables.

Environment Variable	Description
K6_BROWSER_ARGS	Extra command line arguments to include when launching browser process. See the browser arguments for usage and common arguments.
K6_BROWSER_DEBUG	All CDP messages and internal fine grained logs will be logged if set to `true`.
K6_BROWSER_EXECUTABLE_PATH	Override search for browser executable in favor of specified absolute path.
K6_BROWSER_HEADLESS	Show browser GUI or not. `true` by default.
K6_BROWSER_IGNORE_DEFAULT_ARGS	Ignore any of the default arguments included when launching a browser process.
K6_BROWSER_TIMEOUT	Default timeout for initializing the connection to the browser instance. `'30s'` if not set.
K6_BROWSER_TRACES_METADATA	Sets additional key-value metadata that is included as attributes in every span generated from browser module traces. Example: `K6_BROWSER_TRACES_METADATA=attr1=val1,attr2=val2`. This only applies if traces generation is enabled, refer to Traces output for more details.

The following command passes the browser options as environment variables to launch a headful browser with custom arguments.

Bash

docker

windows

windows-powershell

K6_BROWSER_HEADLESS=false K6_BROWSER_ARGS='show-property-changed-rects' k6 run script.js

# WARNING!
# The grafana/k6:master-with-browser image launches a Chrome browser by setting the
# 'no-sandbox' argument. Only use it with trustworthy websites.
#
# As an alternative, you can use a Docker SECCOMP profile instead, and overwrite the
# Chrome arguments to not use 'no-sandbox' such as:
# docker container run --rm -i -e K6_BROWSER_ARGS='' --security-opt seccomp=$(pwd)/chrome.json grafana/k6:master-with-browser run - <script.js
#
# You can find an example of a hardened SECCOMP profile in:
# https://raw.githubusercontent.com/jfrazelle/dotfiles/master/etc/docker/seccomp/chrome.json.
docker run --rm -i -e K6_BROWSER_HEADLESS=false -e K6_BROWSER_ARGS='show-property-changed-rects' grafana/k6:master-with-browser run - <script.js

set "K6_BROWSER_HEADLESS=false" && set "K6_BROWSER_ARGS='show-property-changed-rects' " && k6 run script.js

$env:K6_BROWSER_HEADLESS="false" ; $env:K6_BROWSER_ARGS='show-property-changed-rects' ; k6 run script.js

Browser arguments

The following table highlights commonly useful arguments you can pass via the K6_BROWSER_ARGS environment variable. Most tests run without extra arguments, because the browser module already uses sensible defaults. Set these extra arguments only when you need to debug or adapt to your environment. For a complete list, refer to Chromium command line switches.

Note
Arguments should not start with -- when passing them to K6_BROWSER_ARGS.

Argument	Type	Description
disable-web-security	boolean	Disables the same-origin policy. Useful when testing a site whose CORS configuration blocks the browser from interacting with cross-origin iframes or assets.
ignore-certificate-errors	boolean	Ignores TLS certificate errors. Useful when testing against hosts with self-signed or otherwise invalid certificates.
no-sandbox	boolean	Disables the Chromium sandbox. Needed when running as root inside Docker, CI, or Kubernetes. Only use with trustworthy targets.
proxy-server	string	Routes browser traffic through an HTTP or SOCKS proxy. Pass the proxy address (`host:port`) as the value. Useful for corporate proxies or inspecting traffic with tools like mitmproxy.

For example, pass the following arguments to the K6_BROWSER_ARGS environment variable to ignore TLS certificate errors and route browser traffic through a proxy when running a browser test:

Bash

docker

windows

windows-powershell

K6_BROWSER_ARGS='ignore-certificate-errors,proxy-server=127.0.0.1:8080' k6 run script.js

docker run --rm -i -e K6_BROWSER_ARGS='ignore-certificate-errors,proxy-server=127.0.0.1:8080' grafana/k6:master-with-browser run - <script.js

set "K6_BROWSER_ARGS='ignore-certificate-errors,proxy-server=127.0.0.1:8080'" && k6 run script.js

$env:K6_BROWSER_ARGS='ignore-certificate-errors,proxy-server=127.0.0.1:8080' ; k6 run script.js

k6/crypto

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

k6/crypto

Note
A module with a better and standard API exists.

The crypto module partially implements the WebCrypto API, supporting more features than k6/crypto.

The k6/crypto module provides common hashing functionality available in the GoLang crypto package.

Function	Description
createHash(algorithm)	Create a Hasher object, allowing the user to add data to hash multiple times, and extract hash digests along the way.
createHMAC(algorithm, secret)	Create an HMAC hashing object, allowing the user to add data to hash multiple times, and extract hash digests along the way.
hmac(algorithm, secret, data, outputEncoding)	Use HMAC to sign an input string.
md4(input, outputEncoding)	Use MD4 to hash an input string.
md5(input, outputEncoding)	Use MD5 to hash an input string.
randomBytes(int)	Return an array with a number of cryptographically random bytes.
ripemd160(input, outputEncoding)	Use RIPEMD-160 to hash an input string.
sha1(input, outputEncoding)	Use SHA-1 to hash an input string.
sha256(input, outputEncoding)	Use SHA-256 to hash an input string.
sha384(input, outputEncoding)	Use SHA-384 to hash an input string.
sha512(input, outputEncoding)	Use SHA-512 to hash an input string.
sha512_224(input, outputEncoding)	Use SHA-512/224 to hash an input string.
sha512_256(input, outputEncoding)	Use SHA-512/256 to hash an input string.

Class	Description
Hasher	Object returned by crypto.createHash(). It allows adding more data to be hashed and to extract digests along the way.

k6/data

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

k6/data

The k6/data module provides helpers to work with data.

Class/Method	Description
SharedArray	read-only array like structure that shares memory between VUs

k6/encoding

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

k6/encoding

The k6/encoding module provides base64 encoding/decoding as defined by RFC4648.

Function	Description
b64decode(input, [encoding], [format])	Base64 decode a string.
b64encode(input, [encoding])	Base64 encode a string.

k6/execution

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

k6/execution

The k6/execution module provides the capability to get information about the current test execution state inside the test script. You can read in your script the execution state during the test execution and change your script logic based on the current state.

k6/execution provides the test execution information with the following properties:

import exec from 'k6/execution';

export const options = {
  scenarios: {
    myscenario: {
      // this will be the returned name
      executor: 'shared-iterations',
      maxDuration: '30m',
    },
  },
};

export default function () {
  console.log(exec.scenario.name); // myscenario
}

ℹ️ Identifiers

All unique identifiers are sequentially generated starting from a base of zero (iterations) or one (VU IDs). In distributed/cloud test runs, the test-wide iteration numbers and VU identifiers are still going to be unique across instances, though there might be gaps in the sequences when, for example, some instances execute faster iterations than others or allocate more VUs mid-test.

instance

The instance object provides information associated with the load generator instance. You can think of it as the current running k6 process, which will likely be a single process if you are running k6 on your local machine. When running a cloud/distributed test with multiple load generator instances, the values of the following properties can differ across instances.

Property	Type	Description
iterationsInterrupted	integer	The number of prematurely interrupted iterations in the current instance.
iterationsCompleted	integer	The number of completed iterations in the current instance.
vusActive	integer	The number of active VUs.
vusInitialized	integer	The number of currently initialized VUs.
currentTestRunDuration	float	The time passed from the start of the current test run in milliseconds.

scenario

Meta information and execution details about the current running scenario.

Property	Type	Description
name	string	The assigned name of the running scenario.
executor	string	The name of the running Executor type.
startTime	integer	The Unix timestamp in milliseconds when the scenario started.
progress	float	Percentage in a 0 to 1 interval of the scenario progress.
iterationInInstance	integer	The unique and zero-based sequential number of the current iteration in the scenario, across the current instance.
iterationInTest	integer	The unique and zero-based sequential number of the current iteration in the scenario. It is unique in all k6 execution modes - in local, cloud and distributed/segmented test runs. However, while every instance will get non-overlapping index values in cloud/distributed tests, they might iterate over them at different speeds, so the values won’t be sequential across them.

test

Control the test execution.

Property	Type	Description
abort([String])	function	It aborts the test run with the exit code `108`, and an optional string parameter can provide an error message. Aborting the test will not prevent the `teardown()` execution.
fail([String])	function	It fails the test run with the exit code `110`, and an optional string parameter can provide an error message. Failing the test will not interrupt test execution, allowing iterations to finish normally.
options	Object	It returns an object with all the test options as properties. The options’ values are consolidated following the order of precedence and derived if shortcuts have been used. It returns `null` for properties where the relative option hasn’t been defined.

vu

Meta information and execution details about the current vu.

Property	Type	Description
iterationInInstance	integer	The identifier of the iteration in the current instance for this VU. This is only unique for current VU and this instance (if multiple instances). This keeps being aggregated if a given VU is reused between multiple scenarios.
iterationInScenario	integer	The identifier of the iteration in the current scenario for this VU. This is only unique for current VU and scenario it is currently executing.
idInInstance	integer	The identifier of the VU across the instance. Not unique across multiple instances.
idInTest	integer	The globally unique (across the whole test run) identifier of the VU.
metrics.tags	object	The map that gives control over VU’s Tags. The Tags will be included in every metric emitted by the VU and the Tags’ state is maintained across different iterations of the same Scenario while the VU exists. Check how to use it in the example below.
metrics.metadata	object	The map that gives control over VU’s Metadata. The Metadata will be included in every metric emitted by the VU and the Metadata’s state is maintained across different iterations of the same Scenario while the VU exists. Check how to use it in the example below.

Examples and use cases

Getting unique data once

This is a common use case for data parameterization, you can read the examples using scenario.iterationInTest and vu.idInTest.

Timing operations

The startTime property from the scenario object can be used to time operations.

import exec from 'k6/execution';

export default function () {
  // do some long operations
  // ...
  console.log(`step1: scenario ran for ${new Date() - new Date(exec.scenario.startTime)}ms`);

  // some more long operations
  //...
  console.log(`step2: scenario ran for ${new Date() - new Date(exec.scenario.startTime)}ms`);
}

Script naming

The name property can be used for executing the logic based on which script is currently running.

Tip: If you need to run multiple scenarios in your script you can use exec option achieve a similar goal

import exec from 'k6/execution';

export const options = {
  scenarios: {
    'the-first': {
      // ...
    },
    'the-second': {
      // ...
    },
  },
};

export default function () {
  if (exec.scenario.name === 'the-first') {
    // do some logic during this scenario
  } else {
    // do some other logic in the others
  }
}

Test Abort

Aborting is possible during initialization:

import exec from 'k6/execution';
exec.test.abort();

As well as inside the default function:

import exec from 'k6/execution';

export default function () {
  // Note that you can abort with a specific message too
  exec.test.abort('this is the reason');
}

export function teardown() {
  console.log('teardown will still be called after test.abort()');
}

Test Fail

The execution.test.fail function enables controlled test failure reporting without interrupting the test execution. When called, this method marks the entire test run as failed while allowing all iterations to complete normally. The test will exit with code 110, making failures detectable by external systems. This provides graceful error handling for scenarios akin to functional testing.

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

export const options = {
  iterations: 10,
};

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

  if (exec.vu.iterationInInstance === 3) {
    exec.test.fail(`iteration ${exec.vu.iterationInInstance}: marked the test as failed`);
  }

  console.log(`iteration ${exec.vu.iterationInInstance} executed`);
}

Get test options

Get the consolidated and derived options’ values

import exec from 'k6/execution';

export const options = {
  stages: [
    { duration: '5s', target: 100 },
    { duration: '5s', target: 50 },
  ],
};

export default function () {
  console.log(exec.test.options.paused); // null
  console.log(exec.test.options.scenarios.default.stages[0].target); // 100
}

Metadata

The vu.metrics.metadata property can be used for getting or setting VU’s metadata. It is similar to tags, but can be used for high cardinality data. It also can not be used in thresholds and will likely be handled differently by each output.

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

export default function () {
  exec.vu.metrics.metadata['trace_id'] = 'somecoolide';

  // the metrics these HTTP requests emit will get the metadata `trace_id`:
  http.batch(['https://test.k6.io', 'https://quickpizza.grafana.com']);

  delete exec.vu.metrics.metadata['trace_id']; // this will unset it
  // which will make the metrics these requests to not have the metadata `trace_id` set on them.
  http.batch(['https://test.k6.io', 'https://quickpizza.grafana.com']);
}

k6/experimental

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

k6/experimental

Caution
This is an experimental module.

While we intend to keep experimental modules as stable as possible, we may need to introduce breaking changes. This could happen at future k6 releases until the module becomes fully stable and graduates as a k6 core module. For more information, refer to the versioning and stability guarantees document.

Experimental modules maintain a high level of stability and follow regular maintenance and security measures. Feel free to open an issue if you have any feedback or suggestions.

Modules	Description
csv	Provides support for efficient and convenient parsing of CSV files.
fs	Provides a memory-efficient way to handle file interactions within your test scripts.
streams	Provides an implementation of the Streams API specification, offering support for defining and consuming readable streams.

k6/html

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

k6/html

The k6/html module contains functionality for HTML parsing.

Function	Description
parseHTML(src)	Parse an HTML string and populate a Selection object.

Class	Description
Element	An HTML DOM element as returned by the Selection API.
Selection	A jQuery-like API for accessing HTML DOM elements.

k6/http

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

k6/http

The k6/http module contains functionality for performing HTTP transactions.

Function	Description
batch( requests )	Issue multiple HTTP requests in parallel (like e.g. browsers tend to do).
cookieJar()	Get active HTTP Cookie jar.
del( url, [body], [params] )	Issue an HTTP DELETE request.
file( data, [filename], [contentType] )	Create a file object that is used for building multi-part requests.
get( url, [params] )	Issue an HTTP GET request.
head( url, [params] )	Issue an HTTP HEAD request.
options( url, [body], [params] )	Issue an HTTP OPTIONS request.
patch( url, [body], [params] )	Issue an HTTP PATCH request.
post( url, [body], [params] )	Issue an HTTP POST request.
put( url, [body], [params] )	Issue an HTTP PUT request.
request( method, url, [body], [params] )	Issue any type of HTTP request.
asyncRequest( method, url, [body], [params] )	Issue any type of HTTP request asynchronously.
setResponseCallback(expectedStatuses)	Sets a response callback to mark responses as expected.
url`url`	Creates a URL with a name tag. Read more on URL Grouping.
expectedStatuses( statusCodes )	Create a callback for setResponseCallback that checks status codes.

Class	Description
CookieJar	Used for storing cookies, set by the server and/or added by the client.
FileData	Used for wrapping data representing a file when doing multipart requests (file uploads).
Params	Used for setting various HTTP request-specific parameters such as headers, cookies, etc.
Response	Returned by the http.* methods that generate HTTP requests.

k6/metrics

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

k6/metrics

The k6/metrics module provides functionality to create custom metrics of various types.

Metric type	Description
Counter	A metric that cumulatively sums added values.
Gauge	A metric that stores the min, max and last values added to it.
Rate	A metric that tracks the percentage of added values that are non-zero.
Trend	A metric that calculates statistics on the added values (min, max, average, and percentiles).

k6/net/grpc

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

k6/net/grpc

The k6/net/grpc module provides a gRPC client for Remote Procedure Calls (RPC) over HTTP/2.

Class/Method	Description
Client	gRPC client used for making RPC calls to a gRPC Server.
Client.load(importPaths, …protoFiles)	Loads and parses the given protocol buffer definitions to be made available for RPC requests.
Client.connect(address [,params])	Connects to a given gRPC service.
Client.invoke(url, request [,params])	Makes an unary RPC for the given service/method and returns a Response.
Client.asyncInvoke(url, request [,params])	Asynchronously makes an unary RPC for the given service/method and returns a Promise with Response.
Client.close()	Close the connection to the gRPC service.
Params	RPC Request specific options.
Response	Returned by RPC requests.
Constants	Define constants to distinguish between gRPC Response statuses.
Stream(client, url, [,params])	Creates a new gRPC stream.
Stream.on(event, handler)	Adds a new listener to one of the possible stream events.
Stream.write(message)	Writes a message to the stream.
Stream.end()	Signals to the server that the client has finished sending.
EventHandler	The function to call for various events on the gRPC stream.
Metadata	The metadata of a gRPC stream’s message.

gRPC metrics

k6 takes specific measurements for gRPC requests. For the complete list, refer to the Metrics reference.

Example

import grpc from 'k6/net/grpc';
import { check, sleep } from 'k6';

const client = new grpc.Client();
client.load(null, 'quickpizza.proto');

export default () => {
  client.connect('grpc-quickpizza.grafana.com:443', {
    // plaintext: false
  });

  const data = { ingredients: ['Cheese'], dough: 'Thick' };
  const response = client.invoke('quickpizza.GRPC/RatePizza', data);

  check(response, {
    'status is OK': (r) => r && r.status === grpc.StatusOK,
  });

  console.log(JSON.stringify(response.message));

  client.close();
  sleep(1);
};

k6/secrets

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

k6/secrets

The k6/secrets module gives access to secrets provided by configured secret sources.

Property	Description
get([String])	asynchrounsly get a secret from the default secret source
source([String])	returns a source for the provided name that can than be used to get a secret from a concrete source

get

get returns the value of the secret for the provided name from the default secret source. If there is no default secret source, there is no secret with that name or some other error is returned an exception will thrown.

source

source returns a secret source for the name provided. The name is defined when running k6.

The returned object has one method get with the same functionality as the global get

Example

A simple example where we get a secret by its name from the default source (if defined).

import secrets from 'k6/secrets';

export default async () => {
  const my_secret = await secrets.get('my_secret'); // get from 1 secret source if only 1, exception if more than 1 secret source or if no secret sources
  console.log(my_secret);
};

We can also get a secret source by its name then get a secret specifically from it.

import secrets from 'k6/secrets';

export default async () => {
  const my_secret = await secrets.source('identifier').get('my_secret'); // get secret from a source with the provided identifier
  console.log(my_secret);
};

In both of those cases the end logs will have ***SECRET_REDACTED*** in place of any secret that has been outputed.

A full example with multiple secret sources and names

import secrets from 'k6/secrets';

export default async () => {
  const my_secret = await secrets.get('cool'); // get secret from a source with the provided identifier
  console.log(my_secret == 'cool secret');
  const anothersource = await secrets.source('another');
  console.log((await anothersource.get('cool')) == 'cool secret');
  console.log((await anothersource.get('cool')) == 'not cool secret');
};

And if we ran we will see that when we get from the default secret source we get one secret and we get a different one from the not default one. This also shows that the internal parts of the scripts can use the actual value of the script even if it is redacted in the logs.

$ k6 run --secret-source=mock=default,cool="cool secret" --secret-source=mock=name=another,cool="not cool secret" multi-source.test.js
...
INFO[0000] true                                          source=console
INFO[0000] false                                         source=console
INFO[0000] true                                          source=console

k6/timers

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

k6/timers

The k6/timers module implements timers to work with k6’s event loop. They mimic the functionality found in browsers and other JavaScript runtimes.

Function	Description
setTimeout	Sets a function to be run after a given timeout.
clearTimeout	Clears a previously set timeout with `setTimeout`.
setInterval	Sets a function to be run on a given interval.
clearInterval	Clears a previously set interval with `setInterval`.

Note
The timer methods are available globally, so you can use them in your script without including an import statement.

Note
When you enable the experimental async-metric-context feature flag, setTimeout() and setInterval() capture the tags and metadata active when you register their callbacks. Each callback runs with a copy of that context. Repeating intervals reuse the original registration context for every invocation, so changes made by one invocation don’t leak into the next one or into the calling code.

Promise reactions and await continuations created inside a timer callback keep any context changes made by that callback.

Example

export default function () {
  const intervalId = setInterval(() => {
    console.log('This runs every 200ms');
  }, 200);

  const timeoutId = setTimeout(() => {
    console.log('This runs after 2s');

    // clear the timeout and interval to exit k6
    clearInterval(intervalId);
    clearTimeout(timeoutId);
  }, 2000);
}

k6/ws

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

k6/ws

Note
A module with a better and standard API exists.

The new k6/websockets API partially implements the WebSockets API living standard.

When possible, we recommend using the new API. It uses a global event loop for consistency with other k6 APIs and better performance.

The k6/ws module provides a WebSocket client implementing the WebSocket protocol.

Function	Description
connect( url, params, callback )	Create a WebSocket connection, and provides a Socket client to interact with the service. The method blocks the test finalization until the connection is closed.

Class/Method	Description
Params	Used for setting various WebSocket connection parameters such as headers, cookie jar, compression, etc.
Socket	WebSocket client used to interact with a WS connection.
Socket.close()	Close the WebSocket connection.
Socket.on(event, callback)	Set up an event listener on the connection for any of the following events: - open - binaryMessage - message - ping - pong - close - error.
Socket.ping()	Send a ping.
Socket.send(data)	Send string data.
Socket.sendBinary(data)	Send binary data.
Socket.setInterval(callback, interval)	Call a function repeatedly at certain intervals, while the connection is open.
Socket.setTimeout(callback, period)	Call a function with a delay, if the connection is open.

k6/x/dns

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

k6/x/dns

Note
This module is implemented as an official extension and is available natively in k6, requiring no additional installation or build steps. Refer to the extensions documentation for available extensions and details.

The k6/x/dns module enables DNS resolution testing in k6, allowing you to resolve DNS names to IP addresses using custom DNS servers or the system’s default DNS configuration. This module is useful for testing DNS server performance, validating DNS configurations, and incorporating DNS resolution into your load testing scenarios.

Key features

The dns.resolve() function resolves DNS names using a specified DNS server, allowing you to test custom DNS configurations and server performance.
The dns.lookup() function resolves DNS names using the system’s default DNS servers, providing a way to test standard DNS resolution behavior.
Support for A (IPv4) and AAAA (IPv6) record types.
Automatic metrics collection for DNS resolution performance analysis.

Use cases

Load testing DNS servers to ensure they can handle high query volumes.
Validating DNS configurations in staging and production environments.
Testing DNS failover mechanisms and redundancy.
Incorporating DNS resolution time into overall application performance testing.

API

Function/Object	Description
resolve	Resolves a DNS name to IP addresses using a specified DNS server.
lookup	Resolves a DNS name to IP addresses using the system’s default DNS servers.

Metrics

The extension automatically generates the following metrics:

dns_resolutions: Counter tracking the number of DNS resolution attempts.
dns_resolution_duration: Trend measuring DNS resolution response times.
dns_lookups: Counter tracking the number of DNS lookup attempts.
dns_lookup_duration: Trend measuring DNS lookup response times.

Examples

Basic DNS resolution with custom server

import dns from 'k6/x/dns';

export default async function () {
  // Resolve k6.io using Cloudflare's DNS server
  const ips = await dns.resolve('k6.io', 'A', '1.1.1.1:53');
  console.log('k6.io resolves to:', ips);
}

DNS lookup using system defaults

import dns from 'k6/x/dns';

export default async function () {
  // Resolve k6.io using system DNS servers
  const ips = await dns.lookup('k6.io');
  console.log('k6.io resolves to:', ips);
}

Comprehensive DNS testing

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

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

export default async function () {
  // Test both IPv4 and IPv6 resolution
  const ipv4Results = await dns.resolve('example.com', 'A', '8.8.8.8:53');
  const ipv6Results = await dns.resolve('example.com', 'AAAA', '[2606:4700:4700::1111]:53');

  // Test system DNS
  const systemResults = await dns.lookup('example.com');

  // Validate results
  expect(ipv4Results.length).toBeGreaterThan(0);
  expect(ipv6Results.length).toBeGreaterThan(0);
  expect(systemResults.length).toBeGreaterThan(0);
}

k6/x/icmp

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

k6/x/icmp

Note
This module is implemented as an official extension and is not part of k6 by default. However, k6’s automatic extension resolution makes it available seamlessly when you import it in your script. Refer to the extensions documentation for available extensions and details.

The k6/x/icmp module adds support for sending ICMP echo requests (pings) to measure network latency and availability. This allows you to measure network latency and reachability of hosts directly within your load testing and synthetic monitoring scenarios.

The main use case for this extension is integration with Grafana’s Synthetic Monitoring product to make a quick reachability check after a scripted check fails. It can also be used directly in k6 scripts, for example as a pre-check to verify network connectivity before running your main test.

Key features

Send ICMP echo requests (ping) to any host
Synchronous and asynchronous ping functions
Support for multiple ping attempts with configurable count and interval
Configurable timeouts and deadlines
Detailed ping results via callback function
Support for IPv4 and IPv6
Custom packet size and TTL settings
Automatic metrics collection
Success threshold configuration for multiple pings

Use cases

Network connectivity pre-checks before load tests
Host reachability validation in synthetic monitoring
Network latency measurement across different hosts
Testing network infrastructure reliability
Monitoring service availability at the network layer
Validating network paths and routing

API

Function/Type	Description
ping( target, [options] )	Send ICMP echo requests synchronously
pingAsync( target, [optsOrCallback], [callback] )	Send ICMP echo requests asynchronously
PingOptions	Configuration options for ping operations
PingDetail	Detailed information about ping results
IP	IP protocol version enumeration

Metrics

The extension automatically generates metrics for ICMP operations:

icmp_pings: Counter tracking the number of ping attempts
icmp_ping_duration: Trend measuring round-trip time for successful pings
icmp_ping_failed: Counter tracking failed ping attempts

Examples

Basic Usage

Here is a basic example showing how to use the ping() function:

import { ping } from "k6/x/icmp"

export default function () {
  const host = "8.8.8.8"

  console.log(`Pinging ${host}:`);

  if (ping(host)) {
    console.log(`Host ${host} is reachable`);
  } else {
    console.error(`Host ${host} is unreachable`);
  }
}

Advanced Usage

A more advanced example below demonstrates how to use the PingCallback to access detailed ping results for each request.

import { pingAsync } from "k6/x/icmp"

export default async function () {
  const host = "8.8.8.8"

  console.log(`Pinging ${host} with callback:`);

  const opts = {
    timeout: 3000,
    count: 5
  };

  const result = await pingAsync(host, opts, (err, { target, sent_at, received_at, seq, ttl, size }) => {
    if (err) {
      console.error(`${target}: ${err}`);

      return
    }

    const rtt = received_at - sent_at;

    console.log(`${size} bytes from ${target}: icmp_seq=${seq} ttl=${ttl} time=${rtt} ms`);
  });

  if (result) {
    console.log(`Host ${host} is reachable`);
  } else {
    console.error(`Host ${host} is unreachable`);
  }
}

k6/x/mqtt

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

k6/x/mqtt

Note
This module is implemented as an official extension and is not part of k6 by default. However, k6’s automatic extension resolution makes it available seamlessly when you import it in your script. Refer to the extensions documentation for available extensions and details.

The k6/x/mqtt module adds first-class support for the MQTT protocol to your load testing and performance scripts. With this extension, you can connect to MQTT brokers, publish and subscribe to topics, and interact with MQTT systems directly from your k6 tests.

The API is designed to feel familiar to users of MQTT.js, the popular JavaScript MQTT client. This means you can use event-driven programming, both synchronous and asynchronous operations, and migrate existing MQTT.js-based test logic with minimal changes.

Key features

Event-driven architecture with support for connection lifecycle events (connect, message, end, reconnect, error)
Both synchronous and asynchronous methods for all operations (subscribe, publish, unsubscribe, end)
Support for Quality of Service (QoS) levels: 0 (at most once), 1 (at least once), 2 (exactly once)
Message retention and Last Will and Testament (LWT) support
Multiple broker URL schemas: mqtt://, mqtts://, tcp://, ssl://, tls://, ws://, wss://
SSL/TLS support using standard k6 TLS configuration
Automatic metrics collection for MQTT operations
Support for binary payloads using ArrayBuffer
Credentials provider for dynamic authentication

Use cases

Load testing MQTT brokers and IoT infrastructure
Testing publish/subscribe patterns under high load
Validating message delivery and QoS guarantees
Simulating thousands of concurrent MQTT clients
Testing MQTT-based microservices and event-driven architectures
Monitoring MQTT broker performance and message throughput

API

Class/Type	Description
Client	MQTT client for connecting to brokers and managing operations
Client.connect()	Connect to an MQTT broker
Client.reconnect()	Reconnect to the broker
Client.subscribe()	Subscribe to MQTT topics
Client.subscribeAsync()	Subscribe to topics asynchronously
Client.unsubscribe()	Unsubscribe from topics
Client.unsubscribeAsync()	Unsubscribe from topics asynchronously
Client.publish()	Publish messages to MQTT topics
Client.publishAsync()	Publish messages asynchronously
Client.on()	Register event handlers
Client.end()	Disconnect from the MQTT broker
Client.endAsync()	Disconnect asynchronously
QoS	Quality of Service enumeration

Metrics

The extension automatically generates metrics for MQTT operations, allowing you to monitor performance:

mqtt_connects: Counter tracking the number of connection attempts
mqtt_connect_duration: Trend measuring connection time
mqtt_publishes: Counter tracking the number of publish operations
mqtt_subscribes: Counter tracking the number of subscribe operations
mqtt_messages_received: Counter tracking received messages
mqtt_messages_sent: Counter tracking sent messages

Event-driven architecture

Unlike HTTP-based tests that continuously loop the main function, MQTT tests use an asynchronous event loop. Each VU creates an MQTT connection and registers event handlers. The VU remains active until the connection is closed.

When you call client.connect(), the connect event handler is immediately called. Inside this handler, you set up other event handlers and perform MQTT operations. The VU blocks until client.end() is called or the connection is closed by the broker.

Examples

Hello World

Comparing HTTP-based tests to MQTT ones, you’ll find differences in both structure and inner workings. The primary difference is that instead of continuously looping the main function (export default function() { ... }) over and over, each VU now runs an asynchronous event loop.

When the MQTT connection is created, the connect handler function is immediately called, all code inside it is executed (usually code to set up other event handlers), and then blocked until the MQTT connection is closed (by the remote host or by using client.end()).

import { Client } from 'k6/x/mqtt';

export default function () {
  const client = new Client();

  client.on('connect', async () => {
    console.log('Connected to MQTT broker');
    client.subscribe('greeting');
    client.publish('greeting', 'Hello MQTT!');
  });

  client.on('message', (topic, message) => {
    const str = new TextDecoder().decode(message);
    console.info('topic:', topic, 'message:', str);
    client.end();
  });

  client.on('end', () => {
    console.log('Disconnected from MQTT broker');
  });

  client.connect(__ENV['MQTT_BROKER_ADDRESS'] || 'mqtt://broker.emqx.io:1883');
}

Async Programming

Async and event-based programming is fully supported. You can use setTimeout(), setInterval(), and other async patterns with xk6-mqtt event handlers.

import { Client } from 'k6/x/mqtt';

export default function () {
  const client = new Client();

  client.on('connect', async () => {
    console.log('Connected to MQTT broker');
    await client.subscribeAsync('probe');

    const intervalId = setInterval(() => {
      client.publish('probe', 'ping MQTT!');
    }, 1000);

    setTimeout(() => {
      clearInterval(intervalId);
      client.end();
    }, 3100);
  });

  client.on('message', (topic, message) => {
    console.info(new TextDecoder().decode(message));
  });

  client.on('end', () => {
    console.log('Disconnected from MQTT broker');
  });

  client.connect(__ENV['MQTT_BROKER_ADDRESS'] || 'mqtt://broker.emqx.io:1883');
}

k6/x/tcp

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

k6/x/tcp

Note
This module is implemented as an official extension and is not part of k6 by default. However, k6’s automatic extension resolution makes it available seamlessly when you import it in your script. Refer to the extensions documentation for available extensions and details.

The k6/x/tcp module adds first-class support for raw TCP socket communication to your performance testing scripts. With this extension, you can establish TCP connections and send and receive data directly from your k6 tests.

If you’ve used Node.js’s net.Socket, the API will feel familiar, with event-driven programming, Promise-based operations, and comprehensive lifecycle management.

Key features

Event-driven architecture with support for socket lifecycle events (connect, data, close, error, timeout)
Promise-based connect() and write() methods for use with async/await
TLS/SSL support using standard k6 TLS configuration
Binary data handling: send and receive strings and ArrayBuffer
Automatic metrics collection for all socket operations
Optional custom tags for filtering and grouping metrics

Use cases

Load testing TCP-based services and custom binary protocols
Testing raw network protocol implementations under high concurrency
Validating server behavior and connection handling under load
Performance testing services that don’t use HTTP

API

Class	Description
Socket	TCP socket for connecting to servers and managing operations
Socket.connect()	Establish a TCP connection
Socket.write()	Send data over the socket
Socket.destroy()	Close and destroy the socket
Socket.setTimeout()	Set inactivity timeout
Socket.on()	Register event handlers

Metrics

The extension automatically generates metrics for TCP socket operations:

Metric	Type	Description
`tcp_socket_connecting`	Trend	Time to establish TCP connection (ms)
`tcp_socket_resolving`	Trend	Time to resolve hostname (ms)
`tcp_socket_duration`	Trend	Total duration of socket connection (ms)
`tcp_sockets`	Counter	Number of TCP socket connections established
`tcp_reads`	Counter	Number of read operations
`tcp_writes`	Counter	Number of write operations
`tcp_errors`	Counter	Number of TCP errors
`tcp_timeouts`	Counter	Number of socket timeouts
`tcp_partial_writes`	Counter	Number of partial write failures
`data_sent`	Counter	Total bytes sent (builtin k6 metric)
`data_received`	Counter	Total bytes received (builtin k6 metric)

You can pass custom tags in the Socket constructor, connection options, or write options to attach additional metadata to each metric.

Event-driven architecture

Unlike HTTP-based tests, TCP tests use an asynchronous event loop. Each VU creates a Socket, registers event handlers, and connects to a server. The VU remains active until socket.destroy() is called or the connection is closed.

Register handlers with socket.on() before calling socket.connect(). The connect handler fires when the connection is established; the data handler fires each time data is received; the close handler fires when the connection is fully closed.

Examples

Basic usage

import { Socket } from 'k6/x/tcp';

export default async function () {
  const socket = new Socket();

  const closed = new Promise((resolve) => {
    socket.on('close', () => {
      console.log('Connection closed');
      resolve();
    });
  });

  socket.on('error', (err) => {
    console.error('Error:', err);
  });

  const host = __ENV.TCP_HOST || 'localhost';
  const port = __ENV.TCP_PORT || '8080';

  await socket.connect(port, host);
  console.log('Connected');
  socket.destroy();

  await closed;
}

TLS connection

import { Socket } from 'k6/x/tcp';

export default async function () {
  const socket = new Socket();

  const closed = new Promise((resolve) => {
    socket.on('close', resolve);
  });

  socket.on('data', (data) => {
    const response = new TextDecoder().decode(data);
    console.log('Received:', response.substring(0, 100));
    socket.destroy();
  });

  socket.on('error', (err) => {
    console.error('Error:', err);
  });

  const host = __ENV.TLS_HOST || 'example.com';

  await socket.connect({ port: 443, host, tls: true });
  await socket.write(`GET / HTTP/1.1\r\nHost: ${host}\r\nConnection: close\r\n\r\n`);

  await closed;
}

k6/x/tls

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

k6/x/tls

Note
This module is implemented as an official extension and is available natively in k6, requiring no additional installation or build steps. Refer to the extensions documentation for available extensions and details.

The k6/x/tls module provides functionality for TLS certificate validation and inspection, allowing you to fetch certificate details and validate their properties directly from your k6 tests.

Use cases

Fetch TLS certificate information from any host
Validate certificate expiration and properties
Access certificate details (for example subject, issuer, fingerprint)

API

getCertificate( hostname )

Fetches TLS certificate information from a specified host.

The tls.getCertificate function retrieves TLS certificate details from a given hostname and returns a promise that resolves to a certificate object containing various properties such as expiration date, subject, issuer, and fingerprint information.

Parameters

Parameter	Type	Description
hostname	string	The hostname to fetch the TLS certificate from. For example, “example.com” or “k6.io”.

Returns

A promise resolving to a certificate object containing the following properties:

Property	Type	Description
subject	object	The certificate subject information (pkixName object)
issuer	object	The certificate issuer information (pkixName object)
issued	number	The certificate issued timestamp in milliseconds since Unix epoch
expires	number	The certificate expiration timestamp in milliseconds since Unix epoch
fingerprint	string	The certificate fingerprint

Examples

Check if a certificate is expired

import tls from "k6/x/tls";
import { check } from "k6";

export default async function () {
  const cert = await tls.getCertificate("example.com");

  check(cert, {
    "certificate is not expired": (c) => c.expires > Date.now(),
  });

  console.log(`Certificate expires: ${new Date(cert.expires)}`);
}

k6/x/redis

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

k6/x/redis

The Redis module provides a client library that makes it possible to interact with Redis directly from a k6 script. With this module, you can:

Load test Redis
Use Redis as a data store for test-script logic.

Though the API intends to be thorough and extensive, it does not expose the whole Redis API. Instead, the intent is to expose Redis for use cases most appropriate to k6.

Class	Description
Client	Client that exposes allowed interactions with Redis.
Options	Options used to configure the behavior of the Redis Client.

Notes on usage

The Client exposes a promise-based API. Unlike most other current k6 modules and extensions, which operate in a synchronous manner, the Redis Client operates in an asynchronous manner. In practice, this means that using the Redis Client’s methods won’t block test execution, and that the test will continue to run even if the Redis Client isn’t ready to respond to the request. The async and await keywords enable asynchronous, promise-based behavior to be written in a cleaner style, avoiding the need to explicitly configure promise chains (for details, refer to the MDN documentation).

Error Codes

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

Error Codes

Error codes are unique numbers that can be used to identify and handle different application and network errors more easily. For the moment, these error codes are applicable only for errors that happen during HTTP requests, but they will be reused and extended to support other protocols in future k6 releases.

When an error occurs, its code is determined and returned as both the error_code field of the http.Response object, and also attached as the error_code tag to any metrics associated with that request. Additionally, for more details, the error metric tag and http.Response field will still contain the actual string error message.

Error codes for different errors are as distinct as possible, but for easier handling and grouping, codes in different error categories are also grouped in broad ranges. The current error code ranges are:

1000-1099 - General errors
1100-1199 - DNS errors
1200-1299 - TCP errors
1300-1399 - TLS errors
1400-1499 - HTTP 4xx errors
1500-1599 - HTTP 5xx errors
1600-1699 - HTTP/2 specific errors

The following specific error codes are currently defined:

1000: A generic error that isn’t any of the ones listed below.
1010: A non-TCP network error - this is a place holder there is no error currently known to trigger it.
1020: An invalid URL was specified.
1050: The HTTP request has timed out.
1100: A generic DNS error that isn’t any of the ones listed below.
1101: No IP for the provided host was found.
1110: Blacklisted IP was resolved or a connection to such was tried to be established.
1111: Blacklisted hostname using The Block Hostnames option.
1200: A generic TCP error that isn’t any of the ones listed below.
1201: A “broken pipe” on write - the other side has likely closed the connection.
1202: An unknown TCP error - We got an error that we don’t recognize but it is from the operating system and has errno set on it. The message in error includes the operation(write,read) and the errno, the OS, and the original message of the error.
1210: General TCP dial error.
1211: Dial timeout error - the timeout for the dial was reached.
1212: Dial connection refused - the connection was refused by the other party on dial.
1213: Dial unknown error.
1220: Reset by peer - the connection was reset by the other party, most likely a server.
1300: General TLS error
1310: Unknown authority - the certificate issuer is unknown.
1311: The certificate doesn’t match the hostname.
1400 to 1499: error codes that correspond to the HTTP 4xx status codes for client errors
1500 to 1599: error codes that correspond to the HTTP 5xx status codes for server errors
1600: A generic HTTP/2 error that isn’t any of the ones listed below.
1610: A general HTTP/2 GoAway error.
1611 to 1629: HTTP/2 GoAway errors with the value of the specific HTTP/2 error code added to 1611.
1630: A general HTTP/2 stream error.
1631 to 1649: HTTP/2 stream errors with the value of the specific HTTP/2 error code added to 1631.
1650: A general HTTP/2 connection error.
1651 to 1669: HTTP/2 connection errors with the value of the specific HTTP/2 error code added to 1651.
1701: Decompression error.

crypto

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

crypto

With this module, you can use the WebCrypto API in your k6 scripts. However, note that this API is not yet fully implemented and some algorithms and features might still be missing.

The Web Crypto API is a JavaScript API for performing cryptographic operations such as encryption, decryption, digital signature generation and verification, and key generation and management. It provides a standard interface to access cryptographic functionality, which can help ensure that cryptographic operations are performed correctly and securely.

API

The module is a top-level crypto object with the following properties and methods:

Interface/Function	Description
getRandomValues	Fills the passed `TypedArray` with cryptographically sound random values.
randomUUID	Returns a randomly generated, 36 character long v4 UUID.
subtle	The SubtleCrypto interface provides access to common cryptographic primitives, such as hashing, signing, encryption, or decryption.

Example

export default async function () {
  const plaintextText = 'Hello, World!';
  const plaintext = new TextEncoder().encode(plaintextText);

  /**
   * Generate a symmetric key using the AES-CBC algorithm.
   */
  const key = await crypto.subtle.generateKey(
    {
      name: 'AES-CBC',
      length: 256,
    },
    true,
    ['encrypt', 'decrypt']
  );

  /**
   * Encrypt the plaintext using the AES-CBC key with
   * have generated.
   */
  const iv = crypto.getRandomValues(new Uint8Array(16));
  const ciphertext = await crypto.subtle.encrypt(
    {
      name: 'AES-CBC',
      iv: iv,
    },
    key,
    plaintext
  );

  /**
   * Decrypt the ciphertext using the same key to verify
   * that the resulting plaintext is the same as the original.
   */
  const deciphered = await crypto.subtle.decrypt(
    {
      name: 'AES-CBC',
      iv: iv,
    },
    key,
    ciphertext
  );

  console.log(
    'deciphered text == original plaintext: ',
    new TextDecoder().decode(deciphered) === plaintextText
  );
}

jslib

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

jslib

jslib is a collection of JavaScript libraries maintained by the k6 team that can be used in k6 scripts.

Library	Description
aws	Library allowing to interact with Amazon AWS services
httpx	Wrapper around k6/http to simplify session handling
k6chaijs	BDD assertion style
http-instrumentation-pyroscope	Library to instrument k6/http to send baggage headers for pyroscope to read back
http-instrumentation-tempo	Library to instrument k6/http to send tracing data
testing	Advanced assertion library with Playwright-inspired API for protocol and browser testing
totp	TOTP (Time-based One-Time Password) generation and verification
utils	Small utility functions useful in every day load testing

websockets

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

websockets

Note
The k6/experimental/websockets module has been deprecated. Use k6/websockets instead.

This module implements the browser WebSocket API with additional k6-specific functionalities (cookies, tags, headers and so on).

The main difference between this module and k6/ws is that this module uses a global event loop instead of a local one. A global event loop lets a single VU have multiple concurrent connections, which improves performance.

Note
When you enable the experimental async-metric-context feature flag, handlers assigned to WebSocket event properties, such as onopen and onmessage, and handlers registered with addEventListener() capture the tags and metadata active at registration. Metrics emitted by a handler use a copy of that context, and k6 restores the interrupted context after the handler returns or throws. Promise reactions and await continuations created by the handler keep its context.

This behavior applies to k6/websockets, but not to the legacy k6/ws module.

Class/Method	Description
Params	Used for setting various WebSocket connection parameters such as headers, cookie jar, compression, etc.
WebSocket(url, protocols, params)	Constructs a new WebSocket connection.
WebSocket.close()	Close the WebSocket connection.
WebSocket.ping()	Send a ping.
WebSocket.send(data)	Send data.
WebSocket.addEventListener(event, handler)	Add an event listener on the connection for specific event.
Blob	Interface that represents a blob, which is a file-like object of immutable, raw data; they can be read as text or binary data, or converted into a ReadableStream.

A WebSocket instance also has the following properties:

Class/Property	Description
WebSocket.readyState	The current state of the connection. Could be one of the four states.
WebSocket.url	The URL of the connection as resolved by the constructor.
WebSocket.bufferedAmount	The number of bytes of data that have been queued using calls to `send()` but not yet transmitted to the network.
WebSocket.binaryType	The `binaryType` controls the type of binary data being received over the WebSocket connection. Use `"blob"` to receive it as `Blob`, or `"arraybuffer"` to receive it as `ArrayBuffer`. The default value is `"blob"`.
WebSocket.onmessage	A handler for `message` events.
WebSocket.onerror	A handler for `error` events.
WebSocket.onopen	A handler for `open` events.
WebSocket.onclose	A handler for `close` events.
WebSocket.onping	A handler for `ping` events.
WebSocket.onpong	A handler for `pong` events.

Compare readyState with the ready-state constants, such as WebSocket.OPEN.

Websocket metrics

k6 takes specific measurements for Websockets. For the complete list, refer to the Metrics reference.

Example

This example shows:

How a single VU can run multiple WebSockets connections asynchronously.
How to use the timeout and interval functions to stop the connections after some period.

import { randomString, randomIntBetween } from 'https://jslib.k6.io/k6-utils/1.1.0/index.js';
import { WebSocket } from 'k6/websockets';

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

export default function () {
  for (let i = 0; i < 4; i++) {
    startWSWorker(i);
  }
}

function startWSWorker(id) {
  // create a new websocket connection
  const ws = new WebSocket(`wss://quickpizza.grafana.com/ws`);
  ws.binaryType = 'arraybuffer';

  ws.addEventListener('open', () => {
    // change the user name
    ws.send(JSON.stringify({ event: 'SET_NAME', new_name: `VU ${__VU}:${id}` }));

    // listen for messages/errors and log them into console
    ws.addEventListener('message', (e) => {
      const msg = JSON.parse(e.data);
      if (msg.event === 'CHAT_MSG') {
        console.log(`VU ${__VU}:${id} received: ${msg.user} says: ${msg.message}`);
      } else if (msg.event === 'ERROR') {
        console.error(`VU ${__VU}:${id} received:: ${msg.message}`);
      } else {
        console.log(`VU ${__VU}:${id} received unhandled message: ${msg.message}`);
      }
    });

    // send a message every 2-8 seconds
    const intervalId = setInterval(() => {
      ws.send(JSON.stringify({ event: 'SAY', message: `I'm saying ${randomString(5)}` }));
    }, randomIntBetween(2000, 8000)); // say something every 2-8 seconds

    // after a sessionDuration stop sending messages and leave the room
    const timeout1id = setTimeout(function () {
      clearInterval(intervalId);
      console.log(`VU ${__VU}:${id}: ${sessionDuration}ms passed, leaving the chat`);
      ws.send(JSON.stringify({ event: 'LEAVE' }));
    }, sessionDuration);

    // after a sessionDuration + 3s close the connection
    const timeout2id = setTimeout(function () {
      console.log(`Closing the socket forcefully 3s after graceful LEAVE`);
      ws.close();
    }, sessionDuration + 3000);

    // when connection is closing, clean up the previously created timers
    ws.addEventListener('close', () => {
      clearTimeout(timeout1id);
      clearTimeout(timeout2id);
      console.log(`VU ${__VU}:${id}: disconnected`);
    });
  });
}

import.meta

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

import.meta

The import.meta object provides the resolve function, which resolves a path to a URL string in the same way an import statement does.

The import.meta object is only available in ECMAScript modules, not in CommonJS modules.

Function	Description
import.meta.resolve	Resolves a path to a URL string the same way an import statement does.

JavaScript API on Grafana Labs

Init context

Init context

k6

k6

k6/browser

browser

Asynchronous metric context

Properties

Browser Module API

Example

Devices example

Browser-level APIs

Browser module options

Browser arguments

k6/crypto

k6/crypto

k6/data

k6/data

k6/encoding

k6/encoding

k6/execution

k6/execution

instance

scenario

test

vu

Examples and use cases

Getting unique data once

Timing operations

Script naming

Test Abort

Test Fail

Get test options

Tags

Metadata

k6/experimental

k6/experimental

k6/html

k6/html

k6/http

k6/http

k6/metrics

k6/metrics

k6/net/grpc

k6/net/grpc

gRPC metrics

Example

k6/secrets

k6/secrets

get

source

Example

A full example with multiple secret sources and names

k6/timers

k6/timers

Example

k6/ws

k6/ws

k6/x/dns

k6/x/dns

Key features

Use cases

API

Metrics

Examples

Basic DNS resolution with custom server

DNS lookup using system defaults

Comprehensive DNS testing

k6/x/icmp

k6/x/icmp

Key features

Use cases

API

Metrics

Examples

Basic Usage

Advanced Usage

k6/x/mqtt

k6/x/mqtt