Separate executor options, add 'When to use' section

See #49 (review)
grafana · Jul 10, 2020 · ee1e8aa · ee1e8aa
1 parent 6ab5bff
commit ee1e8aa
Showing 1 changed file with 49 additions and 1 deletion.
diff --git a/src/data/markdown/docs/01 guides/02 Using k6/14 Scenarios.md b/src/data/markdown/docs/01 guides/02 Using k6/14 Scenarios.md
@@ -94,12 +94,19 @@ once all iterations are executed. This executor is equivalent to the global `vus
 Note that iterations aren't fairly distributed with this executor, and a VU that
 executes faster will complete more iterations than others.
 
+#### Options
+
 | Option        | Type    | Description                                                                    | Default |
 |---------------|---------|--------------------------------------------------------------------------------|---------|
 | `vus`         | integer | Number of VUs to run concurrently.                                             | `1`     |
 | `iterations`  | integer | Total number of script iterations to execute across all VUs.                   | `1`     |
 | `maxDuration` | string  | Maximum test duration before it's forcibly stopped (excluding `gracefulStop`). | `"10m"` |
 
+#### When to use
+
+This executor is suitable when you want a specific amount of VUs to complete a fixed
+number of total iterations, and the amount of iterations per VU is not important.
+
 #### Examples
 
 - Execute 200 total iterations shared by 10 VUs with a maximum duration of 10 seconds:
@@ -131,14 +138,22 @@ export default function() {
 
 ### Per VU iterations
 
-Each VU executes an exact number of iterations.
+Each VU executes an exact number of iterations. The total number of completed
+iterations will be `vus * iterations`.
+
+#### Options
 
 | Option        | Type    | Description                                                                    | Default |
 |---------------|---------|--------------------------------------------------------------------------------|---------|
 | `vus`         | integer | Number of VUs to run concurrently.                                             | `1`     |
 | `iterations`  | integer | Number of script iterations to execute with each VU.                           | `1`     |
 | `maxDuration` | string  | Maximum test duration before it's forcibly stopped (excluding `gracefulStop`). | `"10m"` |
 
+#### When to use
+
+Use this executor if you need a specific amount of VUs to complete the same amount of
+iterations.
+
 #### Examples
 
 - Execute 20 iterations by 10 VUs *each*, for a total of 200 iterations, with a
@@ -174,11 +189,17 @@ export default function() {
 A fixed number of VUs execute as many iterations as possible for a specified amount
 of time. This executor is equivalent to the global `vus` and `duration` options.
 
+#### Options
+
 | Option     | Type    | Description                                     | Default |
 |------------|---------|-------------------------------------------------|---------|
 | `vus`      | integer | Number of VUs to run concurrently.              | `1`     |
 | `duration` | string  | Total test duration (excluding `gracefulStop`). | -       |
 
+#### When to use
+
+Use this executor if you need a specific amount of VUs to run for a certain amount of time.
+
 #### Examples
 
 - Run a constant 10 VUs for 10 seconds:
@@ -212,12 +233,19 @@ export default function() {
 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.
 
+#### Options
+
 | Option             | Type    | Description                                                                   | Default |
 |--------------------|---------|-------------------------------------------------------------------------------|---------|
 | `startVUs`         | integer | Number of VUs to run at test start.                                           | `1`     |
 | `stages`           | array   | Array of objects that specify the target number of VUs to ramp up or down to. | `[]`    |
 | `gracefulRampDown` | string  | Time to wait for iterations to finish before starting new VUs.                | `"30s"` |
 
+#### When to use
+
+This executor is a good fit if you need VUs to ramp up or down during specific periods
+of time.
+
 #### Examples
 
 - Run a two-stage test, ramping up from 0 to 100 VUs for 5 seconds, and down to 0 VUs
@@ -265,6 +293,8 @@ useful for a more accurate representation of RPS, for example.
 
 See the [arrival rate](#arrival-rate) section for details.
 
+#### Options
+
 | Option            | Type    | Description                                                                             | Default |
 |-------------------|---------|-----------------------------------------------------------------------------------------|---------|
 | `rate`            | integer | Number of iterations to execute each `timeUnit` period.                                 | -       |
@@ -273,6 +303,11 @@ See the [arrival rate](#arrival-rate) section for details.
 | `preAllocatedVUs` | integer | Number of VUs to pre-allocate before test start in order to preserve runtime resources. | -       |
 | `maxVUs`          | integer | Maximum number of VUs to allow during the test run.                                     | -       |
 
+#### When to use
+
+When you want to maintain a constant number of requests without being affected by the
+system-under-test's performance.
+
 #### Examples
 
 - Execute a constant 200 RPS for 1 minute, allowing k6 to dynamically schedule up to 100 VUs:
@@ -315,6 +350,8 @@ to dynamically change the number of VUs to achieve the configured iteration rate
 
 See the [arrival rate](#arrival-rate) section for details.
 
+#### Options
+
 | Option            | Type    | Description                                                                             | Default |
 |-------------------|---------|-----------------------------------------------------------------------------------------|---------|
 | `startRate`       | integer | Number of iterations to execute each `timeUnit` period at test start.                   | `0`     |
@@ -323,6 +360,11 @@ See the [arrival rate](#arrival-rate) section for details.
 | `preAllocatedVUs` | integer | Number of VUs to pre-allocate before test start in order to preserve runtime resources. | -       |
 | `maxVUs`          | integer | Maximum number of VUs to allow during the test run.                                     | -       |
 
+#### When to use
+
+If you need your tests to not be affected by the system-under-test's performance, and
+would like to ramp the number of iterations up or down during specific periods of time.
+
 #### Examples
 
 - Execute a variable RPS test, starting at 50, ramping up to 200 and then back to 0,
@@ -368,12 +410,18 @@ required in order to use the `pause`, `resume`, and `scale` CLI commands. Also n
 that arguments to `scale` to change the amount of active or maximum VUs only affect
 the externally controlled executor.
 
+#### Options
+
 | Option     | Type    | Description                                         | Default |
 |------------|---------|-----------------------------------------------------|---------|
 | `vus`      | integer | Number of VUs to run concurrently.                  | -       |
 | `maxVUs`   | integer | Maximum number of VUs to allow during the test run. | -       |
 | `duration` | string  | Total test duration.                                | -       |
 
+#### When to use
+
+If you want to control the number of VUs while the test is running.
+
 #### Examples
 
 - Execute a test run controllable at runtime, starting with 0 VUs up to a maximum of