Using k6 on Grafana Labs

Analyze script dependencies

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

k6 deps command

The k6 deps command analyzes your k6 test script and outputs information about the dependencies your script uses.

Usage

k6 deps [options] <script>

Description

When you run k6 deps, k6 analyzes your test script and its imports to identify k6 extensions (such as k6/x/faker, k6/x/redis) and k6 itself that your script uses.

The command outputs dependency information in human-readable format by default, or JSON format with the --json flag. You can use this information to:

Understand what k6 extensions your script uses
Share dependency information with your team
Use it to know if you need a custom binary or if the current one can run the script

The command, like automatic extension resolution, is only able to find dependencies using import/export syntax and “use” directives in already found files. It doesn’t follow potential require calls.

The command also takes into account any provided dependency manifest and applies it during k6 run.

Options

Option	Description
`--json`	Output dependency information in JSON format. Without this flag, the output is human-readable.

Examples

Generate dependency information

Analyze your test script and output dependency information:

k6 deps script.js

This outputs dependency information in human-readable format to stdout.

Generate JSON output

Output the dependency information in JSON format:

k6 deps --json script.js

Output format

The k6 deps command outputs dependency information in human-readable format by default. When using the --json flag, the output is a JSON object.

Human-readable output

The default human-readable output shows:

Build Dependencies: Lists k6 extensions and k6 itself with version constraints (or (none) if there are no build dependencies)
Imports: Lists all imports including file paths and module names
Custom Build Required: Indicates yes or no whether a custom build is required

Example:

Build Dependencies:
  k6: >1.2.0
  k6/x/faker: *

Imports:
  file:///path/to/script.js
  k6/execution
  k6/x/faker

Custom Build Required: yes

JSON output

When using the --json flag, the output is a JSON object with three fields:

buildDependencies: An object mapping k6 extension names (or k6 itself) to version constraints
imports: An array of strings listing all imports
customBuildRequired: A boolean indicating whether a custom build is required

Example:

{
  "buildDependencies": {
    "k6": ">1.2.0",
    "k6/x/faker": "*"
  },
  "imports": [
    "file:///path/to/script.js",
    "k6/execution",
    "k6/x/faker"
  ],
  "customBuildRequired": true
}

Run a k6 test script

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

Run a k6 test script

There are several ways you can use the Grafana k6 command-line tool (CLI) to run a k6 performance test. In this page, you’ll learn how to use each method and how they differ from each other.

Before you begin

To run a CLI test, you’ll need:

A machine with k6 installed.
A test file.

Run a test on your local machine

Running tests locally is a great way to incrementally test your script as you write it. For example, you can make sure that your checks and thresholds are configured correctly before you run a test with more VUs in Grafana Cloud k6.

To run a test locally, use the k6 run command:

k6 run script.js

Run a test using Grafana Cloud k6

Grafana Cloud k6 is a performance testing application that’s part of Grafana Cloud, and it’s powered by k6 OSS. It allows you to leverage all of the Grafana k6 OSS capabilities while managing the infrastructure needed for scaling servers, running load tests from multiple locations, storing test results, and providing dashboards to detect performance errors and regressions.

Grafana Cloud k6 makes it easier to visualize and compare test results by providing you with built-in dashboards, while also making it easier to share and collaborate on test data with other teams in your organization.

To run a cloud test from the CLI, authenticate with k6 cloud login — it will prompt you interactively for your API token and stack:

k6 cloud login

For non-interactive environments such as CI/CD, pass the values directly:

k6 cloud login --token <API_TOKEN> --stack <STACK_SLUG>

With the CLI authentication configured, you can run cloud tests by using the k6 cloud command:

k6 cloud run cloud_demo.js

You can also run a test from a local machine and stream the results for storage and visualization on Grafana Cloud. A common use case for this feature is to run load tests in a CI/CD environment, or on networks that aren’t accessible from the public internet.

To run a test locally and stream the results to Grafana Cloud k6, use the k6 cloud run --local-execution:

k6 cloud run --local-execution cloud_demo.js

Note
The k6 cloud run --local-execution command uploads the test archive k6 produces from your test script and resources to Grafana Cloud.

You can change this behavior by adding the --no-archive-upload option to your command. For example: k6 cloud run --local-execution --no-archive-upload script.js.

To learn more about Grafana Cloud k6, refer to:

Grafana Cloud k6 documentation.
Use the CLI - Learn about the different methods available to run a k6 test in Grafana Cloud.

Run a test in your infrastructure with the k6 Operator

k6 Operator is a Kubernetes operator that you can use to run distributed k6 tests in your Kubernetes cluster.

A couple of reasons why you might want to do this:

You run your application in Kubernetes and would like k6 to be executed in the same fashion as all your other infrastructure components.
You want to run your tests within your private network for security or privacy reasons.

To set up and run a test using the k6 Operator, refer to Set up distributed k6.

Feature flags

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

Feature flags

Feature flags let you try k6 capabilities before they’re on by default. When a feature reaches general availability, it becomes the default and k6 removes the flag.

Unlike operational configuration like K6_WEB_DASHBOARD, flags are temporary. Operational config stays user-controllable indefinitely; flags get removed once their behavior is the default.

Discover available flags

The set of flags changes across k6 releases: some get promoted to defaults and disappear, new ones are added. Check which flags your k6 version supports before enabling one.

k6 features

FEATURE                LIFECYCLE      DESCRIPTION
async-metric-context   Experimental   Propagate metric context through asynchronous operations
freeze-env             Experimental   Freeze __ENV object to prevent modifications from JS code
merge-run-tags         Experimental   Merge run tags across config layers instead of replacing
native-histograms      Experimental   Use native histograms for trend metrics

The async-metric-context flag propagates the tags and metadata associated with metric samples through asynchronous operations, including Promise reactions and timer callbacks. It also enables async callbacks for group(). This flag is experimental, off by default, and may change or be removed.

Module-specific propagation applies to http.asyncRequest(), timers, k6/websockets, gRPC stream handlers, and k6/browser. Refer to each API page for its context-capture boundary and limitations.

Add --json to get machine-readable output, useful for scripting — for example, checking in CI whether a specific flag is available before enabling it:

k6 features --json

[
  {
    "feature": "native-histograms",
    "lifecycle": "Experimental",
    "description": "Use native histograms for trend metrics"
  }
]

Enabling flags

k6 supports three ways to enable flags. Pick the one that fits your workflow.

CLI flag

Use --features to enable a flag for a single run, without touching your config or environment:

k6 run --features native-histograms script.js

Separate multiple flags with commas:

k6 run --features native-histograms,other-flag script.js

Environment variable

Use K6_FEATURES when your CI pipeline or shell environment controls which features are active, without changing your script or config file:

Bash

windows

powershell

K6_FEATURES=native-histograms k6 run script.js

set "K6_FEATURES=native-histograms" && k6 run script.js

$env:K6_FEATURES="native-histograms"; k6 run script.js

Separate multiple flags with commas: K6_FEATURES=native-histograms,other-flag.

JSON config file

Put flags in a config file to version-control them alongside your test suite and share them with your team:

{
  "features": ["native-histograms"]
}

k6 run --config config.json script.js

Precedence

If you set flags in more than one place, CLI wins over the environment variable, which wins over the config file. The winning source is used as-is; k6 ignores the others entirely. For example, if you pass --features, k6 ignores K6_FEATURES for that run.

Lifecycle stages

A flag’s lifecycle stage tells you how stable it is and when to clean it up. Check the stage before relying on a flag in production or long-running CI.

Stage	Behavior
`Experimental`	Off by default. Enable to try it. May change or be removed.
`GA`	On by default. Passing the flag logs a reminder to remove it from your config.
`Deprecated`	Off by default. Removed in a future release.

Note
If you pass a flag k6 doesn’t recognize (a typo or a flag removed after its grace period), k6 logs an ERROR and the run continues. Watch your logs — the flag is not applied.

Migrate from legacy environment variables

Some features previously used their own environment variables. For example, K6_PROMETHEUS_RW_TREND_AS_NATIVE_HISTOGRAM maps to the native-histograms flag. The old variable still works but logs a deprecation warning and will be removed in a future release. Switch to K6_FEATURES=native-histograms or --features native-histograms to avoid breakage when it’s gone.

Observability

If you’re comparing test results across runs (for example, checking whether a feature improved tail latency), you need to know which features were active. k6 tags every metric sample with the active flags so you can filter and compare in your output.

While a flag is active, every metric sample carries a tag k6_feature_<name>="true" (hyphens become underscores, for example k6_feature_native_histograms="true").

k6 also includes active flags in usage telemetry.

Running on Grafana Cloud

Feature flags work the same when you run tests through Grafana Cloud k6. Set them with --features, K6_FEATURES, or a config file. Your test runs on the cloud with the same features active as locally.

HTTP Requests

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

HTTP Requests

When you create a new load test, one of the first steps is to define the HTTP requests that you would like to test.

Make HTTP Requests

A GET request looks like this:

import http from 'k6/http';

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

For something slightly more complex, this example shows a POST request with an email/password authentication payload:

import http from 'k6/http';

export default function () {
  const url = 'http://test.k6.io/login';
  const payload = JSON.stringify({
    email: 'aaa',
    password: 'bbb',
  });

  const params = {
    headers: {
      'Content-Type': 'application/json',
    },
  };

  http.post(url, payload, params);
}

Available methods

The http module handles all kinds of HTTP requests and methods.

Name	Value
batch()	Issue multiple HTTP requests in parallel (like e.g. browsers tend to do).
del()	Issue an HTTP DELETE request.
get()	Issue an HTTP GET request.
head()	Issue an HTTP HEAD request.
options()	Issue an HTTP OPTIONS request.
patch()	Issue an HTTP PATCH request.
post()	Issue an HTTP POST request.
put()	Issue an HTTP PUT request.
request()	Issue any type of HTTP request.

Follow redirects

By default, k6 automatically follows a set number of redirects before stopping and returning the last response. You can customize this by using:

The maxRedirects option to customize the number of redirects globally. Refer to Max redirects for more details.
The Params.redirects property to customize the number of redirects for a specific request, which overrides the maxRedirects option. Refer to Params for more details.

HTTP Request Tags

k6 automatically applies tags to your HTTP requests. You can use these tags to filter your results and organize your analysis.

Name	Description
expected_response	By default, response statuses between 200 and 399 are `true`. Change the default behavior with setResponseCallback.
group	When the request runs inside a group, the tag value is the group name. Default is empty.
name	Defaults to URL requested
method	Request method (`GET`, `POST`, `PUT` etc.)
scenario	When the request runs inside a scenario, the tag value is the scenario name. Default is `default`.
status	response status
url	defaults to URL requested

The following snippet shows a JSON example of how a test-result data point is logged. In this example, the metric is the duration of an HTTP request.

Note how the tags object groups data.

{
  "type": "Point",
  "metric": "http_req_duration",
  "data": {
    "time": "2017-06-02T23:10:29.52444541+02:00",
    "value": 586.831127,
    "tags": {
      "expected_response": "true",
      "group": "",
      "method": "GET",
      "name": "http://test.k6.io",
      "scenario": "default",
      "status": "200",
      "url": "http://test.k6.io"
    }
  }
}

Group URLs under one tag

By default, tags have a name field that holds the value of the request URL. If your test has dynamic URL paths, you might not want this behavior, which could bring a large number of unique URLs into the metrics stream. For example, the following code accesses 100 different URLs:

import http from 'k6/http';

export default function () {
  for (let id = 1; id <= 100; id++) {
    http.get(`http://example.com/posts/${id}`);
  }
}
// tags.name=\"http://example.com/posts/1\",
// tags.name=\"http://example.com/posts/2\",

You might prefer to report this data in a single metric: To aggregate data from dynamic URLs, explicitly set a name tag:

import http from 'k6/http';

export default function () {
  for (let id = 1; id <= 100; id++) {
    http.get(`http://example.com/posts/${id}`, {
      tags: { name: 'PostsItemURL' },
    });
  }
}
// tags.name=\"PostsItemURL\",
// tags.name=\"PostsItemURL\",

That code would produce JSON output like this:

// For http://example.com/1, note that the url is not present in the JSON.

{
    "type":"Point",
    "metric":"http_req_duration",
    "data": {
        "time":"2017-06-02T23:10:29.52444541+02:00",
        "value":586.831127,
        "tags": {
            "method":"GET",
            "name":"PostsItemURL",
            "status":"200",
            "url":"PostsItemURL"
        }
    }
}

