A modern load testing tool, using Go and JavaScript

"like unit testing, for performance"

k6 is a modern load testing tool, building on Load Impact's years of experience. It provides a clean, approachable JavaScript scripting API, distributed and cloud execution, and orchestration via a REST API.

k6 REST API

Recent Posts

Archive

Options

What are options?

Options allow you to configure how k6 will behave during test execution. They can be a part of the script code so that they can be version controlled. They can also be specified with command line flags, environment variables or via a config file. Please refer to the list of available options below for more details.

The order of precedence is: defaults < config file < exported script options < environment variables < command-line flags. Options from each subsequent level can be used to overwrite the options from the previous levels, with the CLI flags having the highest priority.

Available options

The table below details the available options that can be specified within a script. It also documents the equivalent command line flag, environment variables or option when executing k6 run ... and k6 cloud ... that can be used to override options specified in the code.

Option name

Option value

durationor--duration value or -d valueorK6_DURATION

A string specifying the total duration a test run should be run for. During this time each VU will execute the script in a loop.

Default: null

Examples

export let options = {
duration: "3m"
};

Available in k6 run and k6 cloud commands

ext

An object used to set configuration options for third-party collectors (like plugins).

Default: null

ExamplesThis is an example of how to specify the test name (test runs/executions with the same name will be logically grouped together for trending and comparison purposes) when streaming results to Load Impact Insights.

Available in k6 run command (not supported yet for cloud executed tests using k6 cloud command)

lingeror--linger or -lorK6_LINGER

A boolean, true or false, specifying whether the k6 process should linger around after test run completion. The primary use case for this is when making use of the k6 web UI.

Default: false

Examples

export let options = {
linger: true
};

Available in k6 run command

--no-usage-reportorK6_NO_USAGE_REPORT

Don't send anonymous stats to the developers

Default: false

$ k6 run --no-usage-report ~/script.js

Available in k6 run command

--no-thresholdsorK6_NO_THRESHOLDS

Don't run thresholds

Default: false

$ k6 run --no-thresholds ~/script.js

Available in k6 run command

maxRedirectsor--max-redirects valueorK6_MAX_REDIRECTS

The maximum number of HTTP redirects that k6 will follow before giving up on a request and erroring out.

Default: 10

Examples

export let options = {
maxRedirects: 10
};

Available in k6 run and k6 cloud commands

batchor--batchorK6_BATCH

The maximum number of simultaneous/parallel connections in total that an http.batch() call in a VU can make.

Default: 10

Example

export let options = {
batch: 15
};

If you have a batch() call that you've given 20 URLs to and --batch is set to 15, then the VU will make 15 requests right away in parallel and queue the rest, executing them as soon as a previous request is done and a slot opens.

Available in k6 run and k6 cloud commands

batchPerHostor--batch-per-hostorK6_BATCH_PER_HOST

The maximum number of simultaneous/parallel connections per host that an http.batch() call in a VU can make.

Default: No Limit

Example

export let options = {
batchPerHost: 10
};

This option is similar to --batch, only it restricts requests based on the destination host.

A boolean, true or false, specifying whether k6 should reuse TCP connections between iterations of a VU

Default: false

Examples

export let options = {
noVUConnectionReuse: true
};

Available in k6 run and k6 cloud commands

noUsageReportor--no-usage-reportorK6_NO_USAGE_REPORT

A boolean, true or false. By default, k6 sends a usage report each time it is run, so that we can track how often people use it. If this option is set to true, no usage report will be made. To learn more, have a look at the Usage reports documentation.

Default: false

Examples

export let options = {
noUsageReport: true
};

Available in k6 run commands

pausedor--paused or -porK6_PAUSED

A boolean, true or false, specifying whether the test should start in a paused state. To resume a paused state you'd use the k6 resume command.

Default: false

Examples

export let options = {
paused: true
};

Available in k6 run and k6 cloud commands

rpsor--rpsorK6_RPS

The maximum number of requests to make per second, in total across all VUs.

Default: 0 (unlimited)

Examples

export let options = {
rps: 500
};

Available in k6 run and k6 cloud commands

