Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 36 ยท Concepts and Scripts

Options and Stages

Learn the k6 options object, vus, duration, iterations, stages, gracefulStop, setup timeouts, user agent and more, and how stages ramp virtual users up and down.

The options object is the control panel of a k6 test. It says how many users, for how long, which pass/fail rules apply and how the engine behaves. You can set it in the script, with environment variables, or with command-line flags (flags win). This lesson covers the options you will use in almost every test, with special attention to stages, the easiest way to shape traffic over time.

The most common options

JavaScript
export const options = {
  vus: 20,
  duration: '2m',
  thresholds: { http_req_failed: ['rate<0.01'] },
  noConnectionReuse: false,
  userAgent: 'MyLoadTest/1.0',
  insecureSkipTLSVerify: false,
  setupTimeout: '60s',
  teardownTimeout: '60s',
  gracefulStop: '30s',
};
Option Meaning
vus Number of virtual users (constant load).
duration How long to run; accepts 30s, 5m, 1h30m.
iterations Total iterations, shared across VUs.
stages A list of ramp steps (see below).
thresholds Pass/fail rules on metrics (Thresholds).
scenarios Explicit traffic models (Scenarios).
gracefulStop Time to let running iterations finish when the test ends (default 30s).
noConnectionReuse Open a new connection for every request.
userAgent Value of the User-Agent header.
insecureSkipTLSVerify Accept invalid certificates (staging only).
tags Tags added to every metric (Groups and Tags).
summaryTrendStats Which statistics the summary prints for trend metrics.

Durations are strings with units (ms, s, m, h). Passing a bare number is not accepted for most duration options, so duration: 30 is an error; write '30s'.

Run k6 inspect script.js to see the options k6 resolved, including the implicit scenario it built from vus and duration. It is a quick way to find out why a test is not doing what you think.

Stages: ramping load

A stage is a step with a duration and a target. k6 moves the number of VUs linearly from where it is to the target over the duration. Stages run one after another.

JavaScript
export const options = {
  stages: [
    { duration: '30s', target: 20 }, // ramp from 0 to 20 VUs over 30 s
    { duration: '1m',  target: 20 }, // stay at 20
    { duration: '20s', target: 0 },  // ramp down
  ],
};

Starting from 0, the VU count after 15 seconds is 10, after 30 seconds it reaches 20, holds for a minute, then falls to 0. Ramps are important because a system that is fine at 20 users may break while the first 20 arrive in one second; a gentle ramp also gives autoscalers and caches time to warm up, so your measurements are fairer.

Stages work together with two more options:

  • startVUs sets the initial number of VUs (default 1).
  • gracefulRampDown (default 30s) lets a VU finish its current iteration when the target drops, instead of being cut off mid-request.

Behind the scenes, stages is shorthand for the ramping-vus executor, which you will meet in VU-Based Executors. Use stages for quick tests; use scenarios when you need several traffic patterns at once.

Visualising a stages list

The program below is not k6; it is a Node.js stand-in that applies the same linear-interpolation rule to a worker pool. It runs a list of short stages against a local server, adjusts the number of concurrent workers every 50 ms tick, and reports the peak concurrency it reached. The load is real (concurrent HTTP calls), the timing is compressed.

Node.js Stand-in: ramp workers up and down with stages

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Real k6 does not use polling like this, but the model is the same: a target curve, and VUs started or stopped to follow it.

Setting options per environment

Hard-coding numbers makes a script rigid. A good habit is to define a default and let each run override it:

JavaScript
export const options = {
  vus: Number(__ENV.VUS || 5),
  duration: __ENV.DURATION || '30s',
};

Then k6 run -e VUS=50 -e DURATION=5m script.js changes the load without touching the file. For large projects, keep several option sets in one module and pick one with __ENV.PROFILE (see Test Data and Environment Variables).

You can also export options from a JSON file and pass it with --config options.json, or write them in the script with export const options. Remember the precedence: CLI flags, then environment variables (such as K6_VUS), then the script, then the defaults.

Common mistakes

  • Using vus and stages together: stages replace a constant vus; set startVUs if you need a non-zero beginning.
  • Forgetting a final ramp-down stage: the test ends abruptly and in-flight iterations are cut after the gracefulStop.
  • Making stages too short: a 5-second ramp to 1000 users is a spike, not a ramp.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does { duration: '1m', target: 50 } as a stage do?

    Stages interpolate linearly from the current VU count to the target across the stage's duration.
  2. 2. Which value is valid for the duration option?

    Durations are strings with a unit, such as '30s' or '5m'.
  3. 3. What does gracefulStop control?

    gracefulStop gives in-flight iterations time to complete (30s by default) rather than killing them abruptly.
  4. 4. Which tool shows the options k6 resolved from a script?

    k6 inspect prints the resolved options without running the test.

Summary

  • options configures load, rules and engine behaviour; flags beat env vars beat script beat defaults.
  • Durations are strings like '30s', '5m'.
  • stages ramp VUs linearly through a list of { duration, target } steps.
  • Always ramp down, and give ramps enough time to be realistic.
  • Parameterize options with __ENV so the same script serves smoke, load and stress runs.

Next: GET and POST Requests