Shared Iterations Executor

Execute a fixed total number of iterations shared among VUs

The shared-iterations executor executes a specific total number of iterations that are shared across all configured VUs. This executor is ideal when you need to ensure a specific total number of test iterations complete, regardless of how long each iteration takes.

How It Works

With shared iterations:

1. A pool of VUs is created (specified by vus)
2. VUs compete to execute iterations from the shared total
3. The first VU to finish an iteration immediately grabs the next one
4. Execution continues until all iterations complete or maxDuration is reached
5. Faster VUs will execute more iterations than slower ones

Iteration Pool: [1][2][3][4][5][6][7][8][9][10]

VU 1: ████─────█████────███       (iterations 1, 5, 9)
VU 2: ──████████────███           (iterations 2, 3, 6)
VU 3: ────████─────████────████   (iterations 4, 7, 10)
VU 4: ──────████████              (iterations 8)

Configuration

executor · string · required

Must be shared-iterations

vus · integer · default: "1"

Number of VUs to run concurrently. Must be greater than 0.

iterations · integer · default: "1"

Total number of script iterations to execute across all VUs. Must be greater than or equal to vus.

maxDuration · duration · default: "10m"

Maximum duration for the executor. If all iterations don’t complete within this time, the executor stops and remaining iterations are dropped.

Example

Basic Configuration

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

export const options = {
  scenarios: {
    shared_iter_scenario: {
      executor: 'shared-iterations',
      vus: 10,
      iterations: 100,
      maxDuration: '30s',
    },
  },
};

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

This runs 100 total iterations shared among 10 VUs, with a maximum duration of 30 seconds.

Data-Driven Testing

import http from 'k6/http';
import { SharedArray } from 'k6/data';

const testData = new SharedArray('users', function () {
  return JSON.parse(open('./users.json'));
});

export const options = {
  scenarios: {
    data_driven: {
      executor: 'shared-iterations',
      vus: 5,
      iterations: testData.length, // One iteration per data row
      maxDuration: '5m',
    },
  },
};

let iterationCounter = 0;

export default function () {
  const user = testData[iterationCounter++];
  http.post('https://test.k6.io/login', JSON.stringify(user));
}

When to Use

Use the shared iterations executor when:

• You need to process a specific amount of test data exactly once
• You want to ensure a fixed total number of operations complete
• You need to iterate through a dataset with each iteration processing one item
• The total work is more important than the execution time
• You want faster VUs to do more work

Behavior Details

VU Distribution

Iterations are not evenly distributed. VUs that complete iterations faster will execute more iterations:

// If VU 1 is consistently faster:
// VU 1 might do: iterations 1, 3, 5, 7, 9, 11, 13...
// VU 2 might do: iterations 2, 6, 10, 14...
// VU 3 might do: iterations 4, 8, 12...

Maximum Duration

If iterations don’t complete within maxDuration, execution stops and the remaining iterations are recorded as dropped:

export const options = {
  scenarios: {
    example: {
      executor: 'shared-iterations',
      vus: 2,
      iterations: 1000,
      maxDuration: '10s', // Might not complete all 1000
    },
  },
};

Dropped iterations are tracked in the dropped_iterations metric.

Minimum Iterations

The number of iterations must be at least equal to the number of VUs. This ensures each VU can execute at least one iteration:

// ❌ Invalid - iterations < vus
{
  executor: 'shared-iterations',
  vus: 10,
  iterations: 5, // Error!
}

// ✓ Valid
{
  executor: 'shared-iterations',
  vus: 10,
  iterations: 10, // OK
}

Metrics

The executor emits these specific metrics:

• iterations - Total completed iterations
• iteration_duration - Time to complete each iteration
• dropped_iterations - Iterations that didn’t complete within maxDuration
• vus - Number of active VUs
• vus_max - Maximum number of VUs

Common Patterns

Processing a Queue

import http from 'k6/http';

const tasks = new SharedArray('tasks', () => 
  Array.from({ length: 500 }, (_, i) => ({ id: i }))
);

let taskIndex = 0;

export const options = {
  scenarios: {
    process_queue: {
      executor: 'shared-iterations',
      vus: 20,
      iterations: tasks.length,
    },
  },
};

export default function () {
  const task = tasks[taskIndex++];
  http.post('https://api.example.com/process', JSON.stringify(task));
}

Smoke Test with Exact Count

export const options = {
  scenarios: {
    smoke: {
      executor: 'shared-iterations',
      vus: 1,
      iterations: 10, // Exactly 10 iterations
      maxDuration: '1m',
    },
  },
};

Comparison with Per VU Iterations

Feature	Shared Iterations	Per VU Iterations
Total iterations	Fixed	vus × iterations
Distribution	Dynamic (faster VUs do more)	Even (each VU does same amount)
Predictability	Less predictable per-VU	More predictable per-VU
Use case	Process fixed dataset	Consistent per-user load

Best Practices

1. Set appropriate maxDuration: Ensure maxDuration is long enough for all iterations to complete
2. Monitor dropped iterations: Check the dropped_iterations metric to ensure work completes
3. Use SharedArray for data: When processing datasets, use SharedArray to avoid memory duplication
4. Consider execution segment: For distributed testing, iterations are split across k6 instances

See Also

• Per VU Iterations - Each VU runs a fixed number of iterations
• Constant VUs - Time-based execution with fixed VUs