// and for http://example.com/2

{
    "type":"Point",
    "metric":"http_req_duration",
    "data": {
        "time":"2017-06-02T23:10:29.58582529+02:00",
        "value":580.839273,
        "tags": {
            "method":"GET",
            "name":"PostsItemURL",
            "status":"200",
            "url":"PostsItemURL"
        }
    }
}

Note how these two objects have the same name, despite having different URLs. If you filter the results for the tag name: PostsItemURL, the results include all data points from all 100 URLs.

As an alternative, you can also use the http.url wrapper to set the name tag with a string template value:

import http from 'k6/http';

export default function () {
  for (let id = 1; id <= 100; id++) {
    http.get(http.url`http://example.com/posts/${id}`);
  }
}
// tags.name="http://example.com/posts/${}",
// tags.name="http://example.com/posts/${}",

Metrics

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

Metrics

Metrics measure how a system performs under test conditions. By default, k6 automatically collects built-in metrics. Besides built-ins, you can also make custom metrics.

Metrics fall into four broad types:

Counters sum values.
Gauges track the smallest, largest, and latest values.
Rates track how frequently a non-zero value occurs.
Trends calculates statistics for multiple values (like mean, mode or percentile).

To make a test fail a certain criteria, you can write a Threshold based on the metric criteria (the specifics of the expression depend on the metric type). To filter metrics, you can use Tags and groups. You can also export metrics in various summary and granular formats, as documented in Results output.

On this page…	Read about…
Built-in metrics	Each built-in metric for each supported protocol
Create custom metrics	How to build your own metric for each metric type

What metrics to look at?

Each metric provides a different perspective on performance. So the best metric for your analysis depends on your goals.

However, if you’re unsure about the metrics to focus on, you can start with the metrics that measure the requests, errors, and duration (the criteria of the RED method).

http_reqs, to measure requests
http_req_failed, to measure error rate
http_req_duration, to measure duration

Note
In other terminology, these metrics measure traffic (in requests), availability (in error rate), and latency (in request duration). SREs might recognize these metrics as three of the four Golden Signals.

Example output

An aggregated summary of all built-in and custom metrics outputs to stdout when you run a test:

import http from 'k6/http';

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

The preceding script outputs something like this:

$ k6 run script.js

         /\      Grafana   /‾‾/
    /\  /  \     |\  __   /  /
   /  \/    \    | |/ /  /   ‾‾\
  /          \   |   (  |  (‾)  |
 / __________ \  |_|\_\  \_____/


  execution: local
     script: http_get.js
     output: -

  scenarios: (100.00%) 1 scenario, 1 max VUs, 10m30s max duration (incl. graceful stop):
           * default: 1 iterations for each of 1 VUs (maxDuration: 10m0s, gracefulStop: 30s)



  █ TOTAL RESULTS

    HTTP
    http_req_duration.......................................................: avg=117.55ms min=117.55ms med=117.55ms max=117.55ms p(90)=117.55ms p(95)=117.55ms
      { expected_response:true }............................................: avg=117.55ms min=117.55ms med=117.55ms max=117.55ms p(90)=117.55ms p(95)=117.55ms
    http_req_failed.........................................................: 0.00%  0 out of 1
    http_reqs...............................................................: 1      2.768749/s

    EXECUTION
    iteration_duration......................................................: avg=361.09ms min=361.09ms med=361.09ms max=361.09ms p(90)=361.09ms p(95)=361.09ms
    iterations..............................................................: 1      2.768749/s

    NETWORK
    data_received...........................................................: 6.8 kB 19 kB/s
    data_sent...............................................................: 541 B  1.5 kB/s

running (00m03.8s), 0/1 VUs, 1 complete and 0 interrupted iterations
default ✓ [======================================] 1 VUs  00m03.8s/10m0s  1/1 iters, 1 per VU

In that output, all the metrics that start with http, iteration, and vu are built-in metrics, which get written to stdout at the end of a test. For details of all metrics, refer to the Metrics reference.

Metric name restrictions

Metric names must comply with OpenTelemetry and Prometheus limitations. The character limit is the same limit k6 had before restricting the character set down.

That means metrics names must:

Include up to 128 symbols (ASCII letters, numbers, or underscores).
Start with a letter or an underscore.

Checks

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

Checks

Checks validate boolean conditions in your test. Testers often use checks to validate that the system is responding with the expected content. For example, a check could validate that a POST request has a response.status == 201, or that the body is of a certain size.

Checks are similar to what many testing frameworks call an assert, but failed checks do not cause the test to abort or finish with a failed status. Instead, k6 keeps track of the rate of failed checks as the test continues to run

Each check creates a rate metric. To make a check abort or fail a test, you can combine it with a Threshold.

Check for HTTP response code

Checks are great for codifying assertions relating to HTTP requests and responses. For example, this snippet makes sure the HTTP response code is a 200:

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

export default function () {
  const res = http.get('http://test.k6.io/');
  check(res, {
    'is status 200': (r) => r.status === 200,
  });
}

Check for text in response body

Sometimes, even an HTTP 200 response contains an error message. In these situations, consider adding a check to verify the response body, like this:

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

export default function () {
  const res = http.get('http://test.k6.io/');
  check(res, {
    'verify homepage text': (r) =>
      r.body.includes('Collection of simple web-pages suitable for load testing'),
  });
}

Check for response body size

To verify the size of the response body, you can use a check like this:

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

export default function () {
  const res = http.get('http://test.k6.io/');
  check(res, {
    'body size is 11,105 bytes': (r) => r.body.length == 11105,
  });
}

See percentage of checks that passed

When a script includes checks, the summary report shows how many of the tests’ checks passed. The check built-in metric is split into three separate metrics: checks_total, checks_succeeded, and checks_failed.:

$ k6 run script.js

  ...
    ✓ is status 200

  ...
  checks_total.......................: 1       1.23/s
  checks_succeeded...................: 100.00% 1 out of 1
  checks_failed......................: 0.00%   0 out of 1
  ...

In this example, note that the check “is status 200” succeeded 100% of the times it was called.

Add multiple checks

You can also add multiple checks within a single check() statement:

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

export default function () {
  const res = http.get('http://test.k6.io/');
  check(res, {
    'is status 200': (r) => r.status === 200,
    'body size is 11,105 bytes': (r) => r.body.length == 11105,
  });
}

When this test executes, the output will look something like this:

$ k6 run checks.js

  ...
    ✓ is status 200
    ✓ body size is 11,105 bytes

  ...
  checks_total.......................: 2       2.34/s
  checks_succeeded...................: 100.00% 2 out of 2
  checks_failed......................: 0.00%   0 out of 2
  ...

Note
When a check fails, the script will continue executing successfully and will not return a ‘failed’ exit status. If you need the whole test to fail based on the results of a check, you have to combine checks with thresholds. This is particularly useful in specific contexts, such as integrating k6 into your CI pipelines or receiving alerts when scheduling your performance tests.

Assertions

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

Note
This is a preview feature.

While we’re committed to supporting and maintaining this feature in the future (we do not anticipate breaking changes) some functionality might be missing; it might be a bit rough around the edges; and there might be use-cases we haven’t covered yet. The feature is considered ready to use, but it is in a preview state as we expect to keep iterating on it by adding new functionalities and improvements.

Users are encouraged to participate in its roadmap and implementation on GitHub. Feel free to open an issue if you have any feedback or suggestions.

Assertions

k6 provides test assertions in the form of the expect function. Assertions validate that your application behaves as expected during testing.

Define assertions by passing a value to expect() and chaining it with a matcher that defines your expected outcome. The library provides expressive matchers that work with both protocol testing HTTP/API and browser testing scenarios.

The assertions API is inspired by Playwright’s assertion syntax, providing a fluent interface that improves test readability and reliability.

Getting started

Assertions are provided by the k6-testing library. Import the library to start using assertions:

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

export function protocolTest() {
  // Get the home page of k6's Quick Pizza app
  const response = http.get('https://quickpizza.grafana.com/');

  // Simple assertions
  expect(response.status).toBe(200);
  expect(response.error).toEqual('');
  expect(response.body).toBeDefined();
}

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

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

    // Assert the "Pizza Please" button is visible
    await expect(page.locator('button[name=pizza-please]')).toBeVisible();
  } finally {
    await page.close();
  }
}

export const options = {
  scenarios: {
    // Protocol tests
    protocol: {
      executor: 'shared-iterations',
      vus: 1,
      iterations: 1,
      exec: 'protocolTest',
    },

    // Browser tests
    ui: {
      executor: 'shared-iterations',
      options: {
        browser: {
          type: 'chromium',
        },
      },
      exec: 'browserTest',
    },
  },
};

Types of assertions

The k6-testing library provides two types of assertions, each designed for different testing scenarios:

Non-retrying assertions

Non-retrying assertions evaluate conditions immediately at a single point in time without retrying. They’re ideal for validating static data such as HTTP response content, data structures, or configuration values.

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

export default function () {
  const pizzaRequestPayload = { maxCaloriesPerSlice: 1000, mustBeVegetarian: true };
  const pizzaRequestHeader = {
    'Content-Type': 'application/json',
    'Authorization': 'Token ' + 'abcdef0123456789',
  };

  const response = http.post(
    `https://quickpizza.grafana.com/api/pizza`,
    JSON.stringify(pizzaRequestPayload),
    { headers: pizzaRequestHeader }
  );
  const data = response.json();

  // These assertions evaluate immediately
  expect(response.status).toEqual(200);
  expect(response.headers['Content-Type']).toBeDefined();
  expect(response.headers['Content-Type']).toEqual('application/json');
  expect(data.pizza).toBeDefined();
  expect(data.pizza.name).toBeDefined();
  expect(data.pizza.name).not.toHaveLength(0);
}

Auto-retrying assertions

Auto-retrying assertions automatically retry until conditions become true or a timeout is reached. They’re designed for browser testing scenarios where elements may take time to load, update, or become interactable.

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

export default async function () {
  // Open a new browser page
  const page = await browser.newPage();

  try {
    // Navigate to the quickpizza website
    await page.goto('https://quickpizza.grafana.com/');

    // Click the 'Pizza please' button
    await page.locator('button[name="pizza-please"]').click();

    // Take a screenshot of the homepage, and save it to the local filesystem
    // so we can inspect it later if needed.
    await page.screenshot({ path: 'homepage.png' });

    // Check if the pizza recipe is displayed
    const textContent = await pizzaRecipeIsDisplayed(page);
    expect(textContent).toEqual('Our recommendation:');
  } finally {
    await page.close();
  }
}

// Browsers are asynchronous, so we need to wait for the content we want to check
// to be visible.
async function pizzaRecipeIsDisplayed(page) {
  const label = await page.locator('h2[id="pizza-name"]');
  await label.isVisible();
  const textContent = (await label.textContent()).trim();

  return textContent;
}

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

Assertions vs. checks

Unlike k6 checks, which continue execution when they fail and register metrics for threshold evaluation, assertions immediately fail and interrupt the test when expectations are not met. Assertions are designed for validating critical conditions that determine whether a test should continue—when these conditions aren’t met, they invalidate the entire testing scenario.

Assertions do not register metrics because they halt execution rather than collect data points. This design provides fast feedback and detailed error messages to help you identify issues quickly, ensuring your tests only proceed when fundamental assumptions are satisfied.

Available assertion methods

Non-retrying assertions

Use these for immediate evaluation of static values:

Method	Description
toBe()	Exact equality using Object.is()
toEqual()	Deep equality comparison
toBeTruthy()	Value is truthy
toBeFalsy()	Value is falsy
toBeDefined()	Value is not undefined
toBeUndefined()	Value is undefined
toBeNull()	Value is null
toBeGreaterThan()	Numeric greater than
toBeGreaterThanOrEqual()	Numeric greater than or equal
toBeLessThan()	Numeric less than
toBeLessThanOrEqual()	Numeric less than or equal
toBeCloseTo()	Floating point comparison
toContain()	Array/string contains value
toContainEqual()	Array contains object with matching content
toHaveLength()	Array/string has specific length
toHaveProperty()	Object has specific property
toBeInstanceOf()	Value is instance of class

See all non-retrying assertions →

Auto-retrying assertions

Essential for browser testing with dynamic content:

