> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/grafana/k6/llms.txt
> Use this file to discover all available pages before exploring further.

# Executors Overview

> Learn about k6 executors and how to control VU and iteration scheduling

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](/executors/shared-iterations)** - A fixed number of iterations shared among VUs
* **[Per VU Iterations](/executors/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](/executors/constant-vus)** - A fixed number of VUs run for a specified duration
* **[Ramping VUs](/executors/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](/executors/constant-arrival-rate)** - Starts iterations at a constant rate
* **[Ramping Arrival Rate](/executors/ramping-arrival-rate)** - Starts iterations at a variable rate over stages

### Special Executors

* **[Externally Controlled](/executors/externally-controlled)** - Control execution via the k6 REST API

## Configuration

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

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

## Common Configuration Options

All executors share these base configuration options:

<ParamField path="executor" type="string" required>
  The executor type (e.g., `constant-vus`, `ramping-arrival-rate`)
</ParamField>

<ParamField path="startTime" type="duration" default="0s">
  Time offset since the start of the test when this executor should begin
</ParamField>

<ParamField path="gracefulStop" type="duration" default="30s">
  Time to wait for iterations to finish executing before stopping them forcefully. Not supported by `externally-controlled`.
</ParamField>

<ParamField path="exec" type="string" default="default">
  Name of the exported JS function to execute
</ParamField>

<ParamField path="env" type="object">
  Environment variables specific to this executor
</ParamField>

<ParamField path="tags" type="object">
  Tags to set for all metrics emitted by this executor
</ParamField>

## 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:

```javascript theme={null}
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:

```javascript theme={null}
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

<CardGroup cols={2}>
  <Card title="Shared Iterations" icon="share-nodes" href="/executors/shared-iterations">
    Run a fixed total number of iterations
  </Card>

  <Card title="Constant VUs" icon="users" href="/executors/constant-vus">
    Maintain constant VUs over time
  </Card>

  <Card title="Ramping VUs" icon="chart-line" href="/executors/ramping-vus">
    Gradually increase/decrease VUs
  </Card>

  <Card title="Constant Arrival Rate" icon="clock" href="/executors/constant-arrival-rate">
    Fixed iterations per second
  </Card>
</CardGroup>