Documentationbreadcrumb arrow Grafana k6breadcrumb arrow Using k6breadcrumb arrow Scenarios
Open source RSS

Scenarios

Scenarios configure how VUs and iteration schedules in granular detail. With scenarios, you can model diverse workloads, or traffic patterns in load tests.

Benefits of using scenarios include:

  • Easier, more flexible test organization. You can declare multiple scenarios in the same script, and each one can independently execute a different JavaScript function.
  • Simulate more realistic traffic. Every scenario can use a distinct VU and iteration scheduling pattern, powered by a purpose-built executor.
  • Parallel or sequential workloads. Scenarios are independent from each other and run in parallel, though they can be made to appear sequential by setting the startTime property of each carefully.
  • Granular results analysis. Different environment variables and metric tags can be set per scenario.

Configure scenarios

To configure scenarios, use the scenarios key in the options object. You can give the scenario any name, as long as each scenario name in the script is unique.

The scenario name appears in the result summary, tags, and so on.

JavaScript 
export const options = {
  scenarios: {
    example_scenario: {
      // name of the executor to use
      executor: 'shared-iterations',

      // common scenario configuration
      startTime: '10s',
      gracefulStop: '5s',
      env: { EXAMPLEVAR: 'testing' },
      tags: { example_tag: 'testing' },

      // executor-specific configuration
      vus: 10,
      iterations: 200,
      maxDuration: '10s',
    },
    another_scenario: {
      /*...*/
    },
  },
};

Scenario executors

For each k6 scenario, the VU workload is scheduled by an executor. Executors configure how long the test runs, whether traffic stays constant or changes, and whether the workload is modeled by VUs or by arrival rate (that is, open or closed models).

Your scenario object must define the executor property with one of the predefined executor names. Your choice of executor determines how k6 models load. Choices include:

Along with the generic scenario options, each executor object has additional options specific to its workload. For the full list, refer to Executors.

Scenario options

OptionTypeDescriptionDefault
executor(required) ️stringUnique executor name. See the list of possible values in the executors section.-
startTimestringTime offset since the start of the test, at which point this scenario should begin execution."0s"
gracefulStopstringTime to wait for iterations to finish executing before stopping them forcefully. To learn more, read Graceful stop."30s"
execstringName of exported JS function to execute."default"
envobjectEnvironment variables specific to this scenario.{}
tagsobjectTags specific to this scenario.{}
optionsobjectAdditional options include browser options.{}

Scenario example

This script combines two scenarios, with sequencing:

  • The shared_iter_scenario starts immediately. Ten VUs try to use 100 iterations as quickly as possible (some VUs may use more iterations than others).
  • The per_vu_scenario starts after 10s. In this case, ten VUs each run ten iterations.

Which scenario takes longer? You can run to discover. You can also add a maxDuration property to one or both scenarios.

JavaScript 
import http from 'k6/http';

export const options = {
  scenarios: {
    shared_iter_scenario: {
      executor: 'shared-iterations',
      vus: 10,
      iterations: 100,
      startTime: '0s',
    },
    per_vu_scenario: {
      executor: 'per-vu-iterations',
      vus: 10,
      iterations: 10,
      startTime: '10s',
    },
  },
};

export default function () {
  http.get('https://test.k6.io/');
}

If you run a script with scenarios, k6 output includes high-level information about each one. For example, if you run the preceding script, k6 run scenario-example.js, then k6 reports the scenarios as follows:

Bash 
  execution: local
     script: scenario-example.js
     output: -

  scenarios: (100.00%) 2 scenarios, 20 max VUs, 10m40s max duration (incl. grace
ful stop):
           * shared_iter_scenario: 100 iterations shared among 10 VUs (maxDurati
on: 10m0s, gracefulStop: 30s)
           * per_vu_scenario: 10 iterations for each of 10 VUs (maxDuration: 10m
0s, startTime: 10s, gracefulStop: 30s)

The full output includes the summary metrics, like any default end-of-test summary:

Run selected scenarios

Use --scenario to run part of a multi-scenario script without editing it or adding environment-variable logic. For example, run only the workload for the API method you are developing, or run a subset on every commit and the full test less often. Selected scenarios keep their configured load.

Save this example as scenarios.js:

JavaScript 
export const options = {
  scenarios: {
    api: {
      executor: 'shared-iterations',
      vus: 1,
      iterations: 2,
      exec: 'api',
    },
    checkout: {
      executor: 'shared-iterations',
      vus: 1,
      iterations: 3,
      exec: 'checkout',
    },
  },
  thresholds: {
    iterations: ['count>0'],
    'iterations{scenario:api}': ['count>0'],
    'iterations{scenario:checkout}': ['count>0'],
  },
};

export function api() {
  console.log('API iteration');
}

export function checkout() {
  console.log('Checkout iteration');
}

Select one name, or separate several names with commas:

sh 
k6 run --scenario checkout scenarios.js
k6 run --scenario api,checkout scenarios.js

The first command runs three checkout iterations. The second runs both scenarios with their configured iteration counts. Selection preserves each scenario’s executor, load, timing, function, environment, tags, and browser settings. Other global options and the normal test lifecycle still apply, including setup() and teardown().

Names must exist in the configured scenarios object after the script’s initialization code runs. A default export alone does not define a selectable scenario; --scenario default requires an explicitly configured scenarios.default. An empty selection or an unknown name returns an error.

Load options and thresholds

You cannot combine --scenario with --vus, --duration, --iterations, or --stage. k6 ignores the corresponding top-level settings from the script, a configuration file, or environment variables and logs a warning. Settings inside selected scenarios remain intact. Execution segments remain active and can reduce the work assigned to selected scenarios.

Selection removes thresholds whose scenario tag names a configured scenario that you excluded, and logs a warning. In the example, selecting checkout skips the API threshold and keeps the global and checkout thresholds. Global thresholds, filters without a scenario tag, and filters naming a selected or unconfigured scenario remain active. A global count threshold that expects the full workload can still fail a partial run.

A skipped threshold stays skipped even if another scenario emits samples with the excluded scenario’s tag. For example, a selected checkout scenario can emit a custom metric tagged scenario:api; an API threshold removed by selection will not evaluate those samples. Refer to thresholds for specific tags when choosing which assertions should remain shared.

Cloud runs and archives

The same selection works with k6 cloud run, including --local-execution, and k6 archive. Archives save the selected scenarios and remaining thresholds, so you can replay an archive without repeating --scenario. Omitting the flag on replay does not restore excluded scenarios or thresholds.

Run each selected scenario once

To check the selected workloads with one iteration each, combine --scenario with --once. Selection chooses which scenarios run; --once gives each one a single VU and iteration:

sh 
k6 run --scenario api,checkout --once scenarios.js

This command runs one API iteration and one checkout iteration. Each scenario keeps its function, environment, tags, and browser settings, while --once resets its executor and timing to shared-iterations, startTime: '0s', maxDuration: '10m', and gracefulStop: '30s'. Execution segments cannot be combined with --once. Bare --once still rejects a script with multiple scenarios; explicit selection tells k6 which ones to run.