Options

Using 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.

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.k6.io': '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.k6.io/');
}

You can also set the same options through a config file:

{
  "hosts": {
    "test.k6.io": "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

Below, you'll find details on all 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.

TLS Cipher Suites

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 - Allow all suites

Example

export let options = {
  tlsCipherSuites: [
    'TLS_RSA_WITH_RC4_128_SHA',
    'TLS_RSA_WITH_AES_128_GCM_SHA256',
  ],
};

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. Available in k6 run and k6 cloud commands.

Default

null

Example

export let options = {
  duration: '3m',
};

Extension Options

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

Default

null

Example

This is an example of how to specify the test name (test runs/executions with the same name will be logically grouped for trending and comparison) when streaming results to k6 Cloud 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. For instance, you could set up an override which routes all requests for test.k6.io to 1.2.3.4.

⚠️ Keep in mind!

This does not modify the actual HTTP Host header, but rather where it will be routed.

Default

null

Example

export let options = {
  hosts: {
    'test.k6.io': '1.2.3.4',
  },
};

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. Available in k6 run command (not yet supported for cloud executed tests using the k6 cloud command).

Default

1

Example

export let options = {
  iterations: 10,
};

Or, to run 10 VUs 10 times each:

export let options = {
  vus: 10,
  iterations: 100,
};

Linger

A boolean, true or false, specifying whether the k6 process should linger around after test run completion. Available in the k6 run command.

Default

false

Example

export let options = {
  linger: true,
};

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. Available in k6 run commands.

Default

null

Example

export let options = {
  thresholds: {
    http_req_duration: ['avg<100', 'p(95)<200'],
    'http_req_connecting{cdnAsset:true}': ['p(95)<100'],
  },
};

No Thresholds

Disables threshold execution. Available in the k6 run command.

Default

false

Example

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

Max Redirects

The maximum number of HTTP redirects that k6 will follow before giving up on a request and erroring out. Available in both the k6 run and the k6 cloud commands.

Default

10

Example

export let options = {
  maxRedirects: 10,
};

Batch

The maximum number of simultaneous/parallel connections in total that an http.batch() call in a VU can make. 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 both the k6 run and the k6 cloud commands

Default

10

Example

export let options = {
  batch: 15,
};

No Connection Reuse

A boolean, true or false, specifying whether k6 should disable keep-alive connections. Available in k6 run and k6 cloud commands.

Default

false

Example

export let options = {
  noConnectionReuse: true,
};

No VU Connection Reuse

A boolean, true or false, specifying whether k6 should reuse TCP connections between iterations of a VU. Available in k6 run and k6 cloud commands.

Default

false

Example

export let options = {
  noVUConnectionReuse: true,
};

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. Available in k6 run commands.

Default

false

Example

export let options = {
  noUsageReport: true,
};

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. Available in k6 run and k6 cloud commands.

Default

false

Example

export let options = {
  paused: true,
};

RPS

The maximum number of requests to make per second, in total across all VUs. Available in k6 run and k6 cloud commands.

Default

0 (unlimited)

Example

export let options = {
  rps: 500,
};

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. Available in k6 run and k6 cloud commands,

Default

Based on vus and duration.

Example

// 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 },
  ],
};

$ k6 run --stage 5s:10,5m:20,10s:5 ~/script.js

# or...

$ K6_STAGES="5s:10,5m:20,10s:5" k6 run ~/script.js

Summary export

New in v0.26.0

Output the end-of-test summary report to a JSON file that includes data for all test metrics, checks and thresholds. This is useful to get the aggregated test results in a machine-readable format, for integration with dashboards, external alerts, etc.

Available in the k6 run command.

Default

null

Example

$ k6 run --summary-export export.json ~/script.js

# or...

$ K6_SUMMARY_EXPORT="export.json" k6 run ~/script.js

See an example file on the Results Output page.

Tags

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. Available in k6 run and k6 cloud commands.

Default

null

Example

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

Include System Env Vars

Pass the real system environment variables to the runtime. Available in k6 run and k6 cloud commands.

Default

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

Example

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

Supply Env Var

Add/override environment variable with VAR=value. Available in k6 run and k6 cloud commands.

Default

Example

$ k6 run -e FOO=bar ~/script.js

Results Output

Specify the results output. 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.

Default

null

Example

$ k6 run --out influxdb=http://localhost:8086/k6 script.js

Throw

A boolean, true or false, specifying whether to throw errors on failed HTTP requests or not. Available in k6 run and k6 cloud commands.

Default

false

Example

export let options = {
  throw: true,
};

Blacklist IPs

Blacklist IP ranges from being called. Available in k6 run and k6 cloud commands.

Default

null

Example

export let options = {
  blacklistIPs: ['10.0.0.0/8'],
};

Summary Trend Stats

Define stats for trend metrics (response times), one or more as avg,p(95),.... Available in k6 run and k6 cloud commands

Default

null

Example

export let options = {
  summaryTrendStats: ['avg', 'p(95)'],
};

TLS Authentication

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

Example

export let options = {
  tlsAuth: [
    {
      domains: ['example.com'],
      cert: open('mycert.pem'),
      key: open('mycert-key.pem'),
    },
  ],
};

Skip TLS Verification

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. Available in k6 run and k6 cloud commands

Default

false

Example

export let options = {
  insecureSkipTLSVerify: true,
};

TLS Version

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 - Allow all versions

Example:

export let options = {
  tlsVersion: 'tls1.2',
};

// or...

export let options = {
  tlsVersion: {
    min: 'ssl3.0',
    max: 'tls1.2',
  },
};

User Agent

A string specifying the user-agent string to use in User-Agent headers when sending HTTP requests. Available in k6 run and k6 cloud commands

Default

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

Example

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

HTTP Debug

Log all HTTP requests and responses. Excludes body by default, to include body use '--http-debug=full'. Available in k6 run and k6 cloud commands.

Default

false

Example

export let options = {
  httpDebug: 'full',
};

VUs

A number specifying the number of VUs to run concurrently. If you'd like more control look at the stages option. Available in k6 run and k6 cloud commands.

Default

1

Example

export let options = {
  vus: 10,
};

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 the amount of VUs up and down during the test using the k6 scale command. Since instantiating a VU is an expensive operation in k6 this option is used to preallocate vusMax number of VUs. Available in k6 run and k6 cloud commands.

Default

0

Example

export let options = {
  vusMax: 10,
};

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. Available in k6 run and k6 cloud commands

Default

proto, subproto, status, method, url, name, group, check, error, tls_version

Example

export let options = {
  systemTags: ['status', 'method', 'url'],
};

Setup Timeout

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

Default

10s

Example

export let options = {
  setupTimeout: '30s',
};

Teardown Timeout

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

Default

10s

Example

export let options = {
  teardownTimeout: '30s',
};

Config

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

Default

null

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 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

Example

export let options = {
  discardResponseBodies: true,
};

Minimum Iteration Duration

Specifies the minimum 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 minimum duration is reached.

Default

0 (disabled)

Example

export let options = {
  minIterationDuration: '10s',
};

No Cookies Reset

This disables the default behavior of resetting the cookie jar after each VU iteration. If it's enabled, saved cookies will be persisted across VU iterations.

Default

false

Example

export let options = {
  noCookiesReset: true,
};