Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 36 ยท Scenarios and Executors

VU-Based Executors

Configure the four VU-based k6 executors, shared-iterations, per-vu-iterations, constant-vus and ramping-vus, with their options, differences and when each one fits.

Four executors describe load in terms of virtual users: you choose how many VUs there are and either how long they run or how many iterations they execute. They all belong to the closed workload model from the previous lesson: a VU begins a new iteration only after finishing the last one. They are the right choice when you want to reason about concurrent users rather than request rates.

shared-iterations

A fixed number of iterations is shared between all VUs. k6 stops when the total is reached; faster VUs simply run more of them.

JavaScript
scenarios: {
  smoke: {
    executor: 'shared-iterations',
    vus: 10,
    iterations: 200,
    maxDuration: '5m', // safety limit (default 10m)
  },
},

Use it when the amount of work matters: running a data-import script exactly 500 times, or a debugging run (vus: 1, iterations: 1). If the work does not finish within maxDuration, k6 stops the scenario anyway.

per-vu-iterations

Each VU runs exactly N iterations. The total is vus * iterations.

JavaScript
scenarios: {
  onboarding: {
    executor: 'per-vu-iterations',
    vus: 25,
    iterations: 3,
    maxDuration: '10m',
  },
},

Slow VUs take longer, but nobody does fewer than N. Choose it when every virtual user must go through the same sequence, for example 25 simulated people each completing the signup flow three times, or when you pair each VU with a distinct data row.

constant-vus

A fixed number of VUs runs for a fixed time. This is the executor behind vus plus duration.

JavaScript
scenarios: {
  steady: {
    executor: 'constant-vus',
    vus: 50,
    duration: '10m',
  },
},

It is the standard average-load plateau. The number of iterations is whatever the VUs manage in the time.

ramping-vus

The number of VUs follows a list of stages, the same shape as the top-level stages option, with extra control:

JavaScript
scenarios: {
  stress: {
    executor: 'ramping-vus',
    startVUs: 0,
    stages: [
      { duration: '2m', target: 50 },
      { duration: '5m', target: 50 },
      { duration: '2m', target: 150 },
      { duration: '5m', target: 150 },
      { duration: '2m', target: 0 },
    ],
    gracefulRampDown: '30s',
  },
},
  • startVUs is the initial VU count.
  • gracefulRampDown lets a VU being removed finish its current iteration (30 s default) instead of being interrupted.
  • Targets can go up and down, so you can model daily patterns.

Side by side

Executor Fixed Variable Stops when
shared-iterations VUs, total iterations which VU does how many all iterations done (or maxDuration)
per-vu-iterations VUs, iterations per VU total time every VU finished (or maxDuration)
constant-vus VUs, duration total iterations duration ends
ramping-vus stages VUs last stage ends
flowchart LR
  Q{"What is fixed?"} -->|"total amount of work"| S["shared-iterations"]
  Q -->|"work per user"| P["per-vu-iterations"]
  Q -->|"users and time"| C["constant-vus"]
  Q -->|"a user curve over time"| R["ramping-vus"]

Seeing the differences

The program below is not k6. It reimplements the iteration-counting logic of the three duration-free behaviours with workers whose speed differs (VU 0 is fast, others slow), and prints who did how much. The speeds are fixed delays, so the totals are deterministic.

Node.js Stand-in: shared versus per-VU iterations

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.

Shared-iterations always totals 12 but lets the fast VU do the lion's share; per-VU always gives exactly 4 each (total 12 as well, but by design, not by coincidence); constant-vus has no fixed total at all.

maxDuration and the "stuck test" problem

Iteration-based executors have no natural end if iterations hang. Always set maxDuration to a value you consider reasonable. When it is hit, k6 interrupts the scenario and the iterations that did not run are reported as interrupted. A constant-vus test ends reliably on its own, which is part of why it is the default choice.

Combining with thresholds and stages in practice

A common recipe is: a shared-iterations smoke scenario that runs first with startTime: '0s', followed by a ramping-vus scenario with startTime: '1m'. Running two scenarios in one script is covered in Multiple Scenarios and exec.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. With shared-iterations, vus: 10 and iterations: 100, how many iterations run in total?

    The iterations are a shared pool. The total is exactly 100 unless maxDuration interrupts the scenario.
  2. 2. Which executor guarantees each VU runs the same number of iterations?

    per-vu-iterations gives every VU exactly N iterations.
  3. 3. What is gracefulRampDown for?

    Instead of cutting a VU off mid-iteration when the target falls, k6 waits up to gracefulRampDown.
  4. 4. Which executor matches the shorthand options vus: 20, duration: '5m'?

    vus plus duration create an implicit constant-vus scenario.

Summary

  • shared-iterations: fixed total of iterations shared by VUs. per-vu-iterations: N each.
  • constant-vus: fixed VUs for a duration. ramping-vus: VU count follows stages.
  • All are closed-model executors; request rate depends on response time.
  • Set maxDuration on iteration-based executors; use gracefulRampDown to avoid cutting iterations.

Next: Arrival-Rate Executors