Method	Description
toBeVisible()	Element is visible on the page
toBeHidden()	Element is hidden or not visible
toBeEnabled()	Element is enabled and interactive
toBeDisabled()	Element is disabled
toBeChecked()	Checkbox or radio button is checked
toBeEditable()	Element is editable
toHaveText()	Element has specific text content
toContainText()	Element contains specific text
toHaveValue()	Input element has specific value
toHaveAttribute()	Element has specific attribute value

See all retrying assertions →

Assertion features

Negation

All assertions can be negated using .not:

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

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

  // Negated assertions
  expect(response.status).not.toBe(404);
  expect(response.body).not.toHaveLength(0);
  expect(response.headers).not.toHaveProperty('error');

  // Browser negation (with await)
  const page = await browser.newPage();
  await page.goto('https://quickpizza.grafana.com/');

  await expect(page.locator('.error-message')).not.toBeVisible();
}

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

Soft assertions

Soft assertions continue test execution even when they fail, marking the test as failed but allowing subsequent assertions to run. Unlike checks, soft assertions do not measure failures or emit dedicated metrics. If you need failure-related metrics, consider using checks instead:

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

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

  // These will all run even if some fail
  expect.soft(response.status).toBe(200);
  expect.soft(response.headers['Content-Type']).toContain('text/html');
  expect.soft(response.body).toHaveLength(response.body.length);

  // Test continues and performs additional checks
  console.log('Test completed, checking results...');
}

Custom error messages

Provide descriptive error messages for better debugging:

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

export default function () {
  const response = http.get('https://quickpizza.grafana.com/api/pizza', {
    headers: { 'Content-Type': 'application/json' },
  });
  const pizza = response.json();

  expect(response.status, 'API should return successful response').toBe(200);
  expect(pizza.name, 'Pizza should have a valid name').toBeDefined();
  expect(pizza.name, 'Pizza name should not be empty').not.toHaveLength(0);
}

Configuration and customization

Global configuration

Configure assertion behavior globally for all tests:

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

// Configure global settings
const configuredExpect = expect.configure({
  timeout: 10000, // 10 seconds for retrying assertions
  interval: 500, // Retry check every 500ms (on retriable assertions)
  colorize: true, // Enable colored output

  // Setting `softMode` to 'throw', will make soft assertions fail the current iteration instead of the whole test.
  softMode: 'fail',
});

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

  // All assertions use these settings
  configuredExpect(response.status).toBe(200);
}

Per-scenario configuration

Create different configurations for different test scenarios:

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

// Fast assertions for API testing
const fastExpect = expect.configure({
  timeout: 2000,
  interval: 100,
});

// Slow assertions for complex browser interactions
const slowExpect = expect.configure({
  timeout: 30000,
  interval: 1000,
  softMode: 'continue',
});

export default async function () {
  // Use appropriate expectation based on test type
  const response = http.get('https://quickpizza.grafana.com/');
  fastExpect(response.status).toBe(200);

  if (__ENV.BROWSER_TEST) {
    const page = await browser.newPage();
    await page.goto('https://quickpizza.grafana.com/');
    await slowExpect(page.locator('h1')).toBeVisible();
  }
}

Best practices

For tests that primarily use assertions to validate system state, such as tests verifying a successful deployment in CI pipelines, run k6 tests with assertions in quiet mode:

k6 run --quiet --summary-mode=disabled script.ts

This approach eliminates unnecessary output and focuses on the assertion results, making it ideal for automated testing environments.

Thresholds

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

Thresholds

Thresholds are the pass/fail criteria that you define for your test metrics. If the performance of the system under test (SUT) does not meet the conditions of your threshold, the test finishes with a failed status.

Often, testers use thresholds to codify their SLOs. For example, you can create thresholds for any combination of the following expectations:

Less than 1% of requests return an error.
95% of requests have a response time below 200ms.
99% of requests have a response time below 400ms.
A specific endpoint always responds within 300ms.
Any conditions for a custom metric.

Thresholds are also essential for load-testing automation:

Give your test a threshold.
Automate your execution
Set up alerts for test failures.

After that, you need to worry about the test only after your SUT fails to meet its performance expectations.

Thresholds example for HTTP errors and response duration

This sample script specifies two thresholds. One threshold evaluates the rate of HTTP errors (http_req_failed metric). The other evaluates whether 95 percent of responses happen within a certain duration (the http_req_duration metric).

import http from 'k6/http';

export const options = {
  thresholds: {
    http_req_failed: ['rate<0.01'], // http errors should be less than 1%
    http_req_duration: ['p(95)<200'], // 95% of requests should be below 200ms
  },
};

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

In other words, when you define your threshold, specify an expression for a pass criteria. If that expression evaluates to false at the end of the test, k6 considers the whole test a fail.

After executing that script, k6 outputs something similar to this:

  █ THRESHOLDS

    http_req_duration
    ✓ 'p(95)<200' p(95)=148.21ms

    http_req_failed
    ✓ 'rate<0.01' rate=0.05%

  █ TOTAL RESULTS

    HTTP
    http_req_duration..............: avg=151.06ms min=151.06ms med=151.06ms max=151.06ms p(90)=151.06ms p(95)=151.06ms
       { expected_response:true }..: avg=151.06ms min=151.06ms med=151.06ms max=151.06ms p(90)=151.06ms p(95)=151.06ms
    http_req_failed................: 0.00%  ✓ 0 ✗ 1

In this case, the test met the criteria for both thresholds. k6 considers this test a pass and exits with an exit code 0.

If any of the thresholds had failed, the little green checkmark ✓ next to the threshold name (http_req_failed, http_req_duration) would be a red cross ✗ and k6 would exit with a non-zero exit code.

Threshold Syntax

To use a threshold, follow these steps:

In the thresholds property of the options object, set a key using the name of the metric you want the threshold for:
JavaScript
```
export const options = {
  thresholds: {
    /* ... */
  },
};
```
Define at least one threshold expression. You can do this in two ways:
- The short format puts all threshold expressions as strings in an array.
- The long format puts each threshold in an object, with extra properties to abort on failure.
JavaScript
```
export const options = {
  thresholds: {
    //short format
    METRIC_NAME1: ['THRESHOLD_EXPRESSION', `...`],
    //long format
    METRIC_NAME2: [
      {
        threshold: 'THRESHOLD_EXPRESSION',
        abortOnFail: true, // boolean
        delayAbortEval: '10s', // string
      },
    ], // full format
  },
};
```
Note that METRIC_NAME1 and THRESHOLD_EXPRESSION are placeholders. The real text must be the name of the metric and the threshold expression.

This declaration configures thresholds for the metrics metric_name1 and metric_name2. To determine whether the threshold passes or fails, the script evaluates the 'threshold_expression'.

Threshold expression syntax

A threshold expression evaluates to true or false. The threshold expression must be in the following format:

<aggregation_method> <operator> <value>

Some examples of threshold expressions are as follows:

avg < 200 // average duration must be less than 200ms
count >= 500 // count must be larger than or equal to 500
p(90) < 300 // 90% of samples must be below 300

Aggregation methods by type

k6 aggregates metrics according to their type. These aggregation methods form part of the threshold expressions.

Metric type	Aggregation methods
Counter	`count` and `rate`
Gauge	`value`
Rate	`rate`
Trend	`avg`, `min`, `max`, `med` and `p(N)` where `N` specifies the threshold percentile value, expressed as a number between 0.0 and 100. E.g. `p(99.99)` means the 99.99th percentile. The values are in milliseconds.

A percentile value outside the 0 to 100 range (or NaN) fails parsing with an error, so the test stops before running.

This (slightly contrived) sample script uses all different types of metrics, setting different types of thresholds for each:

import http from 'k6/http';
import { Trend, Rate, Counter, Gauge } from 'k6/metrics';
import { sleep } from 'k6';

export const TrendRTT = new Trend('RTT');
export const RateContentOK = new Rate('ContentOK');
export const GaugeContentSize = new Gauge('ContentSize');
export const CounterErrors = new Counter('Errors');
export const options = {
  thresholds: {
    // Count: Incorrect content cannot be returned more than 99 times.
    Errors: ['count<100'],
    // Gauge: returned content must be smaller than 4000 bytes
    ContentSize: ['value<4000'],
    // Rate: content must be OK more than 95 times
    ContentOK: ['rate>0.95'],
    // Trend: Percentiles, averages, medians, and minimums
    // must be within specified milliseconds.
    RTT: ['p(99)<300', 'p(70)<250', 'avg<200', 'med<150', 'min<100'],
  },
};

export default function () {
  const res = http.get('https://quickpizza.grafana.com/api/json?name=Bert');
  const contentOK = res.json('name') === 'Bert';

  TrendRTT.add(res.timings.duration);
  RateContentOK.add(contentOK);
  GaugeContentSize.add(res.body.length);
  CounterErrors.add(!contentOK);

  sleep(1);
}

Caution
Do not specify multiple thresholds for the same metric by repeating the same object key.

Since thresholds are defined as the properties of a JavaScript object, you can’t specify multiple ones with the same property name.

export const options = {
  thresholds: {
    // don't use the same metric more than once here
    metric_name: ['count<100'],
    metric_name: ['rate<50'],
  },
};

The rest will be silently ignored. If you want to set multiple thresholds for a metric, specify them with an array for the same key.

Threshold examples to copy and paste

The quickest way to start with thresholds is to use the built-in metrics. Here are a few copy-paste examples that you can start using right away.

For more specific threshold examples, refer to the Counter, Gauge, Trend and Rate pages.

A percentile of requests finishes in a specified duration

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

export const options = {
  thresholds: {
    // 90% of requests must finish within 400ms.
    http_req_duration: ['p(90) < 400'],
  },
};

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

Error rate is lower than 1 percent

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

export const options = {
  thresholds: {
    // During the whole test execution, the error rate must be lower than 1%.
    http_req_failed: ['rate<0.01'],
  },
};

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

Multiple thresholds on a single metric

You can also apply multiple thresholds for one metric. This threshold has different duration requirements for different request percentiles.

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

export const options = {
  thresholds: {
    // 90% of requests must finish within 400ms, 95% within 800, and 99.9% within 2s.
    http_req_duration: ['p(90) < 400', 'p(95) < 800', 'p(99.9) < 2000'],
  },
};

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

Threshold on group duration

You can set thresholds per Group. This code has groups for individual requests and batch requests. For each group, there are different thresholds.

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

export const options = {
  thresholds: {
    'group_duration{group:::individualRequests}': ['avg < 400'],
    'group_duration{group:::batchRequests}': ['avg < 200'],
  },
  vus: 1,
  duration: '10s',
};

export default function () {
  group('individualRequests', function () {
    http.get('https://quickpizza.grafana.com/api/json?letter=a');
    http.get('https://quickpizza.grafana.com/api/json?letter=b');
    http.get('https://quickpizza.grafana.com/api/json?letter=c');
  });

  group('batchRequests', function () {
    http.batch([
      ['GET', 'https://quickpizza.grafana.com/api/json?letter=a'],
      ['GET', 'https://quickpizza.grafana.com/api/json?letter=b'],
      ['GET', 'https://quickpizza.grafana.com/api/json?letter=c'],
    ]);
  });

  sleep(1);
}

Set thresholds for specific tags

It’s often useful to specify thresholds on a single URL or specific tag. In k6, tagged requests create sub-metrics that you can use in thresholds:

export const options = {
  thresholds: {
    'metric_name{tag_name:tag_value}': ['threshold_expression'],
  },
};

And here’s a full example.

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

export const options = {
  thresholds: {
    'http_req_duration{type:API}': ['p(95)<500'], // threshold on API requests only
    'http_req_duration{type:staticContent}': ['p(95)<200'], // threshold on static content only
  },
};

export default function () {
  const res1 = http.get('https://quickpizza.grafana.com/api/headers', {
    tags: { type: 'API' },
  });
  const res2 = http.get('https://quickpizza.grafana.com/api/json', {
    tags: { type: 'API' },
  });

  const responses = http.batch([
    [
      'GET',
      'https://quickpizza.grafana.com/favicon.ico',
      null,
      { tags: { type: 'staticContent' } },
    ],
    ['GET', 'https://quickpizza.grafana.com/admin', null, { tags: { type: 'staticContent' } }],
  ]);

  sleep(1);
}

Note
When you select scenarios with --scenario, k6 removes thresholds tagged for configured scenarios you exclude and logs a warning. Those thresholds stay skipped even if a selected scenario emits samples with the excluded scenario’s tag. Global thresholds and other tag filters remain active.

