Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

scenarios, rework top-level page #934

Merged
merged 7 commits into from
Dec 6, 2022
Merged

scenarios, rework top-level page #934

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a7e08df
scenarios, rework top-level page
MattDodsonEnglish Dec 5, 2022
f2e7feb
Update src/data/markdown/translated-guides/en/02 Using k6/14 Scenario…
MattDodsonEnglish Dec 5, 2022
b86fcda
Update src/data/markdown/translated-guides/en/02 Using k6/14 Scenario…
MattDodsonEnglish Dec 5, 2022
c2bebd1
Update src/data/markdown/translated-guides/en/02 Using k6/14 Scenario…
MattDodsonEnglish Dec 5, 2022
627d974
Update src/data/markdown/translated-guides/en/02 Using k6/14 Scenario…
MattDodsonEnglish Dec 5, 2022
6b379f8
Update src/data/markdown/translated-guides/en/02 Using k6/14 Scenario…
MattDodsonEnglish Dec 5, 2022
bd01aed
Use correct syntax highlighting in codeblock
MattDodsonEnglish Dec 6, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ...arkdown/docs/07 extensions/01 Get started/04 Create/01 JavaScript Extensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -331,7 +331,7 @@ INFO[0000] Active VUs: 2, Iteration: 2, VU ID: 2, VU ID from runtime: 2 source=
## Things to keep in mind

