Rework verbosity CLI option (#193, #192)

- make `-v` default behavior (no additional output)
- make `-vv` additionally output `World` on failed steps
- make `-vvv` additionally output docstrings (old behavior)
- add `--junit-v` CLI option for `writer::JUnit`

Co-authored-by: Kai Ren <tyranron@gmail.com>

CHANGELOG.md

@@ -20,6 +20,11 @@ All user visible changes to `cucumber` crate will be documented in this file. Th
 - Switch to [`gherkin`] crate instead of [`gherkin_rust`]. ([rev])
 - Renamed `@allow_skipped` built-in tag to `@allow.skipped`. ([#181])
 - Switched CLI to `clap` from `structopt`. ([#188])
+- Reworked `verbose` CLI option of `writer::Basic`: ([#193], [#192])
+    - Removed long form.
+    - Made `-v` default behavior (no additional output). 
+    - Made `-vv` additionally output `World` on failed steps. 
+    - Made `-vvv` additionally output docstrings (old behavior). 
 
 ### Added
 
@@ -62,6 +67,8 @@ All user visible changes to `cucumber` crate will be documented in this file. Th
 [#181]: /../../pull/181
 [#182]: /../../pull/182
 [#188]: /../../pull/188
+[#192]: /../../pull/192
+[#193]: /../../pull/193
 [cef3d480]: /../../commit/cef3d480579190425461ddb04a1248675248351e
 [rev]: /../../commit/rev-full
 [0110-1]: https://llg.cubic.org/docs/junit

book/src/cli.md

@@ -44,8 +44,11 @@ OPTIONS:
             Note: Tags from Feature, Rule and Scenario are merged together on filtering, so be
             careful about conflicting tags on different levels.
 
-    -v, --verbose
-            Increased verbosity of an output: additionally outputs step's doc string (if present)
+    -v
+            Verbosity of an output.
+            
+            `-v` is default verbosity, `-vv` additionally outputs world on failed steps, `-vvv`
+            additionally outputs step's doc string (if present).
 ```
 
 ![record](rec/cli.gif)

book/src/output/junit.md

@@ -32,7 +32,7 @@ use cucumber::writer;
 # async fn main() -> io::Result<()> {
 let file = fs::File::create(dbg!(format!("{}/target/junit.xml", env!("CARGO_MANIFEST_DIR"))))?;
 World::cucumber()
-    .with_writer(writer::JUnit::new(file))
+    .with_writer(writer::JUnit::new(file, 0))
     .run("tests/features/book")
     .await;
 # Ok(())

book/src/output/terminal.md

@@ -8,7 +8,79 @@ By [default][1], [`cucumber`] crate outputs tests result to [STDOUT]. It provide
 
 ## Verbosity
 
-By [default][1], [`cucumber`] crate omits outputting [doc strings][doc] of [step]s. To include them into the output use `--verbose` CLI option:
+By [default][1], [`cucumber`] crate tries to keep the output quite minimal, but its verbosity may be increased with `-v` CLI option.
+
+Just specifying `-v` makes no difference, as it refers to the default verbosity level (no additional info).
+
+
+### Output `World` on failures (`-vv`)
+
+Increasing verbosity level with `-vv` CLI option, makes the state of the `World` being printed at the moment of failure.
+
+```rust,should_panic
+# use std::{convert::Infallible, time::Duration};
+#
+# use async_trait::async_trait;
+# use cucumber::{given, then, when, World, WorldInit};
+# use tokio::time::sleep;
+#
+# #[derive(Debug, Default)]
+# struct Animal {
+#     pub hungry: bool,
+# }
+#
+# #[derive(Debug, WorldInit)]
+# pub struct AnimalWorld {
+#     cat: Animal,
+# }
+#
+# #[async_trait(?Send)]
+# impl World for AnimalWorld {
+#     type Error = Infallible;
+#
+#     async fn new() -> Result<Self, Infallible> {
+#         Ok(Self {
+#             cat: Animal::default(),
+#         })
+#     }
+# }
+#
+# #[given(regex = r"^a (hungry|satiated) cat$")]
+# async fn hungry_cat(world: &mut AnimalWorld, state: String) {
+#     sleep(Duration::from_secs(2)).await;
+#
+#     match state.as_str() {
+#         "hungry" => world.cat.hungry = true,
+#         "satiated" => world.cat.hungry = false,
+#         _ => unreachable!(),
+#     }
+# }
+#
+#[when("I feed the cat")]
+async fn feed_cat(_: &mut AnimalWorld) {}
+#
+# #[then("the cat is not hungry")]
+# async fn cat_is_fed(world: &mut AnimalWorld) {
+#     sleep(Duration::from_secs(2)).await;
+#
+#     assert!(!world.cat.hungry);
+# }
+#
+# #[tokio::main]
+# async fn main() {
+#     AnimalWorld::cucumber()
+#         .run_and_exit("/tests/features/book/output/terminal_verbose.feature")
+#         .await;
+# }
+```
+![record](../rec/output_terminal_verbose_1.gif)
+
+This is intended to help debugging failed tests. 
+
+
+### Output [doc strings][doc] (`-vvv`)
+
+By [default][1], outputting [doc strings][doc] of [step]s is omitted. To include them into the output use `-vvv` CLI option:
 ```gherkin
 Feature: Animal feature
     
@@ -87,7 +159,7 @@ async fn main() {
         .await;
 }
 ```
-![record](../rec/output_terminal_verbose.gif)
+![record](../rec/output_terminal_verbose_2.gif)
 
 
 
@@ -311,7 +383,7 @@ async fn main() {
     AnimalWorld::cucumber()
         .max_concurrent_scenarios(1)
         .with_writer(
-            writer::Basic::raw(io::stdout(), writer::Coloring::Never, false)
+            writer::Basic::raw(io::stdout(), writer::Coloring::Never, 0)
                 .summarized()
                 .assert_normalized(),
         )

book/src/quickstart.md

@@ -540,4 +540,3 @@ Feature: Animal feature
 [scenario]: https://cucumber.io/docs/gherkin/reference#example
 [step]: https://cucumber.io/docs/gherkin/reference#steps
 [tag]: https://cucumber.io/docs/cucumber/api#tags
-[1]: 

book/src/writing/asserting.md

@@ -65,12 +65,16 @@ fn cat_is_fed(_: &mut AnimalWorld) {
 #
 # #[tokio::main]
 # async fn main() {
-#     AnimalWorld::run_and_exit("/tests/features/book/writing/asserting.feature").await;
+#     AnimalWorld::cucumber()
+#         .run_and_exit("/tests/features/book/writing/asserting.feature")
+#         .await;
 # }
 ```
 ![record](../rec/writing_asserting_panic.gif)
 
-> __NOTE__: Failed [step] prints its location in a `.feature` file, the captured [assertion] message, and state of the `World` at the moment of failure.
+> __NOTE__: Failed [step] prints its location in a `.feature` file and the captured [assertion] message.
+
+> __TIP__: To additionally print the state of the `World` at the moment of failure, increase output verbosity via `-vv` [CLI] option.
 
 
 
@@ -124,7 +128,9 @@ fn cat_is_fed(world: &mut AnimalWorld) -> Result<(), &'static str> {
 #
 # #[tokio::main]
 # async fn main() {
-#     AnimalWorld::run_and_exit("/tests/features/book/writing/asserting.feature").await;
+#     AnimalWorld::cucumber()
+#         .run_and_exit("/tests/features/book/writing/asserting.feature")
+#         .await;
 # }
 ```
 ![record](../rec/writing_asserting_result.gif)
@@ -134,5 +140,6 @@ fn cat_is_fed(world: &mut AnimalWorld) -> Result<(), &'static str> {
 
 [`Display`]: https://doc.rust-lang.org/stable/std/fmt/trait.Display.html
 [assertion]: https://en.wikipedia.org/wiki/Assertion_(software_development)
+[CLI]: ../cli.md
 [step]: https://cucumber.io/docs/gherkin/reference#steps
 [1]: https://doc.rust-lang.org/rust-by-example/testing/unit_testing.html#tests-and-

book/src/writing/doc_strings.md

@@ -115,7 +115,9 @@ async fn hungry_cat(world: &mut AnimalWorld, step: &Step, state: String) {
 #
 # #[tokio::main]
 # async fn main() {
-#     AnimalWorld::run("/tests/features/book/writing/doc_strings.feature").await;
+#     AnimalWorld::cucumber()
+#         .run_and_exit("/tests/features/book/writing/doc_strings.feature")
+#         .await;
 # }
 ```
 ![record](../rec/writing_doc_strings.gif)