improved documentation of @NestedSteps, changed appearence of nested …

…steps in the console report (#174)
TNG · Dec 12, 2015 · d296c24 · d296c24
1 parent 3e68ea9
commit d296c24
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 11 deletions.
diff --git a/jgiven-core/src/main/java/com/tngtech/jgiven/annotation/NestedSteps.java b/jgiven-core/src/main/java/com/tngtech/jgiven/annotation/NestedSteps.java
@@ -3,8 +3,35 @@
 import java.lang.annotation.*;
 
 /**
- * Marks a step method to have nested steps. 
+ * Marks a step method to have nested steps.
+ * <p>
+ *     Nested steps are useful if you want to group certain steps together under a new description.
+ *     This allows you to give a larger scenario more structure and make it better readable
+ *
+ * </p>
+ * <h2>Example</h2>
+ * Let's say you want to express that the registration form is filled with valid values, then you
+ * can do this as follows:
+ *
+ * <pre>
+ * {@literal @}NestedSteps
+ * public NestedStage I_fill_out_the_registration_form_with_valid_values() {
+ *    return I_enter_a_name( "Franky" )
+ *       .and().I_enter_a_password( "password1234" )
+ *       .and().I_enter_a_repeated_password( "password1234" );
+ * }
+ * </pre>
+ *
+ * The resulting console report will look as follows:
+ * <pre>
+ *    Given I fill out the registration form with valid values
+ *            I enter a name Franky
+ *            And I enter a email address franky@acme.com
+ *            And I enter a password password1234
+ *            And I enter a repeated password password1234
+ * </pre>
  * 
+ * In the HTML report nested steps can be expanded and collapsed
  * @since 0.10.0
  */
 @Documented

diff --git a/jgiven-core/src/main/java/com/tngtech/jgiven/base/StageBase.java b/jgiven-core/src/main/java/com/tngtech/jgiven/base/StageBase.java
@@ -18,6 +18,7 @@
  */
 public class StageBase<SELF extends StageBase<?>> {
 
+    @Hidden
     @SuppressWarnings( "unchecked" )
     public SELF self() {
         return (SELF) this;

diff --git a/jgiven-core/src/main/java/com/tngtech/jgiven/report/text/PlainTextScenarioWriter.java b/jgiven-core/src/main/java/com/tngtech/jgiven/report/text/PlainTextScenarioWriter.java
@@ -19,8 +19,8 @@
 
 public class PlainTextScenarioWriter extends PlainTextWriter {
     private static final String INDENT = "   ";
-    public static final String NESTED_HEADING = "|  ";
-    public static final String NESTED_INDENT = "|  ";
+    public static final String NESTED_HEADING = "  ";
+    public static final String NESTED_INDENT = "  ";
 
     protected ScenarioModel currentScenarioModel;
     protected ScenarioCaseModel currentCaseModel;

diff --git a/jgiven-core/src/test/java/com/tngtech/jgiven/report/text/PlainTextReporterTest.java b/jgiven-core/src/test/java/com/tngtech/jgiven/report/text/PlainTextReporterTest.java
@@ -120,8 +120,8 @@ public void nested_steps_are_displayed_in_the_report() throws Throwable {
                     + " Scenario: Test\n"
                     + "\n"
                     + "   Given something with nested steps\n"
-                    + "         |  Given something\n"
-                    + "         |  And something else\n"
+                    + "           Given something\n"
+                    + "           And something else\n"
                     + "    When something happens\n"
                     + "    Then something has happen\n"
                     + "         something else not"
@@ -150,10 +150,10 @@ public void multilevel_nested_steps_are_displayed_in_the_report() throws Unsuppo
                     + " Scenario: Test\n"
                     + "\n"
                     + "   Given something with multilevel nested steps\n"
-                    + "         |  Given something with nested steps\n"
-                    + "         |  |  Given something\n"
-                    + "         |  |  And something else\n"
-                    + "         |  And something further\n"
+                    + "           Given something with nested steps\n"
+                    + "             Given something\n"
+                    + "             And something else\n"
+                    + "           And something further\n"
                     + "    When something happens\n"
                     + "    Then something has happen\n"
                     + "         something else not"
@@ -177,8 +177,8 @@ public void nested_step_failures_appear_in_the_top_level_enclosing_step() throws
                     + " Scenario: Test\n"
                     + "\n"
                     + "   Given something with nested steps that fails (failed)\n"
-                    + "         |  Given something (passed)\n"
-                    + "         |  And something else that fails (failed)\n"
+                    + "           Given something (passed)\n"
+                    + "           And something else that fails (failed)\n"
                     + "    When something happens (skipped)\n"
                     + "    Then something has happen (skipped)\n"
                     + "         something else not (skipped)"