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.
For example, you can define the duration in 4 different ways:
- set the
duration: "10s"
option in the config file - set the
duration: "10s"
option in the script - define
K6_DURATION
as an environment variable - use the command-line flag
-d 10s
The following JS snippet shows how to specify options in the script:
import http from "k6/http";
export let options = {
hosts: {
"test.loadimpact.com": "1.2.3.4"
},
stages: [
{ duration: "1m", target: 10 },
{ duration: "1m", target: 20 },
{ duration: "1m", target: 0 }
],
thresholds: {
http_req_duration: ["avg<100", "p(95)<200"]
},
noConnectionReuse: true,
userAgent: "MyK6UserAgentString/1.0"
};
export default function() {
http.get("http://test.loadimpact.com/");
}
You can also set the same options via config file:
{
"hosts": {
"test.loadimpact.com": "1.2.3.4"
},
"stages": [
{ "duration": "1m", "target": 10 },
{ "duration": "1m", "target": 30 },
{ "duration": "1m", "target": 0 }
],
"thresholds": {
"http_req_duration": ["avg<100", "p(95)<200"]
},
"noConnectionReuse": true,
"userAgent": "MyK6UserAgentString/1.0"
}
Or set some of the previous options via environment variables and command-line flags:
$ K6_NO_CONNECTION_REUSE=true K6_USER_AGENT="MyK6UserAgentString/1.0" k6 run ~/script.js
$ k6 run ---no-connection-reuse --user-agent "MyK6UserAgentString/1.0" ~/script.js
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.
duration
or--duration value
or -d value
orK6_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
Examples
This 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.
export let options = {
ext: {
loadimpact: {
name: "My test name"
}
}
};
hosts
An object with overrides to DNS resolution, similar to what you can do with /etc/hosts
on Linux/Unix or C:\Windows\System32\drivers\etc\hosts
on Windows.
Default: null
Examples:
Set up overrides so all requests to test.loadimpact.com
will be routed to 1.2.3.4
(HTTP Host
header will still be set to "test.loadimpact.com").
export let options = {
hosts: {
"test.loadimpact.com": "1.2.3.4"
}
};
insecureSkipTLSVerify
or--insecure-skip-tls-verify
orK6_INSECURE_SKIP_TLS_VERIFY
A boolean, true or false. When this option is enabled (set to true), all of the verifications that would otherwise be done to establish trust in a server provided TLS certificate will be ignored.
Default: false
Examples
export let options = {
insecureSkipTLSVerify: true
};
Available in k6 run
and k6 cloud
commands
iterations
or--iterations value
or -i value
orK6_ITERATIONS
A number specifying a fixed number of iterations to execute of the script, as opposed to specifying a duration of time during which the script would run in a loop.
Note: The number of iterations is split between all VUs.
Default: 1
Examples
export let options = {
iterations: 10
};
export let options = {
vus: 10,
iterations: 100
};
In this example, 10 VUs will run 10 iterations each.
Available in k6 run
command (not supported yet for cloud executed tests using k6 cloud
command)
linger
or--linger
or -l
orK6_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-report
orK6_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-thresholds
orK6_NO_THRESHOLDS
Don't run thresholds
Default: false
$ k6 run --no-thresholds ~/script.js
Available in k6 run
command
maxRedirects
or--max-redirects value
orK6_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
batch
or--batch
orK6_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
batchPerHost
or--batch-per-host
orK6_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.
Available in k6 run
and k6 cloud
commands
noConnectionReuse
or--no-connection-reuse
orK6_NO_CONNECTION_REUSE
A boolean, true or false, specifying whether k6 should disable keep-alive connections
Default: false
Examples
export let options = {
noConnectionReuse: true
};
Available in k6 run
and k6 cloud
commands
noVUConnectionReuse
or--no-vu-connection-reuse
orK6_NO_VU_CONNECTION_REUSE
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
noUsageReport
or--no-usage-report
orK6_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
paused
or--paused
or -p
orK6_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
rps
or--rps
orK6_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
stages
or--stage DURATION:TARGET
or-s DURATION:TARGET
orK6_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
Examples
The 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.
export let options = {
stages: [
{ duration: "3m", target: 10 },
{ duration: "5m", target: 10 },
{ duration: "10m", target: 35 },
{ duration: "3m", target: 0 },
]
};
You can also set stages using command-line flag or environment variables. To do that, you need to use the following pattern:
duration:target,duration:target...
$ k6 run --stage 5s:10,5m:20,10s:5 ~/script.js
$ K6_STAGES="5s:10,5m:20,10s:5" k6 run ~/script.js
Available in k6 run
and k6 cloud
commands
tags
or--tag NAME:VALUE
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 -e FOO=bar ~/script.js
Available in k6 run
and k6 cloud
commands
-o
or --out
Specify the results output
k6 run --out influxdb=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.
Default: null
Examples
export let options = {
thresholds: {
http_req_duration:
["avg<100", "p(95)<200"],
"http_req_connecting{cdnAsset:true}":
["p(95)<100"]
}
};
Available in k6 run
commands
throw
or--throw
or -w
orK6_THROW
A boolean, true or false, specifying whether to throw errors on failed HTTP requests or not.
Default: false
Examples
export let options = {
throw: true
};
Available in k6 run
and k6 cloud
commands
blacklistIPs
or--blacklist-ip
orK6_BLACKLIST_IPS
Blacklist an IP ranges from being called
Examples
export let options = {
blacklistIPs: ["10.0.0.0/8"]
};
Available in k6 run
and k6 cloud
commands
summaryTrendStats
or--summary-trend-stats
orK6_SUMMARY_TREND_STATS
Define stats for trend metrics (response times), one or more as 'avg,p(95),...'
Examples
export let options = {
summaryTrendStats: ["avg","p(95)"]
};
Available in k6 run
and k6 cloud
commands
tlsAuth
A list of TLS client certificate configuration objects. Each object needs to specify for which host(s)/domain(s) the given client certificate is valid for.
Default: null
Examples
export let options = {
tlsAuth: [
{ domains: ["example.com"],
cert: open("mycert.pem"),
key: open("mycert-key.pem") }
]
};
tlsCipherSuites
A list of cipher suites allowed to be used by in SSL/TLS interactions with a server. For a full listing of available ciphers go here.
Default: null (meaning all supported SSL/TLS cipher suites are allowed)
Examples
export let options = {
tlsCipherSuites: [
"TLS_RSA_WITH_RC4_128_SHA",
"TLS_RSA_WITH_AES_128_GCM_SHA256",
]
};
tlsVersion
Either a string representing the only SSL/TLS version allowed to be used in interactions with a server, or an object specifying the "min" and "max" versions allowed to be used.
Default: null (meaning all supported SSL/TLS versions are allowed)
Examples
Specifying a specific version to allow:
export let options = {
tlsVersion: "tls1.2"
};
Specifying a min and max version to allow:
export let options = {
tlsVersion: {
min: "ssl3.0",
max: "tls1.2"
}
};
userAgent
or--user-agent
orK6_USER_AGENT
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
httpDebug
or--http-debug
orK6_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
vus
or--vus value
or -u value
orK6_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
vusMax
or--max value
or -m value
orK6_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
systemTags
or--system-tags
orK6_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.
Default: proto
, subproto
, status
, method
, url
, name
, group
, check
, error
, tls_version
Available in k6 run
and k6 cloud
commands
setupTimeout
orK6_SETUP_TIMEOUT
Specify how long the setup()
function is allow to run before it's terminated and the test fails.
Default: 10s
teardownTimeout
orK6_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
Available in k6 run
and k6 cloud
commands
discardResponseBodies
or--discard-response-bodies
orK6_DISCARD_RESPONSE_BODIES
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.
Default: false