Skip to main content

​
Options reference

Options configure test-run behavior. Use options to define test tags, thresholds, user agents, the number of virtual users and iterations, and much more.

​
How to use options

You can set options in multiple places with different levels of precedence:
1

In the script

Use the export const options object to set default options in your script.
export const options = {
  vus: 10,
  duration: '30s',
};
2

Command-line flags

Override script options with CLI flags.
k6 run --vus 20 --duration 1m script.js
3

Environment variables

Use environment variables with the K6_ prefix.
K6_VUS=20 K6_DURATION=1m k6 run script.js

​
Order of precedence

When you set options in multiple places, k6 applies them in this order (highest to lowest precedence):
  1. Command-line flags
  2. Environment variables
  3. Script options
  4. Default values

​
Common options

​
Virtual users and duration

​
vus
integer
default:"1"
Number of virtual users to run concurrently.
export const options = {
  vus: 10,
};
​
duration
string
default:"null"
Total test duration. The test will run for this duration with the specified number of VUs.
export const options = {
  duration: '30s',
};
​
iterations
integer
default:"1"
Total number of iterations to execute across all VUs.
export const options = {
  iterations: 100,
};

​
Stages

​
stages
array
default:"[]"
Ramp VUs up or down during the test.
export const options = {
  stages: [
    { duration: '30s', target: 20 },
    { duration: '1m', target: 10 },
    { duration: '10s', target: 0 },
  ],
};

​
Thresholds

​
thresholds
object
default:"{}"
Pass/fail criteria for metrics.
export const options = {
  thresholds: {
    http_req_duration: ['p(95)<500'],
    http_req_failed: ['rate<0.01'],
  },
};

​
Scenarios

​
scenarios
object
default:"{}"
Advanced configuration for VU and iteration scheduling.
export const options = {
  scenarios: {
    contacts: {
      executor: 'constant-vus',
      vus: 10,
      duration: '30s',
    },
  },
};

​
Complete options list

Here’s the complete list of k6 options:

​
Execution options

  • vus - Number of virtual users
  • duration - Test duration
  • iterations - Total iterations
  • stages - VU ramping configuration
  • scenarios - Advanced scenario configuration
  • executionSegment - Segment of test to run
  • executionSegmentSequence - Sequence for segmentation

​
HTTP options

  • batch - Max parallel requests in batch
  • batchPerHost - Max parallel requests per host
  • httpDebug - HTTP request/response logging
  • insecureSkipTLSVerify - Skip TLS verification
  • tlsAuth - TLS client certificate configuration
  • tlsCipherSuites - TLS cipher suites
  • tlsVersion - Min/max TLS versions

​
Output options

  • noConnectionReuse - Disable keep-alive
  • userAgent - User-Agent header value
  • discardResponseBodies - Don’t save response bodies
  • rps - Max requests per second

​
Lifecycle options

  • setupTimeout - Setup function timeout
  • teardownTimeout - Teardown function timeout
  • maxRedirects - Max HTTP redirects

​
Tags

  • tags - Tags applied to all metrics
  • systemTags - System tags to collect

​
Console output

  • noVUConnectionReuse - Per-VU connection behavior
  • minIterationDuration - Minimum iteration duration
  • maxDuration - Maximum test duration

​
Examples

​
Load test with ramping

export const options = {
  stages: [
    { duration: '2m', target: 100 },
    { duration: '5m', target: 100 },
    { duration: '2m', target: 0 },
  ],
  thresholds: {
    http_req_duration: ['p(99)<1500'],
  },
};

​
Spike test

export const options = {
  stages: [
    { duration: '10s', target: 100 },
    { duration: '1m', target: 100 },
    { duration: '10s', target: 1400 },
    { duration: '3m', target: 1400 },
    { duration: '10s', target: 100 },
    { duration: '3m', target: 100 },
    { duration: '10s', target: 0 },
  ],
};

​
Using environment variables

export const options = {
  vus: __ENV.VUS || 10,
  duration: __ENV.DURATION || '30s',
};

Test lifecycle

Learn about the test execution lifecycle

Scenarios

Advanced VU and iteration scheduling

Thresholds

Set pass/fail criteria for your tests

Environment variables

Using environment variables in k6

Build docs developers (and LLMs) love

Get started for freeTalk to us