In a Cucumber .feature file, which lines does the Gherkin parser treat as keywords, and what happens to a line that matches none?

## The lines Gherkin treats as keywords A `.feature` file is not free prose with some keywords sprinkled in. Cucumber parses it with the Gherkin parser, which recognises a **closed vocabulary** and gives every other line one of exactly two fates. In the English dialect the recognised line starts are: | Line begins with | Gherkin calls it | Where it is legal | |---|---|---| | `Feature:` | the feature header | once per file, at the top | | `Rule:` | a business-rule grouping | between `Feature` and its scenarios | | `Background:` | shared setup steps | once per `Feature`, once per `Rule`, before that container's scenarios | | `Scenario:` / `Example:` | one concrete example | under `Feature` or under `Rule` | | `Scenario Outline:` / `Scenario Template:` | a parameterised scenario | same places as `Scenario` | | `Examples:` / `Scenarios:` | the rows of an outline | under the outline it belongs to | | `Given` `When` `Then` `And` `But` `*` | step keywords | inside `Background`, `Scenario` or an outline | | `@` | a tag line | on its own line above `Feature`, `Rule`, a scenario or `Examples` | | `#` | a whole-line comment | anywhere | | `\|` | a table row | as a step argument or inside `Examples` | | `"""` or triple backticks | a doc-string delimiter | directly under a step | `Scenario` and `Example` are synonyms, as are `Examples` and `Scenarios`, and `Scenario Outline` and `Scenario Template`. The step keyword is **not** part of what a step definition matches — it is stripped before matching — which is why `Given`, `And` and `*` are interchangeable to the glue layer and matter only to the human reader. ## The structural rules the parser enforces 1. **One `Feature` per file.** A second `Feature:` line is a parse error, not a second feature. If a merge leaves two of them in one file, split the file. 2. **`Background` is positional.** At most one per container, and it must come before the first scenario of that container. A `Background` written after a scenario fails to parse. 3. **Steps need a home.** A `Given`/`When`/`Then` line before any `Background` or scenario has nothing to attach to and fails. 4. **Comments are whole-line only.** The `#` must be the first non-whitespace character on the line. Gherkin has no trailing-comment syntax, so `When the cut-off passes # 09:47` is a step whose text ends in `# 09:47`, and your step definition now has to match that. 5. **Tags live on their own line** above the element they decorate; a tag written after text on a keyword line is not a tag. ## What happens to a line that matches nothing Gherkin allows **free-form description text** in one position: immediately after a `Feature:`, `Rule:`, `Background:`, scenario or `Examples:` line, running until the next keyword line. Those lines are kept as that element's description and are never executed. This is where the narrative belongs — the paragraph explaining who the feature is for, or a link to the rule it implements. Anywhere else, an unrecognised line is a **parse error**. The parser reports the file, the line and the kinds of token it expected there, and that file does not run. The failure is a *reading* failure, so it happens before any scenario starts: you do not get "one bad scenario, the rest pass". That is the single most useful thing to know about this rule, because the instinct — carried over from languages where an unknown line is a comment or a no-op — is that Cucumber will simply skip it. ## Why it bites on a shared suite Consider a school-meal ordering service whose feature files are edited by both the platform team and the kitchen-operations team. Someone pastes a two-line note between the `When` and the `Then` of a scenario to explain a cut-off time. Locally nothing looks wrong; the file is still readable English. On CI the whole file stops parsing, and because the run fails at discovery the report shows no scenario results at all — which reads like an infrastructure problem rather than a syntax one. The fix is a one-character edit: put a `#` in front of the note, or move it into the description block under `Scenario:`. Two habits keep this cheap: - **Parse in CI on every change** to the feature directory, so a malformed file is caught by the build rather than by whoever runs the suite next. - **Teach the description block.** Non-engineers editing feature files want to write prose; give them the one legal place for it instead of relying on them to remember which lines are keywords. ## Checking yourself The compact way to hold this: Gherkin is closer to a **form with named fields** than to prose. Each keyword opens a field, the parser knows which fields may follow which, and the only free text it accepts is the description blank each field leaves for you. Everything else is either a step, a table row, a tag, a comment, a doc-string delimiter — or an error that stops the file.