Added the ability to comment on steps.

This commit allows commenting on a step by calling comment() after invoking
the corresponding step method. Furthermore, it displays said comment in
the plain text report, if one was given.

relates to TNG#50

CHANGELOG.md

@@ -1,6 +1,7 @@
 # v0.12.0
 
 * Allow multiple formatter annotations on arguments, e.g., "@Quoted @YesNo", see [#204](https://github.com/TNG/JGiven/issues/204).
+* Added a new comment() method to provide further information on specific step method invocations, see [#50](https://github.com/TNG/JGiven/issues/50).
 
 # v0.11.4
 

jgiven-core/src/main/java/com/tngtech/jgiven/Stage.java

@@ -1,6 +1,7 @@
 package com.tngtech.jgiven;
 
 import com.tngtech.jgiven.annotation.IntroWord;
+import com.tngtech.jgiven.annotation.StepComment;
 import com.tngtech.jgiven.base.StageBase;
 
 /**
@@ -42,4 +43,9 @@ public SELF but() {
         return self();
     }
 
+    @StepComment
+    public SELF comment( String comment ) {
+        return self();
+    }
+
 }

jgiven-core/src/main/java/com/tngtech/jgiven/annotation/StepComment.java

@@ -0,0 +1,28 @@
+package com.tngtech.jgiven.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Marks a method to be used to provide an additional comment to the previous step.
+ * This optional comment can be used by reporters for the output.
+ *
+ * A step comment is intended to provide additional information about a specific step
+ * invocation, e.g., because it might be surprising that the step is required. If you
+ * want to provide a more detailed description of a step method in general, refer to
+ * {@link ExtendedDescription}.
+ *
+ * A method decorated with this annotation is expected to take exactly one argument of
+ * type {@link String}.
+ *
+ * @since 0.12.0
+ */
+@Documented
+@Retention( RetentionPolicy.RUNTIME )
+@Target( ElementType.METHOD )
+public @interface StepComment {
+
+}

jgiven-core/src/main/java/com/tngtech/jgiven/impl/ScenarioModelBuilder.java

@@ -141,6 +141,24 @@ public void introWordAdded( String value ) {
         introWord.setValue( value );
     }
 
+    @Override
+    public void stepCommentAdded( List<NamedArgument> arguments ) {
+        if( arguments == null || arguments.size() != 1 ) {
+            throw new JGivenWrongUsageException( "A step comment method must have exactly one parameter." );
+        }
+
+        if( !( arguments.get( 0 ).getValue() instanceof String ) ) {
+            throw new JGivenWrongUsageException( "The step comment method parameter must be a string." );
+        }
+
+        if( currentStep == null ) {
+            throw new JGivenWrongUsageException( "A step comment must be added after the corresponding step, "
+                    + "but no step has been executed yet." );
+        }
+
+        currentStep.setComment( (String) arguments.get( 0 ).getValue() );
+    }
+
     private ScenarioCaseModel getCurrentScenarioCase() {
         if( scenarioCaseModel == null ) {
             scenarioStarted( "A Scenario" );
@@ -152,6 +170,8 @@ private ScenarioCaseModel getCurrentScenarioCase() {
     public void stepMethodInvoked( Method method, List<NamedArgument> arguments, InvocationMode mode, boolean hasNestedSteps ) {
         if( method.isAnnotationPresent( IntroWord.class ) ) {
             introWordAdded( getDescription( method ) );
+        } else if( method.isAnnotationPresent( StepComment.class ) ) {
+            stepCommentAdded( arguments );
         } else {
             addStepMethod( method, arguments, mode, hasNestedSteps );
         }

jgiven-core/src/main/java/com/tngtech/jgiven/impl/intercept/NoOpScenarioListener.java

@@ -24,6 +24,9 @@ public void stepMethodInvoked( Method method, List<NamedArgument> arguments, Inv
     @Override
     public void introWordAdded( String introWord ) {}
 
+    @Override
+    public void stepCommentAdded( List<NamedArgument> arguments ) {}
+
     @Override
     public void stepMethodFailed( Throwable t ) {}
 

jgiven-core/src/main/java/com/tngtech/jgiven/impl/intercept/ScenarioListener.java

@@ -19,6 +19,8 @@ public interface ScenarioListener {
 
     void introWordAdded( String introWord );
 
+    void stepCommentAdded( List<NamedArgument> arguments );
+
     void stepMethodFailed( Throwable t );
 
     void stepMethodFinished( long durationInNanos, boolean hasNestedSteps );

jgiven-core/src/main/java/com/tngtech/jgiven/lang/de/Stufe.java

@@ -1,14 +1,14 @@
 package com.tngtech.jgiven.lang.de;
 
 import com.tngtech.jgiven.annotation.IntroWord;
+import com.tngtech.jgiven.annotation.StepComment;
 import com.tngtech.jgiven.base.StageBase;
 
 /**
  * Eine deutsche Version der {@link com.tngtech.jgiven.Stage}-Klasse.
  */
 public class Stufe<SELF extends Stufe<?>> extends StageBase<SELF> {
 
-
     @IntroWord
     public SELF angenommen() {
         return self();
@@ -44,4 +44,9 @@ public SELF mit() {
         return self();
     }
 
+    @StepComment
+    public SELF kommentiere( String kommentar ) {
+        return self();
+    }
+
 }

jgiven-core/src/main/java/com/tngtech/jgiven/report/model/StepModel.java

@@ -57,6 +57,14 @@ public class StepModel {
      */
     private Boolean isSectionTitle;
 
+    /**
+     * An optional comment for this step.
+     * Can be {@code null}.
+     *
+     * @since 0.12.0
+     */
+    private String comment;
+
     public StepModel() {
     }
 
@@ -122,6 +130,14 @@ public void setExtendedDescription( String extendedDescription ) {
         this.extendedDescription = extendedDescription;
     }
 
+    public String getComment() {
+        return comment;
+    }
+
+    public void setComment( String comment ) {
+        this.comment = comment;
+    }
+
     public List<Word> getWords() {
         return Collections.unmodifiableList( words );
     }
@@ -224,4 +240,4 @@ public boolean hasInlineAttachment() {
     public boolean hasAttachment() {
         return !getAttachments().isEmpty();
     }
-}
+}

jgiven-core/src/main/java/com/tngtech/jgiven/report/text/PlainTextScenarioWriter.java

@@ -126,6 +126,10 @@ private void printStep( StepModel stepModel, int depth, boolean showPassed ) {
             line = green( line + " (passed)" );
         }
 
+        if( !Strings.isNullOrEmpty( stepModel.getComment() ) ) {
+            line = line + gray( String.format( " [%s]", stepModel.getComment() ) );
+        }
+
         writer.println( line );
 
         printNestedSteps( stepModel, depth, showPassed );