fix(#40): scenarios can now contain descriptions

CHANGELOG.md

@@ -1,6 +1,7 @@
 ## [3.1.0] - 01/07/2022
+- Fix #40 scenarios can now contain descriptions
+- Json reporter: ensure exceptions, statuses and scenario descriptions are reported correctly
 - Changed reporter `maybeCall` to `invoke`
-- Json reporter: ensure exceptions and statuses are reported correctly
 
 ## [3.0.0+1] - 16/05/2022
 - Update configuration object constructor to take in additional configuration parameters

example/features/calculator_background_example.feature

@@ -7,5 +7,7 @@ Feature: Calculator with Background
     Given the numbers 100 and 50
     And they are added
 
+  @debug
   Scenario: Add two numbers with background
+    A scenario description!
     Then the expected result is 150

example/features/calculator_count_strings.feature

@@ -2,7 +2,6 @@
 Feature: Calculator can work with strings
   Tests that the calculator can count the total value of the character code units in a string
 
-  @debug
   Scenario Outline: Counts string's code units
     Given the characters "<characters>"
     When they are counted

example/test.dart

@@ -26,6 +26,7 @@ Future<void> main() {
       StdoutReporter(MessageLevel.error),
       ProgressReporter(),
       TestRunSummaryReporter(),
+      JsonReporter(),
     ],
     hooks: [HookExample()],
     customStepParameterDefinitions: [PowerOfTwoParameter()],

lib/src/feature_file_runner.dart

@@ -58,6 +58,7 @@ class FeatureFileRunner {
       await _reporter.feature.onStarted.invoke(
         FeatureMessage(
           name: feature.name,
+          description: feature.description,
           context: feature.debug,
           tags: feature.tags.isEmpty
               ? []
@@ -119,6 +120,7 @@ class FeatureFileRunner {
       await _reporter.feature.onFinished.invoke(
         FeatureMessage(
           name: feature.name,
+          description: feature.description,
           context: feature.debug,
         ),
       );
@@ -236,6 +238,7 @@ class FeatureFileRunner {
               ? Target.scenarioOutline
               : Target.scenario,
           name: scenario.name,
+          description: scenario.description,
           context: scenario.debug,
           tags: scenario.tags.isEmpty
               ? []
@@ -252,7 +255,7 @@ class FeatureFileRunner {
                         .toList(),
                   )
                   .reduce((a, b) => a..addAll(b))
-                  .toList(),
+                  .toList(growable: false),
         ),
       );
 
@@ -305,6 +308,7 @@ class FeatureFileRunner {
       await _reporter.scenario.onFinished.invoke(
         ScenarioMessage(
           name: scenario.name,
+          description: scenario.description,
           context: scenario.debug,
           hasPassed: scenarioPassed,
         ),

lib/src/gherkin/ast/feature_file_visitor.dart

@@ -37,8 +37,10 @@ class FeatureFileVisitor {
         for (final childScenario in allScenarios) {
           await visitScenario(
             feature.name,
+            feature.description,
             _tagsToList(feature.tags),
             childScenario.name,
+            childScenario.description,
             _tagsToList(childScenario.tags),
             path,
             isFirst: !acknowledgedScenarioPosition && isFirst,
@@ -82,8 +84,10 @@ class FeatureFileVisitor {
 
   Future<void> visitScenario(
     String featureName,
+    String? featureDescription,
     Iterable<String> featureTags,
     String name,
+    String? description,
     Iterable<String> tags,
     String path, {
     required bool isFirst,

lib/src/gherkin/runnables/background.dart

@@ -3,5 +3,5 @@ import 'scenario.dart';
 
 class BackgroundRunnable extends ScenarioRunnable {
   BackgroundRunnable(String name, RunnableDebugInformation debug)
-      : super(name, debug);
+      : super(name, null, debug);
 }

lib/src/gherkin/runnables/scenario.dart

@@ -5,15 +5,18 @@ import 'runnable.dart';
 import 'scenario_type_enum.dart';
 import 'step.dart';
 import 'taggable_runnable_block.dart';
+import 'text_line.dart';
 
 class ScenarioRunnable extends TaggableRunnableBlock {
   final String _name;
+  String? description;
   List<StepRunnable> steps = <StepRunnable>[];
 
   ScenarioType get scenarioType => ScenarioType.scenario;
 
   ScenarioRunnable(
     this._name,
+    this.description,
     RunnableDebugInformation debug,
   ) : super(debug);
 
@@ -26,6 +29,9 @@ class ScenarioRunnable extends TaggableRunnableBlock {
       case StepRunnable:
         steps.add(child as StepRunnable);
         break;
+      case TextLineRunnable:
+        description = (child as TextLineRunnable).text;
+        break;
       case CommentLineRunnable:
       case EmptyLineRunnable:
         break;

lib/src/gherkin/runnables/scenario_expanded_from_outline_example.dart

@@ -13,9 +13,14 @@ class ScenarioExpandedFromOutlineExampleRunnable extends ScenarioRunnable {
 
   ScenarioExpandedFromOutlineExampleRunnable(
     String name,
+    String? description,
     RunnableDebugInformation debug,
   )   : _name = name,
-        super(name, debug);
+        super(
+          name,
+          description,
+          debug,
+        );
 
   void setStepParameter(String parameterName, String value) {
     _name = _name.replaceAll('<$parameterName>', value);

lib/src/gherkin/runnables/scenario_outline.dart

@@ -13,8 +13,13 @@ class ScenarioOutlineRunnable extends ScenarioRunnable {
 
   ScenarioOutlineRunnable(
     String name,
+    String? description,
     RunnableDebugInformation debug,
-  ) : super(name, debug);
+  ) : super(
+          name,
+          description,
+          debug,
+        );
 
   @override
   void addChild(Runnable child) {
@@ -65,8 +70,11 @@ class ScenarioOutlineRunnable extends ScenarioRunnable {
 
             final clonedSteps = steps.map((step) => step.clone()).toList();
 
-            final scenarioRunnable =
-                ScenarioExpandedFromOutlineExampleRunnable(exampleName, debug);
+            final scenarioRunnable = ScenarioExpandedFromOutlineExampleRunnable(
+              exampleName,
+              description,
+              debug,
+            );
 
             exampleRow.forEach(
               (parameterName, value) {

lib/src/gherkin/syntax/scenario_outline_syntax.dart

@@ -37,6 +37,10 @@ class ScenarioOutlineSyntax
     GherkinDialect dialect,
   ) {
     final name = pattern(dialect).firstMatch(line)!.group(1)!;
-    return ScenarioOutlineRunnable(name.trim(), debug);
+    return ScenarioOutlineRunnable(
+      name.trim(),
+      null,
+      debug,
+    );
   }
 }

lib/src/gherkin/syntax/scenario_syntax.dart

@@ -35,7 +35,11 @@ class ScenarioSyntax extends RegExMatchedGherkinSyntax<ScenarioRunnable> {
     GherkinDialect dialect,
   ) {
     final name = pattern(dialect).firstMatch(line)!.group(1)!;
-    final runnable = ScenarioRunnable(name, debug);
+    final runnable = ScenarioRunnable(
+      name,
+      null,
+      debug,
+    );
 
     return runnable;
   }

lib/src/reporters/json/json_feature.dart

@@ -5,7 +5,7 @@ import 'json_tag.dart';
 class JsonFeature {
   final String uri;
   final String name;
-  final String description;
+  final String? description;
   final int line;
   final String? id;
   final Iterable<JsonTag> tags;
@@ -16,7 +16,7 @@ class JsonFeature {
     required this.uri,
     required this.name,
     required this.line,
-    this.description = '',
+    this.description,
     this.id,
     List<JsonScenario>? scenarios,
     Iterable<JsonTag>? tags,
@@ -29,6 +29,7 @@ class JsonFeature {
       uri: message.context.filePath,
       id: message.name.toLowerCase(),
       name: message.name,
+      description: message.description,
       line: message.context.nonZeroAdjustedLineNumber,
       tags: message.tags.map((t) => JsonTag.fromMessageTag(t)),
     );
@@ -66,14 +67,17 @@ class JsonFeature {
 
   Map<String, Object?> toJson() {
     final result = {
-      'description': description,
       'id': id,
       'keyword': 'Feature',
       'line': line,
       'name': name,
       'uri': uri,
     };
 
+    if (description?.isNotEmpty ?? false) {
+      result['description'] = description;
+    }
+
     if (tags.isNotEmpty) {
       result['tags'] = tags.toList();
     }

lib/src/reporters/json/json_scenario.dart

@@ -14,8 +14,7 @@ class JsonScenario {
   /// Scenario name
   final String name;
 
-  /// Optional description. Default: ''
-  final String description;
+  final String? description;
 
   final int line;
 
@@ -45,12 +44,11 @@ class JsonScenario {
   /// Scenario steps
   List<JsonStep> steps;
 
-  //TODO(Shigomany): Make immutable class (final feature)
   JsonScenario({
     required this.target,
     required this.name,
     required this.line,
-    this.description = '',
+    this.description,
     this.feature,
     this.passed,
     List<JsonStep>? steps,
@@ -67,6 +65,7 @@ class JsonScenario {
   static JsonScenario from(ScenarioMessage message) => JsonScenario(
         target: message.target,
         name: message.name,
+        description: message.description,
         line: message.context.nonZeroAdjustedLineNumber,
         passed: message.hasPassed,
         tags: message.tags
@@ -104,11 +103,14 @@ class JsonScenario {
       'type': 'scenario',
       'id': '${feature?.id};${name.toLowerCase()}',
       'name': name,
-      'description': description,
       'line': line,
       'status': _calculateStatus()
     };
 
+    if (description?.isNotEmpty ?? false) {
+      result['description'] = description!;
+    }
+
     if (tags.isNotEmpty) {
       result['tags'] = tags.toList();
     }

lib/src/reporters/messages/feature/feature_message.dart

@@ -6,12 +6,14 @@ part of '../messages.dart';
 class FeatureMessage extends ActionMessage {
   /// Gherkin format tags
   final List<Tag> tags;
+  final String? description;
 
   /// {@macro messages.featuremessage}
   FeatureMessage({
     required String name,
     required RunnableDebugInformation context,
     this.tags = const [],
+    this.description,
   }) : super(
           target: Target.feature,
           name: name,
@@ -22,11 +24,13 @@ class FeatureMessage extends ActionMessage {
     String? name,
     RunnableDebugInformation? context,
     List<Tag>? tags,
+    String? description,
   }) {
     return FeatureMessage(
       name: name ?? this.name,
       context: context ?? this.context,
       tags: tags ?? this.tags,
+      description: description ?? this.description,
     );
   }
 }

lib/src/reporters/messages/scenario/scenario_message.dart

@@ -10,13 +10,16 @@ class ScenarioMessage extends ActionMessage {
   /// Gherkin format tags
   final List<Tag> tags;
 
+  final String? description;
+
   /// {@macro messages.scenariomessage}
   ScenarioMessage({
     required String name,
     required RunnableDebugInformation context,
-    Target target = Target.scenario,
+    this.description,
     this.hasPassed = false,
     this.tags = const [],
+    Target target = Target.scenario,
   }) : super(
           target: target,
           name: name,
@@ -25,6 +28,7 @@ class ScenarioMessage extends ActionMessage {
 
   ScenarioMessage copyWith({
     String? name,
+    String? description,
     RunnableDebugInformation? context,
     bool? hasPassed,
     List<Tag>? tags,
@@ -33,6 +37,7 @@ class ScenarioMessage extends ActionMessage {
     return ScenarioMessage(
       target: target ?? this.target,
       name: name ?? this.name,
+      description: description ?? this.description,
       context: context ?? this.context,
       hasPassed: hasPassed ?? this.hasPassed,
       tags: tags ?? this.tags,