No results for

Powered byAlgolia

Ramping VUs


A variable number of VUs execute as many iterations as possible for a specified amount of time. This executor is equivalent to the global stages option.


In addition to the common configuration options this executor also adds the following options:

stages(required)arrayArray of objects that specify the target number of VUs to ramp up or down to.[]
startVUsintegerNumber of VUs to run at test start.1
gracefulRampDownstringTime to wait for an already started iteration to finish before stopping it during a ramp down."30s"

When to use

This executor is a good fit if you need VUs to ramp up or down during specific periods of time.


In this example, we'll run a two-stage test, ramping up from 0 to 10 VUs over 20 seconds, then down to 0 VUs over 10 seconds.

1import http from 'k6/http';
2import { sleep } from 'k6';
4export const options = {
5 discardResponseBodies: true,
6 scenarios: {
7 contacts: {
8 executor: 'ramping-vus',
9 startVUs: 0,
10 stages: [
11 { duration: '20s', target: 10 },
12 { duration: '10s', target: 0 },
13 ],
14 gracefulRampDown: '0s',
15 },
16 },
19export default function () {
20 http.get('');
21 // We're injecting a processing pause for illustrative purposes only!
22 // Each iteration will be ~515ms, therefore ~2 iterations/second per VU maximum throughput.
23 sleep(0.5);

Note the setting of gracefulRampDown to 0 seconds, which could cause some iterations to be interrupted during the ramp down stage.


The following graph depicts the performance of the example script:

Ramping VUs

Based upon our test scenario inputs and results:

  • We've defined 2 stages for a total test duration of 30 seconds;
  • stage 1 ramps up VUs linearly from the startVUs of 0 to the target of 10 over a 20 second duration;
  • from the 10 VUs at the end of stage 1, stage 2 then ramps down VUs linearly to the target of 0 over a 10 second duration;
  • each iteration of the default function is expected to be roughly 515ms, or ~2/s;
  • as the number of VUs changes, the iteration rate directly correlates; each addition of a VU increases the rate by ~2 iters/s, whereas each subtraction of a VU reduces by ~2 iters/s;
  • our example performed ~300 iterations over the course of the test.

Get the stage index

To get the current running stage index, use the getCurrentStageIndex helper function from the k6-jslib-utils library. It returns a zero-based number equal to the position in the shortcut stages array or in the executor's stages array.

import { getCurrentStageIndex } from '';
export const options = {
stages: [
{ target: 10, duration: '30s' },
{ target: 50, duration: '1m' },
{ target: 10, duration: '30s' },
export default function () {
if (getCurrentStageIndex() === 1) {
console.log('Running the second stage where the expected target is 50');

Using this feature, it is possible to automatically tag using the current running stage. Check the Tagging stages section for more details.