Abort a test when a threshold is crossed

If you want to abort a test as soon as a threshold is crossed, set the abortOnFail property to true. When you set abortOnFail, the test run stops as soon as the threshold fails.

Sometimes, though, a test might fail a threshold early and abort before the test generates significant data. To prevent these cases, you can delay abortOnFail with delayAbortEval. In this script, abortOnFail is delayed ten seconds. After ten seconds, the test aborts if it fails the p(99) < 10 threshold.

export const options = {
  thresholds: {
    metric_name: [
      {
        threshold: 'p(99) < 10', // string
        abortOnFail: true, // boolean
        delayAbortEval: '10s', // string
        /*...*/
      },
    ],
  },
};

The fields are as follows:

Name	Type	Description
threshold	string	This is the threshold expression string specifying the threshold condition to evaluate.
abortOnFail	boolean	Whether to abort the test if the threshold is evaluated to false before the test has completed.
delayAbortEval	string	If you want to delay the evaluation of the threshold to let some metric samples to be collected, you can specify the amount of time to delay using relative time strings like `10s`, `1m` and so on.

Here is an example:

import http from 'k6/http';

export const options = {
  vus: 30,
  duration: '2m',
  thresholds: {
    http_req_duration: [{ threshold: 'p(99) < 10', abortOnFail: true }],
  },
};

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

Caution
When k6 runs in the cloud, thresholds are evaluated every 60 seconds. Therefore, the abortOnFail feature may be delayed by up to 60 seconds.

Fail a load test using checks

Checks are nice for codifying assertions, but unlike thresholds, checks do not affect the exit status of k6.

If you use only checks to verify that things work as expected, you can’t fail the whole test run based on the check results.

It’s often useful to combine checks and thresholds, to get the best of both:

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

export const options = {
  vus: 50,
  duration: '10s',
  thresholds: {
    // the rate of successful checks should be higher than 90%
    checks: ['rate>0.9'],
  },
};

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

  check(res, {
    'status is 500': (r) => r.status == 500,
  });

  sleep(1);
}

In this example, the threshold is configured on the checks metric, establishing that the rate of successful checks is higher than 90%.

Additionally, you can use tags on checks if you want to define a threshold based on a particular check or group of checks. For example:

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

export const options = {
  vus: 50,
  duration: '10s',
  thresholds: {
    'checks{myTag:hola}': ['rate>0.9'],
  },
};

export default function () {
  let res;

  res = http.get('https://quickpizza.grafana.com/api/status/500');
  check(res, {
    'status is 500': (r) => r.status == 500,
  });

  res = http.get('https://quickpizza.grafana.com/api/status/200');
  check(
    res,
    {
      'status is 200': (r) => r.status == 200,
    },
    { myTag: 'hola' }
  );

  sleep(1);
}

Options

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

Options

Options configure test-run behavior. For example, options are how you define test tags, thresholds, user agents, and the number of virtual users and iterations.

On this page	Read about…
How to use options	How to set options in different places (with examples), how to override options, and how to access the value of an option as the test runs.
Options reference	Every option, with examples, defaults, and descriptions.

Test lifecycle

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

Test lifecycle

In the lifecycle of a k6 test, a script always runs through these stages in the same order:

Code in the init context prepares the script, loading files, importing modules, and defining the test lifecycle functions. Required.
The setup function runs, setting up the test environment and generating data. Optional.
VU code runs in the default or scenario function, running for as long and as many times as the options define. Required.
The teardown function runs, postprocessing data and closing the test environment. Optional.

Note
Lifecycle functions

Except for init code, each stage occurs in a lifecycle function, a function called in a specific sequence in the k6 runtime.

// 1. init code

export function setup() {
  // 2. setup code
}

export default function (data) {
  // 3. VU code
}

export function teardown(data) {
  // 4. teardown code
}

Overview of the lifecycle stages

For examples and implementation details of each stage, refer to the subsequent sections.

Test stage	Purpose	Example	Called
1. init	Load local files, import modules, declare lifecycle functions	Open JSON file, Import module	Once per VU*
2. Setup	Set up data for processing, share data among VUs	Call API to start test environment	Once
3. VU code	Run the test function, usually `default`	Make https requests, validate responses	Once per iteration, as many times as the test options require
4. Teardown	Process result of setup code, stop test environment	Validate that setup had a certain result, send webhook notifying that test has finished	Once **

* In cloud scripts, init code might be called more often.

** If the Setup function ends abnormally (e.g throws an error), the teardown() function isn’t called. Consider adding logic to the setup() function to handle errors and ensure proper cleanup.

The init stage

The init stage is required. Before the test runs, k6 needs to initialize the test conditions. To prepare the test, code in the init context runs once per VU.

Some operations that might happen in init include the following:

Import modules
Load files from the local file system
Configure the test for all options
Define lifecycle functions for the VU, setup, and teardown stages (and for custom or handleSummary() functions, too).

All code that is outside of a lifecycle function is code in the init context. Code in the init context always executes first.

// init context: importing modules
import http from 'k6/http';
import { Trend } from 'k6/metrics';

// init context: define k6 options
export const options = {
  vus: 10,
  duration: '30s',
};

// init context: global variables
const customTrend = new Trend('oneCustomMetric');

// init context: define custom function
function myCustomFunction() {
  // ...
}

Separating the init stage from the VU stage removes irrelevant computation from VU code, which improves k6 performance and makes test results more reliable. One limitation of init code is that it cannot make HTTP requests. This limitation ensures that the init stage is reproducible across tests (the response from protocol requests is dynamic and unpredictable)

The VU stage

Scripts must contain, at least, a scenario function that defines the logic of the VUs. The code inside this function is VU code. Typically, VU code is inside the default function, but it can also be inside the function defined by a scenario (see subsequent section for an example).

export default function () {
  // do things here...
}

VU code runs over and over through the test duration. VU code can make HTTP requests, emit metrics, and generally do everything you’d expect a load test to do. The only exceptions are the jobs that happen in the init context.

VU code does not load files from your local filesystem.
VU code does not import any other modules.

Again, instead of VU code, init code does these jobs.

The default function life-cycle

A VU executes the default() function from start to end in sequence. Once the VU reaches the end of the function, it loops back to the start and executes the code all over.

As part of this “restart” process, k6 resets the VU. Cookies are cleared, and TCP connections might be torn down (depending on your test configuration options).

Setup and teardown stages

Like default, setup and teardown functions must be exported functions. But unlike the default function, k6 calls setup and teardown only once per test.

setup is called at the beginning of the test, after the init stage but before the VU stage.
teardown is called at the end of a test, after the VU stage (default function).

You can call the full k6 API in the setup and teardown stages, unlike the init stage. For example, you can make HTTP requests:

import http from 'k6/http';

export function setup() {
  const res = http.get('https://quickpizza.grafana.com/api/json');
  return { data: res.json() };
}

export function teardown(data) {
  console.log(JSON.stringify(data));
}

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

The setup() function must complete within the configured setupTimeout (default: 60 seconds). If it exceeds this timeout, the test fails before any VUs start.

In Grafana Cloud k6, setupTimeout has a maximum limit of 10 minutes. If your setup() function requires long-running operations, consider moving heavy work to an external process and passing the results to your test.

Skip setup and teardown execution

You can skip the execution of setup and teardown stages using the options --no-setup and --no-teardown.

k6 run --no-setup --no-teardown ...

Use data from setup in default and teardown

Again, let’s have a look at the basic structure of a k6 test:

// 1. init code

export function setup() {
  // 2. setup code
}

export default function (data) {
  // 3. VU code
}

export function teardown(data) {
  // 4. teardown code
}

You might have noticed the function signatures of the default() and teardown() functions take an argument, referred to here as data.

Here’s an example of passing some data from the setup code to the VU and teardown stages:

export function setup() {
  return { v: 1 };
}

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

export function teardown(data) {
  if (data.v != 1) {
    throw new Error('incorrect data: ' + JSON.stringify(data));
  }
}

For example, with the data returned by the setup() function, you can:

Give each VU access to an identical copy of the data
Postprocess the data in teardown code

However, there are some restrictions.

You can pass only data (i.e. JSON) between setup and the other stages. You cannot pass functions.
If the data returned by the setup() function is large, it will consume more memory.
You cannot manipulate data in the default() function, then pass it to the teardown() function.

It’s best to think that each stage and each VU has access to a fresh “copy” of whatever data the setup() function returns.

It would be extremely complicated and computationally intensive to pass mutable data between all VUs and then to teardown, especially in distributed setups. This would go against a core k6 goal: the same script should be executable in multiple modes.

Additional lifecycle functions

k6 has a few additional ways to use lifecycle functions:

handleSummary(). If you want to make a custom summary, k6 calls one more lifecycle function at the very end of the test.

For details, refer to Custom summary.

Scenario functions. Instead of the default function, you can also run VU code in scenario functions.

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

export const options = {
  scenarios: {
    my_web_test: {
      // the function this scenario will execute
      exec: 'webtest',
      executor: 'constant-vus',
      vus: 50,
      duration: '1m',
    },
  },
};

export function webtest() {
  http.get('https://test.k6.io/contacts.php');
  sleep(Math.random() * 2);
}

Modules

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

Modules

Import modules

It’s common to import modules, or parts of modules, to use in your test scripts. In k6, you can import different kinds of modules:

Built-in modules

k6 provides many built-in modules for core functionalities. For example, the http client make requests against the system under test. For the full list of built-in modules, refer to the API documentation.

import http from 'k6/http';

Local modules

These modules are stored on the local filesystem, and accessed either through relative or absolute filesystem paths.

k6 adopts a browser-like module resolution and doesn’t support Node.js module resolution. File names for imports must be fully specified, such as ./helpers.js.

//my-test.js
import { someHelper } from './helpers.js';

export default function () {
  someHelper();
}

//helpers.js
export function someHelper() {
  // ...
}

Remote modules

These modules are accessed over HTTP(S), from a public source like GitHub, any CDN, or from any publicly accessible web server. The imported modules are downloaded and executed at runtime, making it extremely important to make sure you trust the code before including it in a test script.

For example, jslib is a set of k6 JavaScript libraries available as remote HTTPS modules. They can be downloaded and imported as local modules or directly imported as remote modules.

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

export default function () {
  randomItem([1, 2, 3]);
}

You can also build your custom Javascript libraries and distribute them via a public web hosting. For reference, k6-jslib-aws and k6-rollup-example host their modules as GitHub release assets.

Extension modules

Like the k6 APIs, you can build custom modules in Go code and expose them as JavaScript modules. These custom Go-to-JS modules are known as k6 extensions.

Below is an example that imports the k6/x/kubernetes module from the xk6-kubernetes extension.

import { Kubernetes } from 'k6/x/kubernetes';

const podSpec = {
  apiVersion: 'v1',
  kind: 'Pod',
  metadata: { name: 'busybox', namespace: 'testns' },
  spec: {
    containers: [
      {
        name: 'busybox',
        image: 'busybox',
        command: ['sh', '-c', 'sleep 30'],
      },
    ],
  },
};
export default function () {
  const kubernetes = new Kubernetes();
  kubernetes.create(podSpec);
  const pods = kubernetes.list('Pod', 'testns');
  pods.map(function (pod) {
    console.log(pod.metadata.name);
  });
}

How do k6 extensions (Go-to-JS modules) work? For enhanced performance, the k6 engine is written in Go and embeds a JavaScript VM (sobek) to execute JavaScript test code. That allows you to build your modules in Go code and import them as JavaScript as usual.

To learn more about using or creating k6 extensions, refer to the Extension documentation.

As mentioned previously, users can import custom JavaScript libraries by loading either local or remote modules. Because of that, we have two options to import JavaScript modules, along with various methods to distribute them.

Note
The following options for distributing and sharing JavaScript libraries are available for both custom and other public libraries.

Remote modules

You can host your modules in a public webserver like GitHub and any CDN and be imported remotely.

// As GitHub release assets
import {
  WorkloadConfig,
  sayHello,
} from 'https://github.com/grafana/k6-rollup-example/releases/download/v0.0.2/index.js';

// or hosted in a CDN
import { randomIntBetween, randomItem } from 'https://jslib.k6.io/k6-utils/1.4.0/index.js';

When the library consists of multiple files and modules, you may want to bundle these modules to create public releases. Here are some examples for reference:

Using Webpack: k6-jslib-utils and k6-jslib-aws.
Using Rollup: test-commons.

