In this chapter, the authors introduce the first substantial feature file as a practical example of how BDD documentation is organized and written. The file centers on customer collection orders and demonstrates how a feature can be broken into related rules and scenarios that stay focused on one area of behavior. The emphasis is on readability and maintainability: feature files can be small or large, but they should always communicate the intended business behavior clearly to both technical and non-technical readers.
The chapter then explains the core Gherkin vocabulary and syntax needed to understand and write these files. It distinguishes between block keywords, such as Feature, Rule, Scenario, Scenario Outline, and Examples, and step keywords, such as Given, When, Then, And, and But. The text stresses that Gherkin is intentionally simple, but also strict: spacing, capitalization, and punctuation matter because the scenarios are meant to be processed by automation tools as well as read like natural language.
Finally, the chapter explores how to keep scenarios concise while still expressive. It shows how to decide whether something belongs in context, action, or outcome, and warns against including inessential details that weaken clarity and make scenarios brittle. It also introduces data tables, scenario outlines, and DocStrings as ways to represent repeated data, variations in behavior, and multiline text more readably. Throughout, the central message is that good BDD examples should be brief, essential, and easy to understand, with every extra detail justified by the rule being illustrated.
Summary
Gherkin has two types of keywords: block keywords and step keywords.
The step keywords are Given, When, Then, and two conjunctions, And and But.
Given sets up the context by describing the state the system is in before the behavior being illustrated is exhibited.
When describes the stimulus or event that causes the system to behave in a particular way. There should be only a single When step in a scenario.
Then describes expected outcome of the action. There should be only a single Then step in a scenario, unless the rule being illustrated results in multiple related outcomes.
The conjunctions And and But indicate a continuation when used after Given, When, or Then.
Gherkin keywords are available in multiple languages and its focus is to enable the writing of idiomatic natural language specifications.
The steps in an illustrative scenario should include only information that is essential to illustrating a specific rule.
Data table and scenario outlines can be used to make small variations in data easier to read and reason about.
The DocString construct is provided when you need to document long blocks of text within which whitespace is important.
FAQ
What is the purpose of a Gherkin feature file?A feature file organizes scenarios for a single area of functionality and acts as readable documentation that can also be automated by tools like Cucumber or Reqnroll.What keywords can start a Gherkin feature file?A feature file must start with the Feature: keyword. After that, it can include optional descriptive text, followed by rules and scenarios.What is the difference between Feature, Rule, and Scenario?Feature introduces the overall capability being described, Rule groups scenarios that illustrate a business rule, and Scenario describes one concrete example of system behavior.What do the Given, When, and Then steps represent?Given sets up the context, When describes the action that triggers the behavior, and Then states the expected outcome.Can a scenario have more than one Given, When, or Then step?Yes, but use them carefully. Multiple Given steps can provide necessary context, multiple Then steps can describe tightly related outcomes, but a scenario should usually have only one When step.When should And or But be used in Gherkin?And and But are conjunctions used to continue a previous step in a readable way. They behave like extensions of Given, When, or Then, and should be used when they improve clarity.Why should scenarios include only essential context?Because unnecessary context makes scenarios harder to understand and more brittle. A scenario should include only the state needed to illustrate the rule being tested.What is a scenario outline used for?A scenario outline is a template for generating several similar scenarios by substituting values from an Examples table. It is useful for data variations and similar behaviors.Why are data tables useful in feature files?Data tables make structured information easier to read than long sentences, especially for sets of values such as order details, price lists, or other related data associated with a step.When should a DocString be used in Gherkin?Use a DocString when you need to include multi-line text or preserve whitespace, such as an error message or other long block of text associated with a step.
pro $24.99 per month
access to all Manning books, MEAPs, liveVideos, liveProjects, and audiobooks!
Effective Behavior-Driven Development ebook for free
