Concepts

Mon, 21 Sep 2026 15:16:28 +0000

Concepts

These topics explain the essential concepts of how scenarios and their executors work.

Different scenario configurations can affect many different aspects of your system, including the generated load, utilized resources, and emitted metrics. If you know a bit about how scenarios work, you’ll design better tests and interpret test results with more understanding.

On this page	Read about
Open and closed models	Different ways k6 can schedule VUs, their affects on test results, and how k6 implements the open model in its arrival-rate executors
Graceful Stop	A configurable period for iterations to finish or ramp down after the test reaches its scheduled duration
Arrival-rate VU allocation	How k6 allocates VUs in arrival-rate executors
Dropped iterations	Possible reasons k6 might drop a scheduled iteration

Executors

Mon, 21 Sep 2026 15:16:28 +0000

Executors

Executors control how k6 schedules VUs and iterations. The executor that you choose depends on the goals of your test and the type of traffic you want to model.

Define the executor in executor key of the scenario object. The value is the executor name separated by hyphens.

export const options = {
  scenarios: {
    arbitrary_scenario_name: {
      //Name of executor
      executor: 'ramping-vus',
      // more configuration here
    },
  },
};

All executors

The following table lists all k6 executors and links to their documentation.

Name	Value	Description
Shared iterations	`shared-iterations`	A fixed amount of iterations are shared between a number of VUs.
Per VU iterations	`per-vu-iterations`	Each VU executes an exact number of iterations.
Constant VUs	`constant-vus`	A fixed number of VUs execute as many iterations as possible for a specified amount of time.
Ramping VUs	`ramping-vus`	A variable number of VUs execute as many iterations as possible for a specified amount of time.
Constant Arrival Rate	`constant-arrival-rate`	A fixed number of iterations are executed in a specified period of time.
Ramping Arrival Rate	`ramping-arrival-rate`	A variable number of iterations are executed in a specified period of time.

Note
For any given scenario, you can’t guarantee that a specific VU can run a specific iteration.

With SharedArray and execution context variables, you can map a specific VU to a specific value in your test data. So the tenth VU could use the tenth item in your array (or the sixth iteration to the sixth item).

But, you cannot reliably map, for example, the tenth VU to the tenth iteration.

Advanced Examples

Mon, 21 Sep 2026 15:16:28 +0000

Advanced Examples

You can use multiple scenarios in one script, and these scenarios can be run in sequence or in parallel. Some ways that you can combine scenarios include the following:

Have different start times to sequence workloads
Add per-scenario tags and environment variables
Make scenario-specific thresholds.
Use multiple scenarios to run different test logic, so that VUs don’t run only the default function.

Combine scenarios

With the startTime property, you can configure your script to start some scenarios later than others. To sequence your scenarios, you can combine startTime with the duration options specific to the executor. (this is easiest to do with executors with set durations, like the arrival-rate executors).

This script has two scenarios, contacts and news, which run in sequence:

At the beginning of the test, k6 starts the contacts scenario. 5 VUs try to run as many iterations as possible for 5 seconds.
After 10 seconds, k6 starts the news scenario. 5 VUs each try to run 10 iterations in 20 seconds.

Along with startTime, duration, and maxDuration, note the different test logic for each scenario.

import http from 'k6/http';

export const options = {
  discardResponseBodies: true,
  scenarios: {
    contacts: {
      executor: 'constant-vus',
      exec: 'contacts',
      vus: 5,
      duration: '5s',
    },
    news: {
      executor: 'per-vu-iterations',
      exec: 'news',
      vus: 5,
      iterations: 10,
      startTime: '10s',
      maxDuration: '20s',
    },
  },
};

export function contacts() {
  http.get('https://test.k6.io/contacts.php', {
    tags: { my_custom_tag: 'contacts' },
  });
}

export function news() {
  http.get('https://test.k6.io/news.php', { tags: { my_custom_tag: 'news' } });
}

Use different environment variables and tags per scenario.

The previous example sets tags on individual HTTP request metrics. But, you can also set tags per scenario, which applies them to other taggable objects as well.

import http from 'k6/http';
import { fail } from 'k6';

export const options = {
  discardResponseBodies: true,
  scenarios: {
    contacts: {
      executor: 'constant-vus',
      exec: 'contacts',
      vus: 50,
      duration: '30s',
      tags: { my_custom_tag: 'contacts' },
      env: { MYVAR: 'contacts' },
    },
    news: {
      executor: 'per-vu-iterations',
      exec: 'news',
      vus: 50,
      iterations: 100,
      startTime: '30s',
      maxDuration: '1m',
      tags: { my_custom_tag: 'news' },
      env: { MYVAR: 'news' },
    },
  },
};

