Scenarios documentation

src/data/markdown/docs/01 guides/02 Using k6/02 Metrics.md

@@ -21,6 +21,7 @@ The following _built-in_ metrics will **always** be collected by k6:
 | `vus_max`            | Gauge   | Max possible number of virtual users (VU resources are preallocated, to ensure performance will not be affected when scaling up the load level)                                                                                        |
 | `iterations`         | Counter | The aggregate number of times the VUs in the test have executed the JS script (the `default` function). |
 | `iteration_duration` | Trend   | The time it took to complete one full iteration of the default/main function.                                                                                                                                 |
+| `dropped_iterations` | Counter | Introduced in k6 v0.27.0, the number of iterations that could not be started due to lack of VUs (for the arrival-rate executors) or lack of time (due to expired maxDuration in the iteration-based executors). |
 | `data_received`      | Counter | The amount of received data. Read [this example](/examples/track-transmitted-data-per-url) to track data for an individual URL.                                                                                                                                                                                                          |
 | `data_sent`          | Counter | The amount of data sent. Read [this example](/examples/track-transmitted-data-per-url) to track data for an individual URL.                                                                                                                                                                                                               |
 | `checks`             | Rate    | The rate of successful checks.                                                                                                                                                                                                                |

src/data/markdown/docs/01 guides/02 Using k6/05 Options.md

