gherkin: Having a Comment before a description breaks parsing

[enkessler]

Summary

The documentation states

"Comments are only permitted at the start of a new line, anywhere in the feature file. They begin with zero or more spaces, followed by a hash sign (#) and some text."

However, placing a comment before an element's description is not considered syntactically valid by the (Ruby) parser.

Expected Behavior

The following Gherkin would parse without error:

Feature:

  # TODO: make this not break
  description

Current Behavior

The parser throws an exception

sandbox/features/test.feature: (4:3): expected: #EOF, #Comment, #BackgroundLine, #TagLine, #ScenarioLine, #RuleLine, #Empty, got 'description' (Cucumber::Core::Gherkin::ParseError)

If the comment line is removed, the file parses without error.

Possible Solution

Fix the parser so that it matches the requirements/documentation.

Steps to Reproduce (for bugs)

1. Make a .feature file with the following text

Feature:

  # TODO: make this not break
  description

2. Have Cucumber try to run that feature file
3. See the parsing error

Context & Motivation

Feature files are source code of a sort. As such, comments may be useful/needed on any arbitrary line in the file.

Your Environment

• Version used: cucumber-gherkin Ruby gem, 14.0.1
• Operating System and version: Windows 10

[enkessler]

If I'm understanding the grammar, this bit is what allows empty lines and comment lines to appear in between any other line in the file:

IgnoredTokens -> #Comment,#Empty

The fact that none of the grammar rules for parts of the file that I know aren't impacted by comments bother to call out empty lines or comments at all lead me to suspect that the problem with having comments before a description block is caused by the description grammar rule itself:

// we need to explicitly mention comment, to avoid merging it into the description line's #Other token
// we also eat the leading empty lines, the tailing lines are not removed by the parser to avoid lookahead, this has to be done by the AST builder
DescriptionHelper := #Empty* Description? #Comment*
Description! := #Other+

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in a week if no further activity occurs.

[enkessler]

Giving this a bump.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in a week if no further activity occurs.

[jbullers]

Having the same problem. I encountered it because I'm trying to write some documentation for my company on how to use Cucumber on our project, and I wanted to pull sections of the feature files in to that documentation so that everything stays in sync. To do so, I need to add comments to the feature file and, as @enkessler showed above, this breaks parsing.

For example:

# tag::featureName[]
Feature: Some feature
# end::featureName[]
# tag::featureDescription[]
  description
# end::featureDescription[]

[source,gherkin]
----
include::foo.feature[tag=featureDescription]
----