Be aware that k6 automatically executes remote modules, making it crucial to trust the source code of these remote modules. There is a risk of altering the remote modules with certain hosting mechanisms. To mitigate this security risk, some users prefer to download and import the modules locally to ensure full control of the source code.

Local modules

In this example, the previous remote modules have been downloaded to the lib folder of the testing project and imported as follows:

import { WorkloadConfig, sayHello } from './libs/test-commons.js';

import { randomIntBetween, randomItem } from './libs/k6-utils.js';

Another option to distribute libraries is to use a package manager tool like npm, which enables version locking and the linking of local libraries. The latter can be useful during development.

Although k6 does not resolve node modules, you can utilize a Bundler to load npm dependencies, as shown in the k6-rollup-example.

Use Node.js modules

Caution
k6 isn’t Node.js or a browser. Packages that rely on APIs provided by Node.js, for instance the os and fs modules, won’t work in k6. The same goes for browser-specific APIs, such as the window object.

In a JavaScript project running Node.js, modules are imported using either import or require(), using the Node.js module resolution algorithm. This means that a user can import modules by name, without providing the full filesystem path to the module. For instance:

import { ClassInAModule } from 'cool-module';

The import statement would be automatically resolved by the node resolution algorithm by searching:

The current directory
Any node_modules folder in the directory
Any node_modules folder in a parent directory, up to the closest package.json file.

As the implementation of import in k6 lacks support for the node module resolution algorithm, Node.js modules that resolve external dependencies need to be transformed into a self-contained, isolated, bundle.

That’s done with the help of a bundling tool, such as Webpack, which analyses the test script, identifies all external dependencies, and then creates a self-contained bundle including everything necessary to run the script.

If the test script has no external dependencies, already has them vendored in a k6 compatible way, or only uses ES5.1+ features, using a bundler isn’t necessary.

Pick a bundler

You can use any bundler that supports transpilation. Popular ones include, but are not limited to, webpack, parcel, rollup and browserify.

Due to its flexibility, ease of use, relatively low resource consumption, and known compatibility with k6, it is recommended to use webpack.

You can also use these two example repositories as a starting point:

k6-template-es6: Template using Webpack and Babel to enable ES6 features in k6 tests.
k6-rollup-example: Example using Rollup to bundle k6 tests and release a shared library.

Webpack setup example

Setting up a Babel and Webpack project from scratch might sound like a big undertaking, but is usually accomplished within minutes. Start by creating a project folder and initializing npm:

mkdir ./example-project && \
    cd "$_" && \
    npm init -y

Install packages

Then, install the packages needed:

npm install --save-dev \
    webpack \
    webpack-cli \
    @types/k6 \
    babel-loader \
    @babel/core \
    @babel/preset-env \
    core-js

Package	Usage
webpack	The bundler part of Webpack
webpack-cli	The CLI part of Webpack, which allows us to use it from the terminal
@types/k6	k6 Typescript definition
babel-loader	A loader used by Webpack to leverage babel functionality while bundling
@babel/core	The core functionality of Babel
@babel/preset-env	A smart preset using browserlist, compat-table and electron-to-chromium to determine what code to transpile and polyfill.
core-js	A modular standard library for JS including polyfills

Configure Webpack

Once these packages have been added, the next step will be to set up a webpack.config.js file:

const path = require('path');

module.exports = {
  mode: 'production',
  entry: {
    login: './src/login.test.js',
    signup: './src/signup.test.js',
  },
  output: {
    path: path.resolve(__dirname, 'dist'), // eslint-disable-line
    libraryTarget: 'commonjs',
    filename: '[name].bundle.js',
  },
  module: {
    rules: [{ test: /\.js$/, use: 'babel-loader' }],
  },
  target: 'web',
  externals: /k6(\/.*)?/,
};

Mode

Tells Webpack to automatically use the optimizations associated with the mode. Additional details available in the webpack docs.

Entry

The files Webpack will use as its entry points while performing the bundling. From these points, Webpack will automatically traverse all imports recursively until every possible dependency path has been exhausted. For instance:

// login.test.js

import { SomeService } from './some.service.js';

const svc = new SomeService();

and:

// some.service.js

import * as lodash from 'lodash';

export class SomeService {
  constructor() {
    this._ = lodash;
  }
}

would result in Webpack bundling login.test.js, some.service.js and all upstream dependencies utilized by lodash.

Output

The path key takes an absolute path which is where the finished bundle will be placed. In this example, path.resolve is used to concatenate __dirname and 'dist' into an absolute path.

The libraryTarget key configures how the library will be exposed. Setting it to commonjs will result in it being exported using module.exports. Additional details available in the Webpack docs.

The filename key, as the name suggests, configures the name of the finished bundles. In this example, the template string [name] is used to add a dynamic part to the output filename.

Add a bundle command

Open the package.json file and add a new script entry, used for running the bundling process.

{
  "name": "bundling-example",
  "description": "",
  "version": "0.1.0",
  "private": true,
  "scripts": {
+    "bundle": "webpack"
  }
  ...
}

Bundle tests

Running webpack will now output two different test bundles, that may be executed independently:

$ npm run bundle
# ...
$ tree dist

dist
├── login.bundle.js
└── signup.bundle.js

0 directories, 2 files

Run tests

$ npm run bundle
# ...
$ k6 run dist/login.bundle.js
# ...

$ npm run bundle
# ...
$ k6 run dist/signup.bundle.js \
    --vus 10 \
    --duration 10s
# ...

Use TypeScript

k6 supports partial TypeScript support. For more details, refer to JavaScript and TypeScript compatibility mode.

Use modules with Docker

Built-in and remote modules work out of the box when running k6 in a Docker container like the Grafana k6 Docker image.

Local modules

To run k6 with Docker and import a local module, you must make sure to mount the necessary folders from the host into the container, using Docker volumes. Thus, k6 can see all the JS modules it needs to import.

For example, say you have the following structure on your host machine:

/home/k6/example/src/index.js
/home/k6/example/src/modules/module.js

import { hello_world } from './modules/module.js';

export default function () {
  hello_world();
}

export function hello_world() {
  console.log('Hello world');
}

To run index.js and make the modules available for import we execute the following Docker command with the /home/k6/example/src host folder mounted at /src in the container:

docker run --rm -v /home/k6/example/src:/src -i grafana/k6 run /src/index.js

Note that on Windows, you also need to make sure that your drive in question, say C:\, has been marked for sharing in the Docker Desktop settings.

Extension modules

The official Grafana k6 Docker image includes the k6 release binary but lacks additional k6 extensions. Therefore, using the official Docker container to run a k6 test that requires an extension will fail.

To run k6 with extensions in Docker, create a Docker image that includes the k6 binary with any extension you may want to use. Define a Dockerfile with the necessary xk6 build instructions as follows:

FROM grafana/xk6:latest

RUN GCO_ENABLED=0 xk6 build \
    --with github.com/grafana/xk6-kubernetes@latest

ENTRYPOINT ["./k6"]

After building your custom k6 Docker image, you can run k6 with Docker as usual.

Alternatively, you can implement a multistage Dockerfile build such as shown on this Dockerfile example.

Guidelines for organizing your k6 performance testing suite: Recommendations for large performance testing projects.
JavaScript tools, shared libraries, multiple repos, and central teams: Options for structuring your performance testing projects and sharing k6 libraries with other teams.
JSLib: A collection of k6 JavaScript libraries maintained by Grafana Labs and available as remote modules.
Extensions directory: A collection of k6 extensions maintained by Grafana Labs and the community.
k6-rollup-example: Example using Rollup and Babel to bundle a common library and testing suite.
k6-template-es6: Template using Webpack and Babel to bundle k6 tests into CommonJS modules and polyfill ES+ features.
k6-template-typescript: Template using Webpack and Babel to use TypeScript in your k6 scripts.
JavaScript Compatibility Mode: An option to change the ECMAScript version supported by k6.

Tags and Groups

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

Tags and Groups

A load test usually targets a service with different subsystems and resources. This can make it hard to pinpoint the issues that are degrading performance.

To help you visualize, sort, and filter your test results, k6 adds the following to your results.

Tags categorize your checks, thresholds, custom metrics, and requests for in-depth filtering.
Groups apply tags to the script’s functions.

Besides these granular tags, you can also use options to set test-wide tags. You can use these tags to compare results from multiple tests.

In addition to filtering results, you can also use tags to limit the operations that your thresholds analyze.

Tag	Description
`proto`	the name of the protocol used (e.g. `HTTP/1.1`)
`subproto`	the subprotocol name (used by websockets)
`status`	the HTTP status code (e.g. `200`, `404`, etc.)
`method`	the HTTP method name (e.g. `GET`, `POST`, etc.) or the RPC method name for gRPC
`url`	the HTTP request URL
`name`	the HTTP request name
`group`	the full group path, see the preceding explanation for details about its value
`check`	the Check name
`error`	a string with a non-HTTP error message (e.g. network or DNS error)
`error_code`	A number specifying an error types; a list of current error codes can be found at the Error Codes page
`tls_version`	the TLS version
`scenario`	the name of the scenario where the metric was emitted
`service`	the RPC service name for gRPC
`expected_response`	`true` or `false` based on the responseCallback; by default checks whether the status is 2xx or 3xx

Tag	Description
`vu`	the ID of the virtual user that executed the request
`iter`	the iteration number
`ip`	The IP address of the remote server
`ocsp_status`	the Online Certificate Status Protocol (OCSP) HTTPS status

User-defined tags

Define your own tags to categorize k6 entities based on your test logic. You can tag the following entities:

requests
checks
thresholds
custom metrics

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

const myTrend = new Trend('my_trend');

export default function () {
  // Add tag to request metric data
  const res = http.get('https://quickpizza.grafana.com/', {
    tags: {
      my_tag: "I'm a tag",
    },
  });

  // Add tag to check
  check(res, { 'status is 200': (r) => r.status === 200 }, { my_tag: "I'm a tag" });

  // Add tag to custom metric
  myTrend.add(res.timings.connecting, { my_tag: "I'm a tag" });
}

Test-wide tags

Besides attaching tags to requests, checks, and custom metrics, you can set test-wide tags across all metrics. You can set these tags in four ways:

In the CLI, using one or more --tag NAME=VALUE flags

In the K6_TAGS environment variable, using a comma-separated list of NAME:VALUE pairs:

Bash

windows

powershell

K6_TAGS=name:value,other:value k6 run script.js

set "K6_TAGS=name:value,other:value" && k6 run script.js

$env:K6_TAGS="name:value,other:value"; k6 run script.js

In the script itself:

export const options = {
  tags: {
    name: 'value',
  },
};

In a JSON config file, under the tags key

Combining tags from multiple sources

By default, if you set test-wide tags in more than one place, k6 doesn’t merge them: whichever source has the highest order of precedence replaces the tags from every lower-priority source entirely. For example, if your script sets options.tags = { env: 'staging', team: 'backend' } and you also pass --tag region=us-east, the result is only { region: 'us-east' }.

To merge tags across sources instead of replacing them, enable the merge-run-tags feature flag. With the flag on, k6 combines the tags from the config file, the script, the environment variable, and the CLI, in that order. On a key collision, the higher-priority source wins.

Code-defined tags

In the case, a user-defined tag with advanced logic for handling which tag to set is required then it’s possible doing it by defining the tag from the code.

To support advanced tagging workflows, it is also possible to directly set and get them from scripts’ code.

k6/execution.vu.tags object’s properties can indeed be directly assigned new key/value pairs to define new tags dynamically. This can prove useful, as demonstrated in the following example, to track a container’s group from nested groups, and aggregating nested group’s sub-metrics.

import http from 'k6/http';
import exec from 'k6/execution';
import { group } from 'k6';

export const options = {
  thresholds: {
    'http_reqs{container_group:main}': ['count==3'],
    'http_req_duration{container_group:main}': ['max<1000'],
  },
};

export default function () {
  exec.vu.tags.containerGroup = 'main';

  group('main', function () {
    http.get('https://test.k6.io');
    group('sub', function () {
      http.get('https://quickpizza.grafana.com/');
    });
    http.get('https://quickpizza.grafana.com/api/headers');
  });

  delete exec.vu.tags.containerGroup;

  http.get('https://quickpizza.grafana.com/api/delay/3');
}

Using the same API, you can also retrieve any already set user-defined or system-defined tag:

import exec from 'k6/execution';