stagesor--stage DURATION:TARGETor-s DURATION:TARGETorK6_STAGES

A list of VU { target: ..., duration: ... } objects that specify the target number of VUs to ramp up or down to for a specific period.

Default: based on vus and duration

ExamplesThe following config would have k6 ramping up from 1 to 10 VUs for 3 minutes, then staying flat at 10 VUs for 5 minutes, then ramping up from 10 to 35 VUs over the next 10 minutes before finally ramping down to 0 VUs for another 3 minutes.

Specify tags that should be set test wide across all metrics. If a tag with the same name has been specified on a request, check or custom metrics it will have precedence over a test wide tag.

Default: null

Examples

export let options = {
tags: {
"name": "value"
}
};

Available in k6 run and k6 cloud commands

--include-system-env-vars

Pass the real system environment variables to the runtime

Default: true for k6 run, but false for all other commands to prevent inadvertent sensitive data leaks.

$ k6 run --include-system-env-vars ~/script.js

Available in k6 run and k6 cloud commands

--e or --env VAR=value

Add/override environment variable with VAR=value

$ k6 run -eFOO=bar ~/script.js

Available in k6 run and k6 cloud commands

-o or --out

Specify the results output

k6 run --outinfluxdb=http://localhost:8086/k6 script.js

Please go to Results ouput for more information on all output plugins available and how to configure them.

Since version 0.21, this option can be specified multiple times.

Available in k6 run command

thresholds

A collection of threshold specifications to configure under what condition(s) a test is considered successful or not, when it has passed or failed, based on metric data. To learn more, have a look at the Thresholds documentation.

String specifying the user-agent string to use in User-Agent headers when sending HTTP requests.

Default: "k6/0.20 (https://k6.io/)" (depending on the version you're using).

Examples

export let options = {
userAgent: "MyK6UserAgentString/1.0"
};

Available in k6 run and k6 cloud commands

httpDebugor--http-debugorK6_HTTP_DEBUG

Log all HTTP requests and responses.

Excludes body by default, to include body use '--http-debug=full'

export let options = {
httpDebug: "full"
};

Available in k6 run and k6 cloud commands

vusor--vus value or -u valueorK6_VUS

A number specifying the number of VUs to run concurrently. If you'd like more control look at the stages option above.

Default: 1

Examples

export let options = {
vus: 10
};

Available in k6 run and k6 cloud commands

vusMaxor--max value or -m valueorK6_VUS_MAX

A number specifying max number of virtual users, if more than vus. This option is typically used when the intent is to dynamically scale number of VUs up and down during the test using the k6 scale command. Since instantiating a VU is an expensive operation in k6 this options is used to preallocate vusMax number of VUs.

Default: 0

Examples

export let options = {
vusMax: 10
};

Available in k6 run and k6 cloud commands

systemTagsor--system-tagsorK6_SYSTEM_TAGS

Specify which System Tags will be in the collected metrics. Some collectors like the cloud one may require that certain system tags be used.

You can specify the tags as an array from the JS scripts or as a comma-separated list via the CLI.

Specify how long the setup() function is allow to run before it's terminated and the test fails.

Default: 10s

teardownTimeoutorK6_TEARDOWN_TIMEOUT

Specify how long the teardown() function is allow to run before it's terminated and the test fails.

Default: 10s

--config config.json or -c config.json

Specify the config file in JSON format to read the options values. If the config file is not specified, k6 will look for config.json in the loadimpact/k6 directory inside the regular directory for configuration files on the operating system.

For example in Linux/BSDs, it will look for config.json inside ${HOME}/.config/loadimpact/k6

Specify if response bodies should be discarded by changing the default value of responseType to none for all http requests.

Highly recommended to be set to true and then only for the requests where the response body is actually needed for scripting to set responseType to text or binary. Lessens the amount of memory required and the amount of GC - reducing the load on the testing machine, and probably producing more reliable test results.

Specifies the minimal duration for every single execution (i.e. iteration) of the default function should be. Any iterations that are shorter than it will cause that VU to sleep for the remainder of the time until the specified minimal duration is reached.