Executors Overview

Executors control how k6 schedules VUs and iterations. They are the building blocks of k6 test execution, determining:

How many VUs run
When VUs start and stop
Whether iterations are shared or per-VU
Whether execution is time-based or iteration-based

Executor Types

k6 provides 8 executor types, each optimized for different testing scenarios:

Iteration-Based Executors

These executors run a fixed number of iterations:

Shared Iterations - A fixed number of iterations shared among VUs
Per VU Iterations - Each VU runs a fixed number of iterations

Time-Based Executors with Fixed VUs

These executors run VUs for a specified duration:

Constant VUs - A fixed number of VUs run for a specified duration
Ramping VUs - VUs ramp up/down over stages

Arrival Rate Executors

These executors start iterations at a fixed rate, regardless of iteration duration:

Constant Arrival Rate - Starts iterations at a constant rate
Ramping Arrival Rate - Starts iterations at a variable rate over stages

Special Executors

Externally Controlled - Control execution via the k6 REST API

Configuration

Executors are configured in the scenarios section of your k6 options:

export const options = {
  scenarios: {
    my_scenario: {
      executor: 'constant-vus',
      vus: 10,
      duration: '30s',
    },
  },
};

Common Configuration Options

All executors share these base configuration options:

executor

string

required

The executor type (e.g., constant-vus, ramping-arrival-rate)

startTime

duration

default:"0s"

Time offset since the start of the test when this executor should begin

gracefulStop

duration

default:"30s"

Time to wait for iterations to finish executing before stopping them forcefully. Not supported by externally-controlled.

exec

string

default:"default"

Name of the exported JS function to execute

env

object

Environment variables specific to this executor

Choosing an Executor

Use Iteration-Based Executors When:

You need to run a specific number of test iterations
You want to ensure all test data is processed
You’re running data-driven tests with a fixed dataset

Use Time-Based Executors When:

You want to test system behavior over a time period
You’re simulating real user behavior patterns
You need predictable test duration

Use Arrival Rate Executors When:

You need to test at specific requests-per-second rates
Iteration duration varies significantly
You want to model realistic traffic patterns with variable load
You need to ensure a constant throughput regardless of response times

Use Externally Controlled Executor When:

You need dynamic control during test execution
You’re integrating k6 with other tools or dashboards
You want to manually adjust load based on real-time observations

Graceful Stop

The gracefulStop option (default: 30s) gives running iterations time to complete when the executor’s regular duration ends:

export const options = {
  scenarios: {
    my_scenario: {
      executor: 'constant-vus',
      vus: 10,
      duration: '5m',
      gracefulStop: '30s', // Wait up to 30s for iterations to finish
    },
  },
};

If an iteration doesn’t complete within the graceful stop period, it’s interrupted.

Multiple Scenarios

You can run multiple executors simultaneously:

export const options = {
  scenarios: {
    smoke_test: {
      executor: 'constant-vus',
      vus: 1,
      duration: '1m',
    },
    load_test: {
      executor: 'ramping-vus',
      startTime: '1m', // Start after smoke test
      startVUs: 0,
      stages: [
        { duration: '2m', target: 50 },
        { duration: '5m', target: 50 },
        { duration: '2m', target: 0 },
      ],
    },
  },
};

Execution Segments

All executors except externally-controlled support distributed execution via execution segments. This allows you to split test execution across multiple k6 instances.

Next Steps

Shared Iterations

Run a fixed total number of iterations

Constant VUs

Maintain constant VUs over time

Ramping VUs

Gradually increase/decrease VUs

Constant Arrival Rate

Fixed iterations per second

Overview

Executor Types

​Executor Types

​Iteration-Based Executors

​Time-Based Executors with Fixed VUs

​Arrival Rate Executors

​Special Executors

​Configuration

​Common Configuration Options

​Choosing an Executor

​Use Iteration-Based Executors When:

​Use Time-Based Executors When:

​Use Arrival Rate Executors When:

​Use Externally Controlled Executor When:

​Graceful Stop

​Multiple Scenarios

​Execution Segments

​Next Steps

Shared Iterations

Constant VUs

Ramping VUs

Constant Arrival Rate

Build docs developers (and LLMs) love

Executor Types

Iteration-Based Executors

Time-Based Executors with Fixed VUs

Arrival Rate Executors

Special Executors

Configuration

Common Configuration Options

Choosing an Executor

Use Iteration-Based Executors When:

Use Time-Based Executors When:

Use Arrival Rate Executors When:

Use Externally Controlled Executor When:

Graceful Stop

Multiple Scenarios

Execution Segments

Next Steps