@@ -17,6 +17,7 @@ Options allow you to configure how k6 will behave during test execution.
 | [Config](#config) | Specify the config file in JSON format to read the options values |
 | [Discard Response Bodies](#discard-response-bodies) | Specify if response bodies should be discarded |
 | [Duration](#duration) |  A string specifying the total duration a test run should be run for  |
+| [Execution Segment](#execution-segment) |  Limit execution to a segment of the total test  |
 | [Extension Options](#extension-options) |  An object used to set configuration options for third-party collectors  |
 | [Hosts](#hosts) | An object with overrides to DNS resolution |
 | [HTTP Debug](#http-debug) | Log all HTTP requests and responses |
@@ -33,6 +34,7 @@ Options allow you to configure how k6 will behave during test execution.
 | [Paused](#paused) | A boolean specifying whether the test should start in a paused state |
 | [Results Output](#results-output) | Specify the results output |
 | [RPS](#rps) | The maximum number of requests to make per second |
+| [Scenarios](#scenarios) | Define advanced execution scenarios |
 | [Setup Timeout](#setup-timeout) | Specify how long the `setup()` function is allow to run before it's terminated  |
 | [Skip TLS Verification](#skip-tls-verification) | A boolean specifying whether should ignore TLS verifications |
 | [Stages](#stages) | A list of objects that specify the target number of VUs to ramp up or down |
@@ -316,6 +318,34 @@ export let options = {
 </div>
 
 
+<h3 id="execution-segment">Execution Segment</h3>
+
+> _New in v0.27.0_
+
+These options specify how to partition the test run and which segment to run.
+If defined, k6 will scale the number of VUs and iterations to be run for that
+segment, which is useful in distributed execution. Available in `k6 run` and
+`k6 cloud` commands.
+
+| Env | CLI                            | Code / Config file         | Default |
+|-----|--------------------------------|----------------------------|---------|
+| N/A | `--execution-segment`          | `executionSegment`         | `"0:1"` |
+| N/A | `--execution-segment-sequence` | `executionSegmentSequence` | `"0,1"` |
+
+For example, to run 25% of a test, you would specify `--execution-segment '25%'`,
+which would be equivalent to `--execution-segment '0:1/4'`, i.e. run the first
+1/4 of the test.
+To ensure that each instance executes a specific segment, also specify the full
+segment sequence, e.g. `--execution-segment-sequence '0,1/4,1/2,1'`.
+This way one instance could run with `--execution-segment '0:1/4'`, another with
+`--execution-segment '1/4:1/2'`, etc. and there would be no overlap between them.
+
+In v0.27.0 this distinction is not very important, but it will be required
+in future versions when support for test data partitioning is added.
+
+<!-- TODO: Add more examples, link to a standalone page? -->
+
+
 <h3 id="hosts">Hosts</h3>
 
 An object with overrides to DNS resolution, similar to what you can do with `/etc/hosts` on
@@ -388,8 +418,8 @@ $ k6 run --include-system-env-vars ~/script.js
 A number specifying a fixed number of iterations to execute of the script, as opposed to specifying
 a duration of time during which the script would run in a loop.
 \*Note: The number of iterations
-is split between all VUs. Available in `k6 run` command (not yet supported for cloud executed
-tests using the `k6 cloud` command).
+is split between all VUs. Available in the `k6 run` and since v0.27.0 in the
+`k6 cloud` command as well.
 
 | Env             | CLI                  | Code / Config file | Default |
 |-----------------|----------------------|--------------------|---------|
@@ -636,11 +666,48 @@ export let options = {
 
 </div>
 
-
 > ### Cloud runs
 >
 > There are a couple of considerations with this option when running cloud tests. The option is set per load generator which means that the value you set in the options object of your test script will be multiplied by the number of load generators your test run is using. At the moment we are hosting 300 VUs per load generator instance. In practice that means that if you set the option for 100 rps, and run a test with 1000 VUs, you will spin up 4 load gen instances and effective rps limit of your test run will be 400
 
+
+<h3 id="scenarios">Scenarios</h3>
+
+Define one or more execution patterns, with various VU and iteration scheduling
+settings, running different exported functions (besides `default`!), using different
+environment variables, tags, and more.
+
+See the [Scenarios](/using-k6/scenarios) article for details and more examples.
+
+Available in `k6 run` and `k6 cloud` commands.
+
+| Env | CLI | Code / Config file | Default         |
+|-----|-----|--------------------|-----------------|
+| N/A | N/A | `scenarios`        | `null`          |
+
+<div class="code-group" data-props='{"labels": [], "lineNumbers": [true]}'>
+
+```js
+export let options = {
+  scenarios: {
+    my_api_scenario: {  // arbitrary scenario name
+      executor: 'ramping-vus',
+      startVUs: 0,
+      stages: [
+        { duration: '5s', target: 100 },
+        { duration: '5s', target: 0 },
+      ],
+      gracefulRampDown: '10s',
+      env: { MYVAR: 'example' },
+      tags: { my_tag: 'example' },
+    }
+  }
+};
+```
+
+</div>
+
+
 <h3 id="setup-timeout">Setup Timeout</h3>
 
 Specify how long the `setup()` function is allow to run before it's terminated and the test fails.
@@ -775,7 +842,7 @@ CLI. Available in `k6 run` and `k6 cloud` commands
 
 | Env              | CLI             | Code / Config file | Default                                                                                          |
 |------------------|-----------------|--------------------|--------------------------------------------------------------------------------------------------|
-| `K6_SYSTEM_TAGS` | `--system-tags` | `systemTags`       | `proto`, `subproto`, `status`, `method`, `url`, `name`, `group`, `check`, `error`, `tls_version` |
+| `K6_SYSTEM_TAGS` | `--system-tags` | `systemTags`       | `proto`, `subproto`, `status`, `method`, `url`, `name`, `group`, `check`, `error`, `tls_version`, `scenario` |
 
 <div class="code-group" data-props='{"labels": [], "lineNumbers": [true]}'>
 

src/data/markdown/docs/01 guides/02 Using k6/08 Tags and Groups.md

@@ -69,6 +69,7 @@ Currently, k6 automatically creates the following tags by default:
 | `error`       | a string with a non-HTTP error message (e.g. network or DNS error)                                                                                                                |
 | `error_code`  | added in k6 v0.24.0, this is a number that is unique for different error types; a list of current error codes can be found at the [Error Codes](/javascript-api/error-codes) page |
 | `tls_version` | the [TLS](/using-k6/protocols/ssl-tls) version                                                                                                                                    |
+| `scenario`    | the name of the scenario where the metric was emitted                                                                                                                             |
 
 If you choose, you could disable some of the above tags by using the `systemTags`
 [option](/using-k6/options), just keep in mind that some data collectors (e.g. `cloud`)