- The code in the `default` function (or another function specified by
[`exec`](/using-k6/scenarios/#common-options)) will be executed many
[`exec`](/using-k6/scenarios/#options)) will be executed many
times during a test run and possibly in parallel by thousands of VUs.
Any operation of your extension should therefore be performant
and [thread-safe](https://en.wikipedia.org/wiki/Thread_safety).
Expand Down
155 changes: 91 additions & 64 deletions src/data/markdown/translated-guides/en/02 Using k6/14 Scenarios.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,24 @@ excerpt: 'Scenarios allow us to make in-depth configurations to how VUs and iter
hideFromSidebar: false
---

Scenarios make in-depth configurations to how VUs and iterations are scheduled. This makes it possible to model diverse traffic patterns in load tests. Benefits of using scenarios include:
Scenarios configure how VUs and iteration schedules in granular detail.
With scenarios, you can model diverse _workloads_, or traffic patterns in load tests.

- Multiple scenarios can be declared in the same script, and each one can
independently execute a different JavaScript function, which makes organizing tests easier
and more flexible.
- Every scenario can use a distinct VU and iteration scheduling pattern,
powered by a purpose-built [executor](#executors). This enables modeling
of advanced execution patterns which can better simulate real-world traffic.
- Scenarios are independent from each other and run in parallel, though they can be made to appear sequential by setting the `startTime` property of each carefully.
- Different environment variables and metric tags can be set per scenario.
Benefits of using scenarios include:
- **Easier, more flexible test organization.** You can declare multiple scenarios in the same script,
and each one can independently execute a different JavaScript function.
- **Simulate more realistic traffic.**
Every scenario can use a distinct VU and iteration scheduling pattern,
powered by a purpose-built [executor](#scenario-executors).
- **Parallel or sequential workloads.** Scenarios are independent from each other and run in parallel, though they can be made to appear sequential by setting the `startTime` property of each carefully.
- **Granular results analysis.** Different environment variables and metric tags can be set per scenario.

## Configuration
## Configure scenarios

Execution scenarios are primarily configured via the `scenarios` key of the exported `options` object
in your test scripts. The key for each scenario can be an arbitrary, but unique, scenario name. It will
appear in the result summary, tags, etc.
To configure scenarios, use the `scenarios` key in the `options` object.
You can give the scenario any name, as long as each scenario name in the script is unique.

The scenario name appears in the result summary, tags, and so on.

<CodeGroup labels={[]} lineNumbers={[true]}>

Expand Down Expand Up @@ -50,39 +52,33 @@ export const options = {

</CodeGroup>

## Executors

[Executors](/using-k6/scenarios/executors) are the workhorses of the k6 execution engine. Each one schedules VUs and iterations differently, and you'll choose one depending on the type
of traffic you want to model to test your services.
## Scenario executors

Possible values for `executor` are the executor name separated by hyphens.
For each k6 scenario, the VU workload is scheduled by an _executor_.
For example, executors configure:
- Whether VU traffic stays constant or changes
- Whether to model traffic by iteration number or by VU arrival rate.

| Name | Value | Description |
| ---------------------------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Shared iterations](/using-k6/scenarios/executors/shared-iterations) | `shared-iterations` | A fixed amount of iterations are<br/> "shared" between a number of VUs. |
| [Per VU iterations](/using-k6/scenarios/executors/per-vu-iterations) | `per-vu-iterations` | Each VU executes an exact number of iterations. |
| [Constant VUs](/using-k6/scenarios/executors/constant-vus) | `constant-vus` | A fixed number of VUs execute as many<br/> iterations as possible for a specified amount of time. |
| [Ramping VUs](/using-k6/scenarios/executors/ramping-vus) | `ramping-vus` | A variable number of VUs execute as many<br/> iterations as possible for a specified amount of time. |
| [Constant Arrival Rate](/using-k6/scenarios/executors/constant-arrival-rate) | `constant-arrival-rate` | A fixed number of iterations are executed<br/> in a specified period of time. |
| [Ramping Arrival Rate](/using-k6/scenarios/executors/ramping-arrival-rate) | `ramping-arrival-rate` | A variable number of iterations are <br/> executed in a specified period of time. |
| [Externally Controlled](/using-k6/scenarios/executors/externally-controlled) | `externally-controlled` | Control and scale execution at runtime<br/> via [k6's REST API](/misc/k6-rest-api) or the [CLI](https://k6.io/blog/how-to-control-a-live-k6-test). |
Your scenario object must define the `executor` property with one of the predefined executors names.
Along with the generic scenario options, each executor object has additional options specific to its workload.
For the list of the executors, refer to the [Executor guide](/using-k6/scenarios/executors/).

## Common options
## Scenario options {#options}

| Option | Type | Description | Default |
| -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| executor<sup>(required)</sup> ️ | string | Unique executor name. See the list of possible values in the [executors](#executors) section. | - |
| executor<sup>(required)</sup> ️ | string | Unique executor name. See the list of possible values in the [executors](/using-k6/scenarios/executors/) section. | - |
| startTime | string | Time offset since the start of the test, at which point this scenario should begin execution. | `"0s"` |
| gracefulStop | string | Time to wait for iterations to finish executing before stopping them forcefully. Read more about gracefully stopping a test run [here](/using-k6/scenarios/graceful-stop/). | `"30s"` |
| exec | string | Name of exported JS function to execute. | `"default"` |
| env | object | Environment variables specific to this scenario. | `{}` |
| tags | object | [Tags](/using-k6/tags-and-groups) specific to this scenario. | `{}` |

## Example
## Scenario example

The following script defines two minimal scenarios:

<CodeGroup labels={[]} lineNumbers={[true]}>
<CodeGroup labels={["scenario-example.js"]} lineNumbers={[true]}>

```bash
import http from 'k6/http';
Expand All @@ -101,52 +97,83 @@ export const options = {
};

export default function () {
http.get('https://google.com/');
http.get('https://test.k6.io/');
}
```

</CodeGroup>

Running the above script with `k6 run script.js`, additional information is added to the output as follows:
If you run a script with scenarios, k6 output includes high-level information about each one.
For example, if you run the preceding script, `k6 run scenario-example.js`,
then k6 reports the scenarios as follows:

<CodeGroup labels={["scenario example output"]} lineNumbers={[false]}>

```bash
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
```bash
```javascript

Copy link
Contributor Author

@MattDodsonEnglish MattDodsonEnglish Dec 6, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ppcano , just wondering, what's your preference for Javascript over bash to highlight text output? Originally, I was going to use txt, which would have rendered the text all white, then switched to bash since it highlights the number values.

image

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@MattDodsonEnglish sorry. This should be bash. My suggestion was for scenario-example.js

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh that's a good catch anyway, thanks! Fixed with: bd01aed

execution: local
script: scenario-example.js
output: -

scenarios: (100.00%) 2 scenarios, 30 max VUs, 10m40s max duration (incl. graceful stop):
* shared_iter_scenario: 100 iterations shared among 20 VUs
(maxDuration: 10s, gracefulStop: 30s)
* per_vu_scenario: 20 iterations for each of 10 VUs
(maxDuration: 10m0s, startTime: 10s, gracefulStop: 30s)

<CodeGroup labels={[]} lineNumbers={[true]}>

running (00m15.1s), 00/30 VUs, 300 complete and 0 interrupted iterations
shared_iter_scenario ✓ [======================================] 20 VUs 03.0s/10s 100/100 shared iters
per_vu_scenario ✓ [======================================] 10 VUs 00m05.1s/10m0s 200/200 iters, 20 per VU

```

</CodeGroup>

The full output includes the summary metrics, like any default end-of-test summary:

<Collapsible title="full scenario-example.js output" isOpen="" tag="">

<CodeGroup>

```bash
/\ |‾‾| /‾‾/ /‾‾/
/\ / \ | |/ / / /
/ \/ \ | ( / ‾‾\
/ \ | |\ \ | (‾) |
/\ |‾‾| /‾‾/ /‾‾/
/\ / \ | |/ / / /
/ \/ \ | ( / ‾‾\
/ \ | |\ \ | (‾) |
/ __________ \ |__| \__\ \_____/ .io

execution: local
script: .\scenario_example.js
script: scenario-example.js
output: -

scenarios: (100.00%) 2 scenarios, 2 max VUs, 10m35s max duration (incl. graceful stop):
* example_scenario: 1 iterations shared among 1 VUs (maxDuration: 10m0s, gracefulStop: 30s)
* another_scenario: 1 iterations shared among 1 VUs (maxDuration: 10m0s, startTime: 5s, gracefulStop: 30s)


running (00m05.2s), 0/2 VUs, 2 complete and 0 interrupted iterations
example_scenario ✓ [======================================] 1 VUs 00m00.2s/10m0s 1/1 shared iters
another_scenario ✓ [======================================] 1 VUs 00m00.2s/10m0s 1/1 shared iters

data_received..................: 54 kB 11 kB/s
data_sent......................: 2.5 kB 486 B/s
http_req_blocked...............: avg=53.45ms min=46.56ms med=48.42ms max=70.4ms p(90)=64.25ms p(95)=67.32ms
http_req_connecting............: avg=19.95ms min=18.62ms med=19.93ms max=21.3ms p(90)=21.26ms p(95)=21.28ms
http_req_duration..............: avg=46.16ms min=25.82ms med=45.6ms max=67.6ms p(90)=65.63ms p(95)=66.61ms
{ expected_response:true }...: avg=46.16ms min=25.82ms med=45.6ms max=67.6ms p(90)=65.63ms p(95)=66.61ms
http_req_failed................: 0.00% ✓ 0 ✗ 4
http_req_receiving.............: avg=3.56ms min=305.8µs med=3.05ms max=7.84ms p(90)=7.01ms p(95)=7.43ms
http_req_sending...............: avg=132.85µs min=0s med=0s max=531.4µs p(90)=371.98µs p(95)=451.68µs
http_req_tls_handshaking.......: avg=32.68ms min=27.63ms med=27.99ms max=47.09ms p(90)=41.43ms p(95)=44.26ms
http_req_waiting...............: avg=42.46ms min=24.78ms med=42.64ms max=59.75ms p(90)=58.45ms p(95)=59.1ms
http_reqs......................: 4 0.771306/s
iteration_duration.............: avg=199.23ms min=182.79ms med=199.23ms max=215.67ms p(90)=212.38ms p(95)=214.03ms
iterations.....................: 2 0.385653/s
vus............................: 0 min=0 max=0
vus_max........................: 2 min=2 max=2
scenarios: (100.00%) 2 scenarios, 30 max VUs, 10m40s max duration (incl. graceful stop):
* shared_iter_scenario: 100 iterations shared among 20 VUs (maxDuration: 10s, gracefulStop: 30s)
* per_vu_scenario: 20 iterations for each of 10 VUs (maxDuration: 10m0s, startTime: 10s, gracefulStop: 30s)


running (00m15.1s), 00/30 VUs, 300 complete and 0 interrupted iterations
shared_iter_scenario ✓ [======================================] 20 VUs 03.0s/10s 100/100 shared iters
per_vu_scenario ✓ [======================================] 10 VUs 00m05.1s/10m0s 200/200 iters, 20 per VU

data_received..................: 3.6 MB 240 kB/s
data_sent......................: 40 kB 2.6 kB/s
http_req_blocked...............: avg=54.48ms min=4.1µs med=8.23µs max=747.12ms p(90)=47.99ms p(95)=567.6ms
http_req_connecting............: avg=27.62ms min=0s med=0s max=281.12ms p(90)=26.86ms p(95)=279.32ms
http_req_duration..............: avg=210.21ms min=172.25ms med=204.01ms max=1.87s p(90)=206.18ms p(95)=306.99ms
{ expected_response:true }...: avg=210.21ms min=172.25ms med=204.01ms max=1.87s p(90)=206.18ms p(95)=306.99ms
http_req_failed................: 0.00% ✓ 0 ✗ 300
http_req_receiving.............: avg=1.77ms min=82.11µs med=149.11µs max=186.39ms p(90)=233.56µs p(95)=304.91µs
http_req_sending...............: avg=42.26µs min=10.68µs med=37.88µs max=220.62µs p(90)=47.68µs p(95)=70.59µs
http_req_tls_handshaking.......: avg=23.02ms min=0s med=0s max=410.87ms p(90)=20.91ms p(95)=230.64ms
http_req_waiting...............: avg=208.39ms min=172.02ms med=203.78ms max=1.69s p(90)=205.97ms p(95)=233.38ms
http_reqs......................: 300 19.886852/s
iteration_duration.............: avg=264.92ms min=172.48ms med=204.54ms max=1.87s p(90)=680.75ms p(95)=751.6ms
iterations.....................: 300 19.886852/s
vus............................: 1 min=0 max=20
vus_max........................: 30 min=30 max=30

```

</CodeGroup>

</Collapsible>
2 changes: 1 addition & 1 deletion ...nslated-guides/en/02 Using k6/14 Scenarios/01 Executors/01 shared-iterations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Note that iterations aren't fairly distributed with this executor, and a VU that

## Options

In addition to the [common configuration options](/using-k6/scenarios#common-options) this executor
In addition to the [common configuration options](/using-k6/scenarios#options) this executor
also adds the following options:

| Option | Type | Description | Default |
Expand Down
2 changes: 1 addition & 1 deletion ...nslated-guides/en/02 Using k6/14 Scenarios/01 Executors/02 per-vu-iterations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ iterations will be `vus * iterations`.

## Options

In addition to the [common configuration options](/using-k6/scenarios#common-options) this executor
In addition to the [common configuration options](/using-k6/scenarios#options) this executor
also adds the following options:

| Option | Type | Description | Default |
Expand Down
2 changes: 1 addition & 1 deletion ...n/translated-guides/en/02 Using k6/14 Scenarios/01 Executors/03 constant-vus.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ of time. This executor is equivalent to the global [vus](/using-k6/options#vus)

## Options

In addition to the [common configuration options](/using-k6/scenarios#common-options) this executor
In addition to the [common configuration options](/using-k6/scenarios#options) this executor
also adds the following options:

| Option | Type | Description | Default |
Expand Down
2 changes: 1 addition & 1 deletion ...wn/translated-guides/en/02 Using k6/14 Scenarios/01 Executors/04 ramping-vus.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ amount of time. This executor is equivalent to the global [stages](/using-k6/opt

## Options

In addition to the [common configuration options](/using-k6/scenarios#common-options) this executor
In addition to the [common configuration options](/using-k6/scenarios#options) this executor
also adds the following options:

| Option | Type | Description | Default |
Expand Down
2 changes: 1 addition & 1 deletion ...ted-guides/en/02 Using k6/14 Scenarios/01 Executors/05 constant-arrival-rate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ See the [arrival rate](/using-k6/scenarios/arrival-rate) section for details.

## Options

In addition to the [common configuration options](/using-k6/scenarios#common-options) this executor
In addition to the [common configuration options](/using-k6/scenarios#options) this executor
also adds the following options:

| Option | Type | Description | Default |
Expand Down
2 changes: 1 addition & 1 deletion ...ated-guides/en/02 Using k6/14 Scenarios/01 Executors/06 ramping-arrival-rate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ See the [arrival rate](/using-k6/scenarios/arrival-rate) section for details.

## Options

In addition to the [common configuration options](/using-k6/scenarios#common-options) this executor
In addition to the [common configuration options](/using-k6/scenarios#options) this executor
also adds the following options:

| Option | Type | Description | Default |
Expand Down
2 changes: 1 addition & 1 deletion ...ted-guides/en/02 Using k6/14 Scenarios/01 Executors/07 externally-controlled.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ maximum VUs will only affect the externally controlled executor.

## Options

In addition to the [common configuration options](/using-k6/scenarios#common-options) this executor
In addition to the [common configuration options](/using-k6/scenarios#options) this executor
also adds the following options:

| Option | Type | Description | Default |
Expand Down