Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 36 ยท Scenarios and Executors

Scenarios Overview

Learn what k6 scenarios are, how executors model traffic, the closed versus open workload models, the scenario options every executor shares, and when to leave plain vus and duration.

So far you shaped load with vus, duration and stages. Those options are convenient, but they secretly describe a single traffic pattern. Real systems receive several kinds of traffic at once: browsers reading pages, mobile apps calling an API, a nightly batch job. Scenarios let one test describe all of them, each with its own load model, its own timing and its own function to run. They are the most powerful part of k6's configuration.

What a scenario is

A scenario is a named entry in options.scenarios. It has an executor, which says how the load is generated, plus executor-specific settings, plus a few shared ones.

JavaScript
export const options = {
  scenarios: {
    browse: {
      executor: 'constant-vus',
      vus: 20,
      duration: '5m',
    },
  },
};

That is exactly what vus: 20, duration: '5m' produces behind the scenes: k6 builds an implicit scenario called default. You can see it with k6 inspect. Writing it explicitly unlocks everything else.

The seven executors

flowchart TB
  E["Executors"] --> A["Closed model<br/>(fixed number of VUs)"]
  E --> B["Open model<br/>(fixed arrival rate)"]
  A --> A1["shared-iterations"]
  A --> A2["per-vu-iterations"]
  A --> A3["constant-vus"]
  A --> A4["ramping-vus"]
  B --> B1["constant-arrival-rate"]
  B --> B2["ramping-arrival-rate"]
  E --> C["externally-controlled"]
Executor Describes Typical use
shared-iterations A fixed total of iterations split among VUs Run a script exactly N times
per-vu-iterations Each VU runs exactly N iterations Each user does the same journey once
constant-vus A fixed number of VUs for a duration Steady concurrent users
ramping-vus VU count that changes over stages Ramps, stress and soak tests
constant-arrival-rate A fixed number of iterations per time unit "50 requests per second"
ramping-arrival-rate Arrival rate that changes over stages Spikes and breakpoint tests
externally-controlled VUs adjusted live via the REST API Interactive experiments

The next two lessons cover the VU-based and arrival-rate executors in detail.

Closed versus open workload models

This distinction decides what your results mean.

Closed model (VU-based). There is a fixed population of users. A user starts a new iteration only after the last one finishes. If the server slows down, users take longer, so fewer requests arrive. Load falls exactly when the system struggles, which can hide problems. It fits systems with a limited number of users, like an internal tool with 200 employees.

Open model (arrival rate). New iterations start at a fixed rate no matter what, like visitors arriving at a public website. If the server slows down, requests pile up and the number of concurrent iterations (VUs) grows. This exposes overload honestly. It fits public websites and APIs.

A load test that uses VUs against a public service often under-reports problems because of the closed model's self-throttling. Choose the model that matches your real traffic.

Options every scenario shares

JavaScript
scenarios: {
  checkout: {
    executor: 'constant-vus',
    vus: 10,
    duration: '2m',
    startTime: '30s',       // begin 30 s after the test starts
    gracefulStop: '10s',    // let iterations finish after the end
    exec: 'checkoutFlow',   // which exported function to run
    env: { PAYMENT: 'card' }, // scenario-specific env vars
    tags: { flow: 'checkout' }, // tags added to all its metrics
  },
},
  • startTime delays a scenario, so you can run scenarios in sequence or overlap them.
  • exec names the exported function to run instead of default (see Multiple Scenarios and exec).
  • env and tags let the same function behave differently per scenario and give per-scenario metrics: every data point automatically carries a scenario tag.
  • gracefulStop controls how long running iterations may finish when the scenario ends (default 30 s).

Scenarios run in parallel by default (each starts at its startTime, which defaults to 0). The test ends when the last scenario finishes.

Scenario-level thresholds

Because of the scenario tag, you can hold each scenario to its own standard:

JavaScript
thresholds: {
  'http_req_duration{scenario:browse}': ['p(95)<400'],
  'http_req_duration{scenario:checkout}': ['p(95)<1500'],
},

A stand-in executor comparison

The program below is not k6. It implements miniature versions of two executors against a local server whose latency grows with load, to show the difference between the closed and the open model. The closed model (4 VUs) can never have more than 4 requests in flight, while the open model starts a new request every 10 ms regardless of how long the previous ones take, so concurrency rises when the server is slow.

Node.js Stand-in: closed versus open workload models

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.

The server slows itself down as requests accumulate. In the closed model the 4 VUs politely wait; in the open model arrivals keep coming and the backlog grows. That is why overload tests use arrival-rate executors.

Choosing quickly

  • Debugging a script: shared-iterations with 1 VU and 1 iteration.
  • "N concurrent users for X minutes": constant-vus.
  • Ramp, stress, soak: ramping-vus.
  • "We expect 100 requests per second": constant-arrival-rate.
  • Spike or breakpoint: ramping-arrival-rate.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a k6 executor define?

    The executor is the traffic model: constant VUs, ramping VUs, a fixed arrival rate, and so on.
  2. 2. In the closed model, what happens when the server slows down?

    VUs only start an iteration after the previous one ends, so a slower server lowers the request rate.
  3. 3. Which scenario option delays its start relative to the test start?

    startTime offsets the scenario, letting you run scenarios in sequence or staggered.
  4. 4. What tag does k6 add to every data point from a scenario?

    The scenario tag lets you filter metrics and thresholds per scenario.

Summary

  • Scenarios describe independent traffic patterns, each with an executor, timing and function.
  • vus/duration/stages are shorthand for an implicit scenario.
  • Seven executors: shared-iterations, per-vu-iterations, constant-vus, ramping-vus, constant-arrival-rate, ramping-arrival-rate, externally-controlled.
  • Closed models (VUs) self-throttle; open models (arrival rate) keep arriving, which exposes overload.
  • Shared options: startTime, gracefulStop, exec, env, tags.

Next: VU-Based Executors