Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 36 ยท Getting Started

Virtual Users and Iterations

Understand how k6 virtual users run iterations of your default function, how vus, duration and iterations interact, why VUs are isolated, and how to avoid common mistakes.

Two words appear in every k6 conversation: virtual user and iteration. Mixing them up leads to wrong load numbers, so it is worth getting them exact before you write bigger tests. A virtual user (VU) is a worker. An iteration is one complete run of your script's default function by a worker. A VU runs iteration after iteration until the test ends.

How the two fit together

Imagine 3 VUs and a function that makes one request and then sleeps for a second. Each VU starts the function, finishes it, and immediately starts it again. After 10 seconds each VU has completed about 10 iterations, so the whole test has about 30 iterations and 30 requests.

flowchart TB
  subgraph VU1["VU 1"]
    direction LR
    a1["iteration 1"] --> a2["iteration 2"] --> a3["iteration 3"]
  end
  subgraph VU2["VU 2"]
    direction LR
    b1["iteration 1"] --> b2["iteration 2"] --> b3["iteration 3"]
  end

Each VU runs its own sequence of iterations; VUs run in parallel.

The number of requests per second you generate therefore depends on two things: how many VUs you have and how long each iteration takes. If one iteration takes 2 seconds (a 1-second request plus a 1-second sleep), each VU produces 0.5 iterations per second.

The three simple options

For simple tests, three options control the amount of work:

JavaScript
export const options = {
  vus: 10,         // how many virtual users
  duration: '30s', // run each VU's loop for this long
  // iterations: 100, // OR: run this many iterations in total
};
  • vus + duration: each VU loops for the time given. The total number of iterations depends on how fast they are.
  • vus + iterations: the iterations are a shared pool. k6 stops when the total reaches iterations, whichever VU ran them. Fast VUs do more of them.
  • Only iterations (with the default 1 VU) is the way to run a script a fixed number of times for debugging.

These options secretly create a single, implicit scenario. When you need more control, such as each VU doing exactly 5 iterations, you use explicit scenarios and executors.

VUs are isolated

Every VU gets its own copy of the JavaScript runtime. Variables declared at the top of the script, outside the default function, exist once per VU. They are not shared between VUs, and one VU cannot see another's data.

JavaScript
let counter = 0; // one copy per VU

export default function () {
  counter += 1;
  console.log(`VU ${__VU}, my iteration ${__ITER}, counter ${counter}`);
}

k6 provides two built-in variables for this: __VU is the VU's number (starting at 1), and __ITER is the iteration count for that VU (starting at 0). Inside a scenario you can also use the exec module's scenario.iterationInTest for a number unique across the whole test.

Isolation has an important benefit: no locking and no race conditions in your scripts. Its cost is that you cannot count "total iterations so far" with a variable; use a metric instead (see Custom Metrics).

VU state persists between iterations

A VU is reused, not recreated. After an iteration finishes, the same VU starts the next iteration with the same global state, the same cookie jar and the same open connections. That is what makes a VU behave like a persistent browser tab or app session. If you want each iteration to look like a fresh visitor, you must clear things yourself (for example with http.cookieJar().clear(url)).

Throughput is a result, not a setting

With VUs, the request rate is an outcome: when the server slows down, each iteration takes longer, so the VUs send fewer requests per second. The load drops exactly when the system struggles. This effect is called a closed model, and it is sometimes unwanted. If you need a fixed request rate no matter how slow the server gets, use an arrival-rate executor (the open model), covered in Arrival-Rate Executors.

A stand-in that shows the arithmetic

This is not k6. It runs 4 "VUs" for a fixed wall time against a local server that takes about 20 ms to respond, with a 20 ms pause between iterations, and shows that iterations per VU and total are linked to the iteration length. The exact counts vary a little, so the program prints properties that are always true.

Node.js Stand-in: VUs, iterations and isolated state

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.

An iteration of about 40 ms means each VU manages roughly 10 iterations in 400 ms. Double the VUs and you double the total; double the sleep time and you halve it.

The same idea as a shared pool

The second stand-in models vus: 4, iterations: 20: the 20 iterations are a pool that any VU can take, so the split between VUs depends on speed, but the total is always exactly 20.

Node.js Stand-in: a shared pool of 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.

Practical guidelines

  • Start with few VUs and raise them; a script that fails with 1 VU will fail loudly with 500.
  • Always include a sleep (think time) unless you deliberately want maximum pressure; without it each VU hammers the server as fast as it can. See Think Time and Pacing.
  • VUs cost memory (a few MB each, more with big data or bundled libraries), so plan the load generator's size.
  • Use __VU and __ITER to pick different test data per VU and iteration (see Test Data and Environment Variables).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is an iteration in k6?

    An iteration is one execution of the default function. It can contain many requests.
  2. 2. With vus: 5 and iterations: 100, how many iterations run in total?

    The iterations value is a shared pool. Together the VUs run exactly 100 iterations.
  3. 3. A variable declared at the top of the script, outside the default function, is:

    Each VU has an isolated JavaScript runtime, so top-level variables are per VU and persist across that VU's iterations.
  4. 4. What happens to request rate when the server gets slower, with a fixed number of VUs?

    VUs wait for responses, so a slower server means fewer iterations per second. This is the closed model.

Summary

  • A VU is a parallel worker; an iteration is one run of the default function.
  • vus with duration loops for a time; vus with iterations shares a pool.
  • Every VU has its own runtime: top-level variables are per VU and persist between its iterations.
  • __VU and __ITER identify the VU and its own iteration count.
  • Request rate with VUs depends on response time; use arrival-rate executors for a fixed rate.

Next: Reading the End-of-Test Summary