provide option to only run a configurable number of iterations of Scenarios

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Changelog
 
 ## 0.16.2-dev
+ - [#477](https://github.com/tag1consulting/goose/pull/477) introduce `--iterations` (and `GooseDefault::Iterations`) which configures each GooseUser to run a configurable number of iterations of the assigned Scenario then exit; introduces Scenario metrics which can be disabled with `--no-scenario-metrics` (`GooseDefault::NoScenarioMetrics`); introduces `--scenario-log` and `--scenario-format` (and `GooseDefault::ScenarioLog` and `GooseDefault::ScenarioFormat`)
 
 ## 0.16.1 May 12, 2022
  - [#464](https://github.com/tag1consulting/goose/pull/464) add `startuptime` (and `startup_time`) TIME to controllers, setting how long the load test should spend starting configured number of users

src/docs/goose-book/src/SUMMARY.md

@@ -6,7 +6,7 @@
 
 - [Getting Started](getting-started/overview.md)
     - [Creating A Load test](getting-started/creating.md)
-    - [Validating requests](getting-started/validation.md)
+    - [Validating Requests](getting-started/validation.md)
     - [Running A Load Test](getting-started/running.md)
     - [Run-Time Options](getting-started/runtime-options.md)
         - [Common Options](getting-started/common.md)
@@ -18,6 +18,7 @@
 - [Logging](logging/overview.md)
     - [Request Log](logging/requests.md)
     - [Transaction Log](logging/transactions.md)
+    - [Scenario Log](logging/scenarios.md)
     - [Error Log](logging/errors.md)
     - [Debug Log](logging/debug.md)
 

src/docs/goose-book/src/controller/telnet.md

@@ -82,7 +82,7 @@ Initially the load test is configured with a hatch rate of 50, so goose increase
 
 The above commands are also summarized in the metrics overview:
 
-```
+```ignore
  === OVERVIEW ===
  ------------------------------------------------------------------------------
  Action       Started               Stopped             Elapsed    Users

src/docs/goose-book/src/getting-started/common.md

@@ -6,7 +6,7 @@ As seen on the previous page, Goose has a lot of run time options which can be o
 
 Load test plans typically contain relative paths, and so Goose must be told which host to run the load test against in order for it to start. This allows a single load test plan to be used for testing different environments, for example "http://local.example.com", "https://qa.example.com", and "https://www.example.com".
 
-### Example
+### Host example
 _Load test the https://www.example.com domain._
 
 ```bash
@@ -17,7 +17,9 @@ cargo run --release -- -H https://www.example.com
 
 By default, Goose will launch one user per available CPU core. Often you will want to simulate considerably more users than this, and this can be done by setting the "--user" run time option.
 
-### Example
+(_Alternatively, you can use [`--test-plan`](./test-plan.html) to build both simple and more complex traffic patterns that can include a varying number of users._)
+
+### Users example
 _Launch 1,000 GooseUsers._
 
 ```bash
@@ -26,13 +28,15 @@ cargo run --release -- -u 1000
 
 ## Controlling how long it takes Goose to launch all users
 
-There are two ways to configure how long Goose will take to launch all configured GooseUsers. You can user either `--hatch-rate` or `--startup-time`, but not both together.
+There are several ways to configure how long Goose will take to launch all configured GooseUsers. For starters, you can user either `--hatch-rate` or `--startup-time`, but not both together. Alternatively, you can use [`--test-plan`](./test-plan.html) to build both simple and more complex traffic patterns that can include varying launch rates.
 
 ### Specifying the hatch rate
 
 By default, Goose starts one GooseUser per second. So if you configure `--users` to 10 it will take ten seconds to fully start the load test. If you set `--hatch-rate 5` then Goose will start 5 users every second, taking two seconds to start up. If you set `--hatch-rate 0.5` then Goose will start 1 user every 2 seconds, taking twenty seconds to start all 10 users.
+
+(_The configured hatch rate is a best effort limit, Goose will not start users faster than this but there is no guarantee that your load test server is capable of starting users as fast as you configure._)
 
-### Example
+### Hatch rate example
 _Launch one user every two seconds._
 
 ```bash
@@ -43,7 +47,9 @@ cargo run --release -- -r .5
 
 Alternatively, you can tell Goose how long you'd like it to take to start all GooseUsers. So, if you configure `--users` to 10 and set `--startup-time 10` it will launch 1 user every second. If you set `--startup-time 1m` it will start 1 user every 6 seconds, starting all users over one minute. And if you set `--startup-time 2s` it will launch five users per second, launching all users in two seconds.
 
-### Example
+(_The configured startup time is a best effort limit, Goose will not start users faster than this but there is no guarantee that your load test server is capable of starting users as fast as you configure._)
+
+### Startup time example
 _Launch all users in 5 seconds._
 
 ```bash
@@ -54,15 +60,26 @@ cargo run --release -- -s 5
 
 The `--run-time` option is not affected by how long Goose takes to start up. Thus, if you configure a load test with `--users 100 --startup-time 30m --run-time 5m` Goose will run for a total of 35 minutes, first ramping up for 30 minutes and then running at full load for 5 minutes. If you want Goose to exit immediately after all users start, you can set a very small run time, for example `--users 100 --hatch-rate .25 --run-time 1s`.
 
+Alternatively, you can use [`--test-plan`](./test-plan.html) to build both simple and more complex traffic patterns and can define how long the load test runs.
+
+A final option is to instead use the `--iterations` option to configure how many times GooseUsers will run through their assigned Scenario before exiting.
+
 If you do not configure a run time, Goose will run until it's canceled with `ctrl-c`.
 
-### Example
+### Run time example
 _Run the load test for 30 minutes._
 
 ```bash
 cargo run --release -- -t 30m
 ```
 
+### Iterations example
+_Each GooseUser will take as long as it takes to fully run its assigned Scenario 5 times and then stop._
+
+```bash
+cargo run --release -- --iterations 5
+```
+
 ## Writing An HTML-formatted Report
 
 By default, Goose displays [text-formatted metrics](metrics.md) when a load test finishes. It can also optionally write an HTML-formatted report if you enable the `--report-file <NAME>` run-time option, where `<NAME>` is an absolute or relative path to the report file to generate. Any file that already exists at the specified path will be overwritten.
@@ -71,7 +88,7 @@ The HTML report includes some graphs that rely on the [eCharts JavaScript librar
 
 ![Requests per second graph](rps.png)
 
-### Example
+### HTML report example
 _Write an HTML-formatted report to `report.html` when the load test finishes._
 
 ```bash

src/docs/goose-book/src/getting-started/creating.md

@@ -1,5 +1,7 @@
 # Creating A Load Test
 
+## Cargo
+
 [Cargo](https://doc.rust-lang.org/cargo/) is the Rust package manager. To create a new load test, use Cargo to create a new application (you can name your application anything, we've generically selected `loadtest`):
 
 ```bash
@@ -30,6 +32,8 @@ $ cargo run
 Hello, world!
 ```
 
+## Creating the load test
+
 To create an actual load test, you first have to add the following boilerplate to the top of `src/main.rs` to make Goose's functionality available to your code:
 
 ```rust,ignore