export default function () {
  const tag = exec.vu.tags['scenario'];
  console.log(tag); // default
}

Tags and metadata in asynchronous code

Metric context is the set of tags and metadata applied to emitted metric samples, including the current group tag. By default, this context is only reliable in synchronous code. Samples emitted after an asynchronous boundary, such as in an await continuation, a Promise reaction, or a timer callback, might not keep the context that was active when the asynchronous work started.

To propagate metric context through asynchronous operations, enable the experimental and opt-in async-metric-context feature flag. With the feature enabled, k6 captures the current metric context when asynchronous work is registered and applies it when that work runs. It also enables async callbacks in group().

Tagging stages

Thanks to some helper functions in the k6-jslib-utils project, if an executor supports the stages option, you can add tags with the current ongoing stage. Similar to other tags tag, the tag is added to all samples collected during the iteration.

One way to tag the executed operations is to invoke the tagWithCurrentStageIndex function for setting a stage tag for identifying the stage that has executed them:

import http from 'k6/http';
import exec from 'k6/execution';
import { tagWithCurrentStageIndex } from 'https://jslib.k6.io/k6-utils/1.3.0/index.js';

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

export default function () {
  tagWithCurrentStageIndex();

  // all the requests will have a `stage` tag
  // with its value equal to the index of the stage
  http.get('https://test.k6.io'); // e.g. {stage: "1"}
}

Additionally, a profiling function tagWithCurrentStageProfile can add a tag with a computed profile of the current running stage:

import http from 'k6/http';
import exec from 'k6/execution';
import { tagWithCurrentStageProfile } from 'https://jslib.k6.io/k6-utils/1.3.0/index.js';

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

export default function () {
  tagWithCurrentStageProfile();

  // all the requests are tagged with a `stage` tag
  // with the index of the stage as value
  http.get('https://test.k6.io'); // {stage_profile: ramp-up}
}

The profile value based on the current stage can be one of the following options:

Profile	Description
`ramp-up`	The current stage has a target greater than the previous stage’s target
`steady`	The current stage has a target equal to the previous stage’s target
`ramp-down`	The current stage has a target less than the previous stage’s target

Tags in results output

JSON

{
  "type ": "Point ",
  "data ": {
    "time ": "2017-05-09T14:34:45.239531499+02:00 ",
    "value ": 459.865729,
    "tags ": {
      "group ": "::my group::json ",
      "method ": "GET ",
      "status ": "200 ",
      "url ": "http://quickpizza.grafana.com"
    }
  },
  "metric ": "http_req_duration "
}

{
  "type ": "Point ",
  "data ": {
    "time ": "2017-05-09T14:34:45.625742514+02:00 ",
    "value ": 5,
    "tags ": null
  },
  "metric ": "vus "
}

To see how tags affect your test-result output, refer to the k6 results output syntax.

Groups

For extra organization, use groups to organize a load script by functions. You can also nest groups for BDD-style testing.

All metrics emitted in a group have the tag group with a value of all wrapping group names separated by :: (two colons). The root group uses the name ’’ (empty string). If you have a single group named cool requests, the actual value of the group is ::cool requests.

For example, you could use groups to organize multiple requests by page loads or user actions.

import { group } from 'k6';

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

Groups do the following tasks internally:

For each group() function, k6 emits a group_duration metric, which contains the total time to execute the group function.
When a taggable resource—a check, request, or custom metric—runs within a group, k6 sets the tag group with the current group name. For more info, refer to the Tags section.

Both options, the group_duration metric and group tagging, could help you analyze and visualize complex test results. Check out how they work in your k6 result output.

Discouraged: one group per request

Wrapping each request within a group might add unnecessary boilerplate.

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

const id = 5;

export default function () {
  // reconsider this type of code
  group('get post', function () {
    http.get(`http://example.com/posts/${id}`);
  });
  group('list posts', function () {
    const res = http.get(`http://example.com/posts`);
    check(res, {
      'is status 200': (r) => r.status === 200,
    });
  });
}

If your code looks like the preceding snippet, consider the following strategies to write cleaner code:

For dynamic URLs, use the URL grouping feature.
To provide a meaningful name to your request, set the value of tags.name.
To reuse common logic or organize your code better, group logic in functions, or create a local JavaScript module and import it into the test script.
To model advanced user patterns, check out Scenarios.

Cookies

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

Cookies

HTTP Cookies are used by websites and apps to store pieces of stateful information on user devices. Through the Set-Cookie HTTP header, a server tells a client what information it wants stored on the user machine.

The user’s browser stores the cookie data and associates it with the hostname of the server. For each subsequent request to that hostname, it includes the stored cookie data in a Cookie header.

You can then control more specific rules for whether to send the cookie data or not, including limiting it to specific subdomains or paths. You can also set an expiry date on the cookie and tell the browser to send it only over encrypted (SSL/TLS) connections.

Cookies with k6

For most purposes, k6 transparently manages the reception, storage, and transmission of cookies as described. Testing of your cookie-based web site or app will just work without requiring any special action of you.

In some cases, though, you might want more control over cookies. k6 provides multiple options to do this. You can:

Directly manipulate HTTP headers,
Use the more ergonomic cookie API.

The following section shows how to use the Cookie API.

Setting simple cookies

To simulate that a cookie has previously been set by a browser and is now supposed to be included in subsequent requests to the server, include the cookie in the cookies request parameter:

import http from 'k6/http';

export default function () {
  http.get('https://quickpizza.grafana.com/api/cookies', {
    cookies: {
      my_cookie: 'hello world',
    },
  });
}

This applies only to the cookie for the request in question. It isn’t sent for any subsequent requests. To send the cookie for subsequent requests, add it to a cookie jar. By default, k6 has a cookie jar for each VU, which you can interact with to set and inspect cookies:

import http from 'k6/http';

export default function () {
  const jar = http.cookieJar();
  jar.set('https://quickpizza.grafana.com/api/cookies', 'my_cookie', 'hello world');
  http.get('https://quickpizza.grafana.com/api/cookies');
}

The per-VU cookie jar stores all cookies received from the server in a Set-Cookie header. You can also create “local cookie jars” that override the per-VU cookie jar (shown in a subsequent section).

You can also override a cookie that is already part of the per-VU cookie jar:

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 cookies = {
    my_cookie: {
      value: 'hello world 2',
      replace: true,
    },
  };

  const res = http.get('https://quickpizza.grafana.com/api/cookies', {
    cookies,
  });

  check(res.json(), {
    'cookie has correct value': (b) => b.cookies.my_cookie == 'hello world 2',
  });
}

Accessing cookies

To see which cookies were set for a particular response, look in the cookies property of the response object:

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

export default function () {
  const res = http.post('https://quickpizza.grafana.com/api/cookies?my_cookie=hello%20world', {
    redirects: 0,
  });
  check(res, {
    "has cookie 'my_cookie'": (r) => r.cookies.my_cookie.length > 0,
    'cookie has correct value': (r) => r.cookies.my_cookie[0].value === 'hello world',
  });
}

The response object’s cookies property is a map where the key is the cookie name and the value is an array of response cookie objects. This array can support multiple cookies that have the same name but different domain or path attributes, as specified in RFC6265.

A response cookie object contains the following properties:

Property	Type	Description
name	`string`	the name of the cookie
value	`string`	the value of the cookie
domain	`string`	domain deciding what hostnames this cookie should be sent to
path	`string`	limiting the cookie to only be sent if the path of the request matches this value
expires	`string`	when the cookie expires, this needs to be in the RFC1123 format looking like: `Mon, 02 Jan 2006 15:04:05 MST`
max_age	`number`	used for the same purpose as expires but defined as the number of seconds a cookie will be valid
secure	`boolean`	if true, the cookie will only be sent over an encrypted (SSL/TLS) connection
http_only	`boolean`	if true, the cookie would not be exposed to JavaScript in a browser environment

To see which cookies are set and stored in the cookie jar for a particular URL, use the cookieForURL() method of the cookie jar object:

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

export default function () {
  const res = http.post('https://quickpizza.grafana.com/api/cookies?my_cookie=hello%20world', {
    redirects: 0,
  });
  const jar = http.cookieJar();
  const cookies = jar.cookiesForURL('https://quickpizza.grafana.com/api/cookies');
  check(res, {
    "has cookie 'my_cookie'": (r) => cookies.my_cookie.length > 0,
    'cookie has correct value': (r) => cookies.my_cookie[0] === 'hello world',
  });
}

The cookies object returned by the jar’s cookiesForURL() method is a map where the key is the cookie name and the value is an array of cookie values (strings). It is an array to support multiple cookies having the same name (but different domain and/or path attributes), which is part of RFC6265.

Setting advanced cookies with attributes

To set cookies that more tightly controls the behavior of the cookie we must add the cookie to a cookie jar. An example:

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', {
    domain: 'quickpizza.grafana.com',
    path: '/api/cookies',
    secure: true,
    max_age: 600,
  });
  const res = http.get('https://quickpizza.grafana.com/api/cookies');

  check(res, {
    'has status 200': (r) => r.status === 200,
    'cookie has correct value': (r) => r.json().cookies.my_cookie == 'hello world',
  });
}

Besides the per-VU cookie jar, you can also create local cookie jars to override the per-VU cookie jar on a per-request basis:

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

export default function () {
  const jar = new http.CookieJar();

  // Add cookie to local jar
  const cookieOptions = {
    domain: 'quickpizza.grafana.com',
    path: '/api/cookies',
    secure: true,
    max_age: 600,
  };
  jar.set('https://quickpizza.grafana.com/api/cookies', 'my_cookie', 'hello world', cookieOptions);

  // Override per-VU jar with local jar for the following request
  const res = http.get('https://quickpizza.grafana.com/api/cookies', { jar });
  check(res, {
    'has status 200': (r) => r.status === 200,
    'cookie has correct value': (r) => r.json().cookies.my_cookie == 'hello world',
  });
}

Examples

// Example showing two methods how to log all cookies (with attributes) from a HTTP response.
import http from 'k6/http';

function logCookie(c) {
  // 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
  const output = `
     ${c.name}: ${c.value}
     tdomain: ${c.domain}
     tpath: ${c.path}
     texpires: ${c.expires}
     thttpOnly: ${c.http_only}
  `;
  console.log(output);
}
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]);
  });
}

Protocols

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

Protocols

Out of the box, k6 supports the following protocols:

HTTP/1.1
HTTP/2
WebSockets
gRPC

You can use k6 on more protocols with xk6.

Upgrade to HTTP/2 is automatic

By default, k6 uses HTTP/1.1 when it contacts a server. If the server reports to k6 that it supports HTTP/2, k6 upgrades the connection to HTTP/2 instead.

This is all automatic: you don’t need to do anything special for either the initial use of HTTP/1.1 or the potential protocol upgrade. However, you might want to verify which protocol is actually being used for a transaction. This verification requires an extra step.

Using WebSockets is a bit different, for both the test structure and the VU lifecycle.

Extend protocol support with xk6

xk6 is a separate CLI tool that lets you build custom k6 binaries. Community contributors have already added support for additional protocols, with extensions for SQL, Kafka, ZeroMQ, Redis, and more. Refer to the full list of extensions and find the ones you want to build. Then follow the xk6 guide.

You can build your own extension, too. See the tutorials to get started.

Environment variables

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

Environment variables

Often, scripts need only minor tweaks to be reusable in different contexts. Rather than creating several separate scripts for these different contexts or environments, you can use environment variables to make parts of your script tweakable.

You can use environment variables for two main purposes:

Passing environment variables to the k6 Script
Configuring k6 Options with environment variables

Passing environment variables to the k6 script

In k6, the environment variables are exposed through a global __ENV variable, a JS object. For reference, see the script example below:

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

export default function () {
  const res = http.get(`http://${__ENV.MY_HOSTNAME}/`);
  sleep(1);
}

By default, __ENV is a plain, mutable object: assignments like __ENV.MY_HOSTNAME = 'other' persist for the rest of the iteration. To make __ENV read-only instead, enable the freeze-env feature flag. Modifying it will then throw a TypeError in strict-mode code, or fail silently otherwise.

The recommended option to pass environment variables to your testing script is to use one or more -e / --env CLI flags (this command works the same for all platforms):

k6 run -e MY_HOSTNAME=test.k6.io script.js

⚠ The -e flag does not configure options

This flag just provides variables to the script, which the script can use or ignore. For example, -e K6_ITERATIONS=120 does not configure the script iterations.