export function contacts() {
  if (__ENV.MYVAR != 'contacts') fail();
  http.get('https://test.k6.io/contacts.php');
}

export function news() {
  if (__ENV.MYVAR != 'news') fail();
  http.get('https://test.k6.io/news.php');
}

Note
By default, k6 applies a scenario tag to all metrics in each scenario, whose value is the scenario name. You can combine these tags with thresholds, or use them to simplify results filtering.

To disable scenario tags, use the --system-tags option.

Run multiple scenario functions, with different thresholds

You can also set different thresholds for different scenario functions. To do this:

Set scenario-specific tags
Set thresholds for these tags.

This test has 3 scenarios, each with different exec functions, tags and environment variables, and thresholds:

import http from 'k6/http';
import { sleep } from 'k6';

export const options = {
  scenarios: {
    my_web_test: {
      // some arbitrary scenario name
      executor: 'constant-vus',
      vus: 50,
      duration: '5m',
      gracefulStop: '0s', // do not wait for iterations to finish in the end
      tags: { test_type: 'website' }, // extra tags for the metrics generated by this scenario
      exec: 'webtest', // the function this scenario will execute
    },
    my_api_test_1: {
      executor: 'constant-arrival-rate',
      rate: 90,
      timeUnit: '1m', // 90 iterations per minute, i.e. 1.5 RPS
      duration: '5m',
      preAllocatedVUs: 10, // the size of the VU (i.e. worker) pool for this scenario
      tags: { test_type: 'api' }, // different extra metric tags for this scenario
      env: { MY_CROC_ID: '1' }, // and we can specify extra environment variables as well!
      exec: 'apitest', // this scenario is executing different code than the one above!
    },
    my_api_test_2: {
      executor: 'ramping-arrival-rate',
      startTime: '30s', // the ramping API test starts a little later
      startRate: 50,
      timeUnit: '1s', // we start at 50 iterations per second
      stages: [
        { target: 200, duration: '30s' }, // go from 50 to 200 iters/s in the first 30 seconds
        { target: 200, duration: '3m30s' }, // hold at 200 iters/s for 3.5 minutes
        { target: 0, duration: '30s' }, // ramp down back to 0 iters/s over the last 30 second
      ],
      preAllocatedVUs: 50, // how large the initial pool of VUs would be
      maxVUs: 100, // if the preAllocatedVUs are not enough, we can initialize more
      tags: { test_type: 'api' }, // different extra metric tags for this scenario
      env: { MY_CROC_ID: '2' }, // same function, different environment variables
      exec: 'apitest', // same function as the scenario above, but with different env vars
    },
  },
  discardResponseBodies: true,
  thresholds: {
    // we can set different thresholds for the different scenarios because
    // of the extra metric tags we set!
    'http_req_duration{test_type:api}': ['p(95)<250', 'p(99)<350'],
    'http_req_duration{test_type:website}': ['p(99)<500'],
    // we can reference the scenario names as well
    'http_req_duration{scenario:my_api_test_2}': ['p(99)<300'],
  },
};

export function webtest() {
  http.get('https://test.k6.io/contacts.php');
  sleep(Math.random() * 2);
}

export function apitest() {
  http.get(`https://quickpizza.grafana.com/api/json?crocId=${__ENV.MY_CROC_ID}`);
  // no need for sleep() here, the iteration pacing will be controlled by the
  // arrival-rate executors above!
}

Run a specific scenario

k6 runs all configured scenarios by default. Use --scenario to select which scenarios run without changing the script.

The following script defines two scenarios:

import http from 'k6/http';

const scenarios = {
  my_web_test: {
    executor: 'per-vu-iterations',
    vus: 1,
    iterations: 1,
    maxDuration: '30s',
  },
  my_api_test: {
    executor: 'per-vu-iterations',
    vus: 1,
    iterations: 1,
    maxDuration: '30s',
  },
};

export const options = {
  scenarios,
  discardResponseBodies: true,
  thresholds: {
    http_req_duration: ['p(95)<250', 'p(99)<350'],
  },
};

export default function () {
  const response = http.get('https://quickpizza.grafana.com');
}

Run only my_web_test with its configured workload:

k6 run --scenario my_web_test script.js

To select both scenarios, pass their names separated by a comma:

k6 run --scenario my_web_test,my_api_test script.js

Scenarios on Grafana Labs

Concepts

Concepts

Executors

Executors

All executors

Advanced Examples

Advanced Examples

Combine scenarios

Use different environment variables and tags per scenario.

Run multiple scenario functions, with different thresholds

Run a specific scenario