Compare this behavior with K6_ITERATIONS=120 k6 run script.js, which does set iterations.

A second option to pass environment variables is to source them from the local system.

MY_HOSTNAME=test.k6.io k6 run script.js

set "MY_HOSTNAME=test.k6.io" && k6 run script.js

$env:MY_HOSTNAME="test.k6.io"; k6 run script.js

⚠️ Warning

By default, passing system environment variables doesn’t work for k6 archive, k6 cloud run, and k6 inspect. This is a security measure to avoid the risk of uploading sensitive data to k6 Cloud. To override this mode, specify –include-system-env-vars.

Configure k6 options with environment variables

You can also configure k6 options with environment variables. Consider this script:

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

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

By default, a local run of this script will execute a single iteration with one virtual user(VU). To modify the default behavior, pass k6 options as environment variables. For example, this snippet configures the script to run 10 virtual users for a duration of 10 seconds:

Bash

windows

powershell

K6_VUS=10 K6_DURATION=10s k6 run script.js

set "K6_VUS=10 K6_DURATION=10s" && k6 run script.js

$env:K6_VUS=10 ; $env:K6_DURATION="10s" ; k6 run script.js

As the preceding example shows, you need to prefix K6_ in the environment variable name for k6 to evaluate it as an option parameter. However, be aware that not all options are supported as environment variables. You can confirm whether one is by checking the documentation for each option.

You can also use the K6_FEATURES environment variable to enable feature flags, which opt in to new, not-yet-stable k6 behavior.

Note that when you define options in multiple places, there’s an order of precedence that determines the option to use. To ensure you’re always working with the highest precedence, use command-line flags instead of environment variables:

k6 run -e MY_HOSTNAME=test.k6.io --duration 10s --vus 10 script.js

Manage environment variables in k6 Cloud

Execution context variables

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

Execution context variables

In some cases, it’s really useful to have information about the script’s current test-execution state. For example, you might want to

Have different VUs run different test logic
Use different data for each VU and iteration
Figure out the stage that a test is in

To solve these issues, you can use execution context variables.

k6/execution

The k6/execution module exposes details about the current execution state, such as the name of the currently executed scenario, how many VUs are currently active, and more. The module provides test-execution information via three properties:

Property	Meta-information and execution details about
instance	The current running k6 instance
scenario	The current running scenario
vu	The current VU and iteration

Example: log all context variables

If you want to experiment with what each context variable looks like as a test runs, you can copy this template literal into one of your test scripts.

Note that this omits the abort variable, since that function would abort the test.

import exec from 'k6/execution';

export default function () {
  console.log(`Execution context

Instance info
-------------
Vus active: ${exec.instance.vusActive}
Iterations completed: ${exec.instance.iterationsCompleted}
Iterations interrupted:  ${exec.instance.iterationsInterrupted}
Iterations completed:  ${exec.instance.iterationsCompleted}
Iterations active:  ${exec.instance.vusActive}
Initialized vus:  ${exec.instance.vusInitialized}
Time passed from start of run(ms):  ${exec.instance.currentTestRunDuration}

Scenario info
-------------
Name of the running scenario: ${exec.scenario.name}
Executor type: ${exec.scenario.executor}
Scenario start timestamp: ${exec.scenario.startTime}
Percentage complete: ${exec.scenario.progress}
Iteration in instance: ${exec.scenario.iterationInInstance}
Iteration in test: ${exec.scenario.iterationInTest}

Test info
---------
All test options: ${exec.test.options}

VU info
-------
Iteration id: ${exec.vu.iterationInInstance}
Iteration in scenario: ${exec.vu.iterationInScenario}
VU ID in instance: ${exec.vu.idInInstance}
VU ID in test: ${exec.vu.idInTest}
VU tags: ${exec.vu.tags}`);
}

For detailed reference, refer to the k6/execution module.

Additional examples

Note
k6 v0.34.0 introduced the k6/execution module. If you are using a version of k6 that doesn’t have this module, use __VU and __ITER.

__VU and __ITER are both global variables with execution-context information that k6 makes available to the test script.

__ITER: A numeric counter with the current iteration number for a specific VU. Zero-based.
__VU: Current VU number in use. k6 assigns the value incrementally for each new VU instance, starting from one. The variable is 0 when executing the setup and teardown functions.

Running in k6 Cloud

When you run tests in Grafana Cloud k6, the __VU value is per server/load generator.

Examples

import http from 'k6/http';
import { sleep } from 'k6';
export default function () {
  http.get('http://test.k6.io');
  console.log(`VU: ${__VU}  -  ITER: ${__ITER}`);
  sleep(1);
}

You can use execution-context variables to configure different test behaviors and parameterizations. A typical use case is a load test that simulates different users performing a login flow.

import http from 'k6/http';
import { sleep } from 'k6';
export default function () {
  const email = `user+${__VU}@mail.com`;
  const payload = JSON.stringify({ email: email, password: 'test' });
  const params = { headers: { 'Content-Type': 'application/json' } };
  http.post('http://test.k6.io/login', payload, params);
  console.log(email);
  // .. continue the user flow
  sleep(1);
}

Grafana Cloud k6 context variables

Grafana Cloud k6 injects additional context variables into a running cloud test. These variables provide information about the server (K6_CLOUDRUN_INSTANCE_ID), load zone (K6_CLOUDRUN_LOAD_ZONE),instance ID (K6_CLOUDRUN_INSTANCE_ID), and cloud distribution (K6_CLOUDRUN_DISTRIBUTION).

Refer to Cloud execution context variables for more details.

Scenarios

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

Scenarios

Scenarios configure how VUs and iteration schedules in granular detail. With scenarios, you can model diverse workloads, or traffic patterns in load tests.

Benefits of using scenarios include:

Easier, more flexible test organization. You can declare multiple scenarios in the same script, and each one can independently execute a different JavaScript function.
Simulate more realistic traffic. Every scenario can use a distinct VU and iteration scheduling pattern, powered by a purpose-built executor.
Parallel or sequential workloads. Scenarios are independent from each other and run in parallel, though they can be made to appear sequential by setting the startTime property of each carefully.
Granular results analysis. Different environment variables and metric tags can be set per scenario.

Configure scenarios

To configure scenarios, use the scenarios key in the options object. You can give the scenario any name, as long as each scenario name in the script is unique.

The scenario name appears in the result summary, tags, and so on.

export const options = {
  scenarios: {
    example_scenario: {
      // name of the executor to use
      executor: 'shared-iterations',

      // common scenario configuration
      startTime: '10s',
      gracefulStop: '5s',
      env: { EXAMPLEVAR: 'testing' },
      tags: { example_tag: 'testing' },

      // executor-specific configuration
      vus: 10,
      iterations: 200,
      maxDuration: '10s',
    },
    another_scenario: {
      /*...*/
    },
  },
};

Scenario executors

For each k6 scenario, the VU workload is scheduled by an executor. Executors configure how long the test runs, whether traffic stays constant or changes, and whether the workload is modeled by VUs or by arrival rate (that is, open or closed models).

Your scenario object must define the executor property with one of the predefined executor names. Your choice of executor determines how k6 models load. Choices include:

By number of iterations.
- shared-iterations shares iterations between VUs.
- per-vu-iterations has each VU run the configured iterations.
By number of VUs.
- constant-VUs sends VUs at a constant number.
- ramping-vus ramps the number of VUs according to your configured stages.
By iteration rate.
- constant-arrival-rate starts iterations at a constant rate.
- ramping-arrival-rate ramps the iteration rate according to your configured stages.

Along with the generic scenario options, each executor object has additional options specific to its workload. For the full list, refer to Executors.

Scenario options

Option	Type	Description	Default
executor^(required) ️	string	Unique executor name. See the list of possible values in the executors section.	-
startTime	string	Time offset since the start of the test, at which point this scenario should begin execution.	`"0s"`
gracefulStop	string	Time to wait for iterations to finish executing before stopping them forcefully. To learn more, read Graceful stop.	`"30s"`
exec	string	Name of exported JS function to execute.	`"default"`
env	object	Environment variables specific to this scenario.	`{}`
tags	object	Tags specific to this scenario.	`{}`
options	object	Additional options include browser options.	`{}`

Scenario example

This script combines two scenarios, with sequencing:

The shared_iter_scenario starts immediately. Ten VUs try to use 100 iterations as quickly as possible (some VUs may use more iterations than others).
The per_vu_scenario starts after 10s. In this case, ten VUs each run ten iterations.

Which scenario takes longer? You can run to discover. You can also add a maxDuration property to one or both scenarios.

import http from 'k6/http';

export const options = {
  scenarios: {
    shared_iter_scenario: {
      executor: 'shared-iterations',
      vus: 10,
      iterations: 100,
      startTime: '0s',
    },
    per_vu_scenario: {
      executor: 'per-vu-iterations',
      vus: 10,
      iterations: 10,
      startTime: '10s',
    },
  },
};

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

If you run a script with scenarios, k6 output includes high-level information about each one. For example, if you run the preceding script, k6 run scenario-example.js, then k6 reports the scenarios as follows:

  execution: local
     script: scenario-example.js
     output: -

  scenarios: (100.00%) 2 scenarios, 20 max VUs, 10m40s max duration (incl. grace
ful stop):
           * shared_iter_scenario: 100 iterations shared among 10 VUs (maxDurati
on: 10m0s, gracefulStop: 30s)
           * per_vu_scenario: 10 iterations for each of 10 VUs (maxDuration: 10m
0s, startTime: 10s, gracefulStop: 30s)

The full output includes the summary metrics, like any default end-of-test summary:

         /\      Grafana   /‾‾/
    /\  /  \     |\  __   /  /
   /  \/    \    | |/ /  /   ‾‾\
  /          \   |   (  |  (‾)  |
 / __________ \  |_|\_\  \_____/

  execution: local
     script: scenario-example.js
     output: -

  scenarios: (100.00%) 2 scenarios, 20 max VUs, 10m40s max duration (incl. grace
ful stop):
           * shared_iter_scenario: 100 iterations shared among 10 VUs (maxDurati
on: 10m0s, gracefulStop: 30s)
           * per_vu_scenario: 10 iterations for each of 10 VUs (maxDuration: 10m
0s, startTime: 10s, gracefulStop: 30s)

  █ TOTAL RESULTS

    HTTP
    http_req_blocked........................................................: avg=24.59ms  min=1µs      med=4µs      max=263.64ms p(90)=22.48ms  p(95)=245.04ms
    http_req_connecting.....................................................: avg=11.36ms  min=0s       med=0s       max=120.45ms p(90)=10.76ms  p(95)=115.19ms
    http_req_duration.......................................................: avg=115.25ms min=108.25ms med=115.66ms max=170.62ms p(90)=119.59ms p(95)=121.13ms
      { expected_response:true }............................................: avg=115.25ms min=108.25ms med=115.66ms max=170.62ms p(90)=119.59ms p(95)=121.13ms
    http_req_failed.........................................................: 0.00%  0 out of 200
    http_req_receiving......................................................: avg=214.61µs min=15µs     med=73.5µs   max=4.57ms   p(90)=253.4µs  p(95)=1.08ms
    http_req_sending........................................................: avg=17.79µs  min=3µs      med=12µs     max=669µs    p(90)=22µs     p(95)=25µs
    http_req_tls_handshaking................................................: avg=12.01ms  min=0s       med=0s       max=126.23ms p(90)=11.49ms  p(95)=120.04ms
    http_req_waiting........................................................: avg=115.02ms min=107.7ms  med=115.33ms max=170.59ms p(90)=119.54ms p(95)=121.04ms
    http_reqs...............................................................: 200    17.489795/s

    EXECUTION
    iteration_duration......................................................: avg=140.07ms min=108.3ms  med=116.14ms max=383.32ms p(90)=187.14ms p(95)=363.64ms
    iterations..............................................................: 200    17.489795/s
    vus.....................................................................: 10     min=0        max=10
    vus_max.................................................................: 20     min=20       max=20

    NETWORK
    data_received...........................................................: 2.4 MB 209 kB/s
    data_sent...............................................................: 26 kB  2.3 kB/s


  █ SCENARIO: per_vu_scenario

    HTTP
    http_req_blocked...................................: avg=23.52ms  min=1µs      med=4µs      max=244.87ms p(90)=22.39ms  p(95)=234.84ms
    http_req_connecting................................: avg=11.45ms  min=0s       med=0s       max=120.45ms p(90)=10.84ms  p(95)=115.81ms
    http_req_duration..................................: avg=114.86ms min=108.25ms med=115.74ms max=123.17ms p(90)=120.08ms p(95)=121.13ms
    http_req_failed....................................: 0.00%  0 out of 100
    http_req_receiving.................................: avg=195.59µs min=15µs     med=73.5µs   max=4.57ms   p(90)=247.5µs  p(95)=875.99µs
    http_req_sending...................................: avg=20.8µs   min=3µs      med=12µs     max=669µs    p(90)=22.1µs   p(95)=27.09µs
    http_req_tls_handshaking...........................: avg=12.06ms  min=0s       med=0s       max=126.23ms p(90)=11.49ms  p(95)=120.61ms
    http_req_waiting...................................: avg=114.64ms min=107.78ms med=115.38ms max=123.07ms p(90)=120.04ms p(95)=121.04ms
    http_reqs..........................................: 100    8.744897/s

    EXECUTION
    iteration_duration.................................: avg=138.53ms min=108.3ms  med=116.22ms max=363.71ms p(90)=144.44ms p(95)=353.48ms
    iterations.........................................: 100    8.744897/s

    NETWORK
    data_received......................................: 1.2 MB 104 kB/s
    data_sent..........................................: 13 kB  1.1 kB/s


  █ SCENARIO: shared_iter_scenario

    HTTP
    http_req_blocked...................................: avg=25.66ms  min=1µs      med=4µs      max=263.64ms p(90)=24.98ms  p(95)=256.16ms
    http_req_connecting................................: avg=11.27ms  min=0s       med=0s       max=115.37ms p(90)=10.76ms  p(95)=115.15ms
    http_req_duration..................................: avg=115.65ms min=108.38ms med=115.61ms max=170.62ms p(90)=119.11ms p(95)=120.91ms
    http_req_failed....................................: 0.00%  0 out of 100
    http_req_receiving.................................: avg=233.63µs min=22µs     med=73.5µs   max=4.22ms   p(90)=324.6µs  p(95)=1.11ms
    http_req_sending...................................: avg=14.77µs  min=3µs      med=12µs     max=128µs    p(90)=20µs     p(95)=22µs
    http_req_tls_handshaking...........................: avg=11.96ms  min=0s       med=0s       max=124.34ms p(90)=11.64ms  p(95)=118.98ms
    http_req_waiting...................................: avg=115.4ms  min=107.7ms  med=115.33ms max=170.59ms p(90)=118.94ms p(95)=120.85ms
    http_reqs..........................................: 100    8.744897/s

    EXECUTION
    iteration_duration.................................: avg=141.6ms  min=108.46ms med=116.09ms max=383.32ms p(90)=189.98ms p(95)=375.24ms
    iterations.........................................: 100    8.744897/s

    NETWORK
    data_received......................................: 1.2 MB 104 kB/s
    data_sent..........................................: 13 kB  1.1 kB/s

running (00m12.8s), 00/20 VUs, 200 complete and 0 interrupted iterations
shared_iter_scenario ✓ [ 100% ] 10 VUs  00m02.7s/10m0s  100/100 shared iters
per_vu_scenario      ✓ [ 100% ] 10 VUs  00m02.8s/10m0s  100/100 iters, 10 per V

Run selected scenarios

Use --scenario to run part of a multi-scenario script without editing it or adding environment-variable logic. For example, run only the workload for the API method you are developing, or run a subset on every commit and the full test less often. Selected scenarios keep their configured load.

Save this example as scenarios.js:

export const options = {
  scenarios: {
    api: {
      executor: 'shared-iterations',
      vus: 1,
      iterations: 2,
      exec: 'api',
    },
    checkout: {
      executor: 'shared-iterations',
      vus: 1,
      iterations: 3,
      exec: 'checkout',
    },
  },
  thresholds: {
    iterations: ['count>0'],
    'iterations{scenario:api}': ['count>0'],
    'iterations{scenario:checkout}': ['count>0'],
  },
};

export function api() {
  console.log('API iteration');
}

export function checkout() {
  console.log('Checkout iteration');
}

Select one name, or separate several names with commas:

k6 run --scenario checkout scenarios.js
k6 run --scenario api,checkout scenarios.js

The first command runs three checkout iterations. The second runs both scenarios with their configured iteration counts. Selection preserves each scenario’s executor, load, timing, function, environment, tags, and browser settings. Other global options and the normal test lifecycle still apply, including setup() and teardown().

Names must exist in the configured scenarios object after the script’s initialization code runs. A default export alone does not define a selectable scenario; --scenario default requires an explicitly configured scenarios.default. An empty selection or an unknown name returns an error.

Load options and thresholds

You cannot combine --scenario with --vus, --duration, --iterations, or --stage. k6 ignores the corresponding top-level settings from the script, a configuration file, or environment variables and logs a warning. Settings inside selected scenarios remain intact. Execution segments remain active and can reduce the work assigned to selected scenarios.

Selection removes thresholds whose scenario tag names a configured scenario that you excluded, and logs a warning. In the example, selecting checkout skips the API threshold and keeps the global and checkout thresholds. Global thresholds, filters without a scenario tag, and filters naming a selected or unconfigured scenario remain active. A global count threshold that expects the full workload can still fail a partial run.

A skipped threshold stays skipped even if another scenario emits samples with the excluded scenario’s tag. For example, a selected checkout scenario can emit a custom metric tagged scenario:api; an API threshold removed by selection will not evaluate those samples. Refer to thresholds for specific tags when choosing which assertions should remain shared.

Cloud runs and archives

The same selection works with k6 cloud run, including --local-execution, and k6 archive. Archives save the selected scenarios and remaining thresholds, so you can replay an archive without repeating --scenario. Omitting the flag on replay does not restore excluded scenarios or thresholds.

Run each selected scenario once

To check the selected workloads with one iteration each, combine --scenario with --once. Selection chooses which scenarios run; --once gives each one a single VU and iteration:

k6 run --scenario api,checkout --once scenarios.js

This command runs one API iteration and one checkout iteration. Each scenario keeps its function, environment, tags, and browser settings, while --once resets its executor and timing to shared-iterations, startTime: '0s', maxDuration: '10m', and gracefulStop: '30s'. Execution segments cannot be combined with --once. Bare --once still rejects a script with multiple scenarios; explicit selection tells k6 which ones to run.

Secret source

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

Secret source

Secret sources provide a secure way for k6 to retrieve and use secrets. Unlike values from environment variables or files, values from secret sources are automatically redacted from k6 logs before propagation through the system.

Access secrets through the k6/secrets JavaScript API. All secrets are redacted from logs.

Configure secret sources

Configure secret sources using the --secret-source CLI flag. You can configure multiple secret sources simultaneously.

Built-in secret sources

The following built-in secret sources are available for local testing:

file: Reads secrets from a key=value file.
mock: Reads secrets from CLI arguments.
url: Fetches secrets from HTTP endpoints.

The following built-in secret source is available for k6 cloud run --local-execution:

cloud: Fetches secrets from Grafana Cloud k6.

Secret source extensions

You can implement a secret source as an extension for k6.

Example script

import http from 'k6/http';
import secrets from 'k6/secrets';

export default async () => {
  const my_secret = await secrets.get('cool'); // Retrieves secret by identifier
  console.log(my_secret);
  const response = await http.asyncRequest('GET', 'https://httpbin.org/get', null, {
    headers: {
      'Custom-Authentication': `Bearer ${await secrets.get('else')}`,
    },
  });
  console.log(response.body);
};

Run the script with the following secrets file:

cool=some
else=source

The following output shows how secrets are redacted in logs, shown as ***SECRET_REDACTED***, while remaining accessible to the script.

$ k6 run --secret-source=file=file.secret secrets.test.js
...
INFO[0000] ***SECRET_REDACTED***                         source=console
INFO[0001] {
  "args": {},
  "headers": {
    "Custom-Authentication": "Bearer ***SECRET_REDACTED***",
    "Host": "httpbin.org",
    "User-Agent": "k6/0.57.0 (https://k6.io/)",
    "X-Amzn-Trace-Id": "Root=1-67dd638b-4243896a2fa1b1b45bc63eaa"
  },
  "origin": "<my actual IP>",
  "url": "https://httpbin.org/get"
}  ***SECRET_REDACTED***=console

Test authoring

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

Test authoring

JavaScript and TypeScript compatibility mode

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

JavaScript compatibility mode

Note
If you’re using k6 v0.53 or higher, the compatibility mode feature doesn’t have much impact on the k6 default behavior. Refer to this GitHub issue for more details.

Starting on k6 v0.57, TypeScript support is enabled by default, and the experimental-enhanced-mode option has been removed.

k6 offers two JavaScript compatibility modes:

Base mode: Only uses native support in k6 and the underlying JavaScript runtime. For k6 v0.53.0 or higher, it has the same functionality as extended apart from the global aliasing.
Extended mode: Similar to base mode, with an additional alias from global to globalThis for Node.js compatibility. This is the default mode.

After k6 v0.53.0, the only difference between the base and extended modes is that global, the Node.js global variable, is aliased to the value of globalThis.

When running tests, you can change the mode by using the --compatibility-mode option:

Env	CLI	Code / Config file	Default
`K6_COMPATIBILITY_MODE`	`--compatibility-mode`	N/A	`"extended"`

Extended mode

By default, k6 uses the --compatibility-mode=extended mode:

k6 run script.js

Base mode

cli

env

k6 run --compatibility-mode=base script.js

K6_COMPATIBILITY_MODE=base k6 run script.js

Typescript support

cli

env

k6 run script.ts

k6 run script.ts

k6 uses esbuild to transpile TypeScript (TS) code for all files that have the .ts extension.

TypeScript support is partial as it strips the type information but doesn’t provide type safety.

CommonJS Example

const http = require('k6/http');
const k6 = require('k6');

module.exports.options = {
  vus: 10,
  duration: '30s',
};

module.exports.default = function () {
  http.get('http://test.k6.io');
  k6.sleep(1);
};

⚠️ About require()

Note that require() is a custom k6 implementation of module loading, which doesn’t behave in the same way as the require() call in Node.js. Specifically, it only handles loading of built-in k6 modules, scripts on the local filesystem, and remote scripts over HTTP(S), but it does not support the Node.js module resolution algorithm.

Bundling with Babel outside of k6

The examples below demonstrate the use of Babel with bundlers like Webpack and Rollup:

k6-template-es6: Template using Webpack and Babel to bundle k6 tests.
k6-rollup-example: Example using Rollup and Babel to bundle a testing project.

Running large tests: Optimize k6 for better performance.
k6 Modules: Different options to import modules in k6.
k6 Archive Command: The k6 archive command bundles all k6 test dependencies into a tar file, which can then be used for execution. It may also reduce the execution startup time.

Using k6 on Grafana Labs

Analyze script dependencies

k6 deps command

Usage

Description

Options

Examples

Generate dependency information

Generate JSON output

Output format

Human-readable output

JSON output

Run a k6 test script

Run a k6 test script

Before you begin

Run a test on your local machine

Run a test using Grafana Cloud k6

Run a test in your infrastructure with the k6 Operator

Feature flags

Feature flags

Discover available flags

Enabling flags

CLI flag

Environment variable

JSON config file

Precedence

Lifecycle stages

Migrate from legacy environment variables

Observability

Running on Grafana Cloud

Read more

HTTP Requests

HTTP Requests

Make HTTP Requests

Available methods

Follow redirects

HTTP Request Tags

Group URLs under one tag

Metrics

Metrics

What metrics to look at?

Example output

Metric name restrictions

Checks

Checks

Check for HTTP response code

Check for text in response body

Check for response body size

See percentage of checks that passed

Add multiple checks

Read more

Assertions

Assertions

Getting started

Types of assertions

Non-retrying assertions

Auto-retrying assertions

Assertions vs. checks

Available assertion methods

Non-retrying assertions

Auto-retrying assertions

Assertion features

Negation

Soft assertions

Custom error messages

Configuration and customization

Global configuration

Per-scenario configuration

Best practices

See also

Thresholds

Thresholds

Thresholds example for HTTP errors and response duration

Threshold Syntax

Threshold expression syntax

Aggregation methods by type

Threshold examples to copy and paste

A percentile of requests finishes in a specified duration

Error rate is lower than 1 percent

Multiple thresholds on a single metric

⚠ The `-e` flag does not configure options