Chapter 8: Formulating a feature
Introduces feature files as Gherkin’s way of grouping related scenarios into readable documentation.
After this chapter you will be able to
- Cohesive feature file organization. Explain that Gherkin scenarios are organized into feature files, and that each file should focus on one area of functionality so its scenarios form readable, cohesive documentation.
- Example map to feature file. Trace how the team turned its example map into scenarios collected in a feature file, replacing the old scenario.
- Gherkin’s dual purpose. Explain why Gherkin combines natural-language readability with enough structure for automation tools to process its documentation.
- Block and step keyword distinction. Distinguish block keywords from step keywords by their colon requirement, and describe how descriptive text can follow a block keyword.
- Feature and behavior blocks. Describe what Feature, Background, Rule, and Scenario introduce or describe in a feature file.
- Context action and outcome steps. Describe what Given, When, and Then express, and how And and But combine steps readably.
- Multilingual Gherkin keywords. Explain that Gherkin keywords are available in over 70 languages, that some languages offer multiple variants of a keyword, and why teams should use their organization’s business language.
- Exact scenario text conventions. Explain why spaces, punctuation, and capitalization must be consistent in scenarios, using the section’s examples of correct keyword formatting.
- Feature block structure. Describe how a feature file begins and where its name and overview go.
- Descriptive text maintenance. Explain why a team must keep feature descriptions and other extra background information up to date.
- Rule and scenario association. Explain how a Rule block documents a discovery rule and determines which scenarios illustrate it, including where scenarios without a rule must appear.
- Scenario purpose and naming. Explain that a Scenario block formulates a concrete example discussed during discovery, should illustrate its containing Rule, and should have a descriptive name.
- Given When Then structure. Describe how a scenario's steps express the context, triggering action, and expected outcome of an example using Given, When, and Then.
- Separate essential context steps. Explain why a scenario may use And to extend a Given with another essential piece of context, rather than combine both into one step.
- Essential scenario context. Apply the test of whether a reader needs each context step to understand the rule being illustrated, removing steps that do not pass it. Explain why basket contents need not appear in a scenario whose rule does not depend on them.
- Readability over automation convenience. Justify leaving inessential setup out of scenario text even when automation must perform it, using the effects on readability and maintenance.
- Context and trigger distinction. Distinguish Given context, the When action, and the Then outcome in the collection-order example. Explain how the business’s validation sequence determines whether providing unacceptable contact details or choosing collection is the triggering action.
- Tightly coupled scenario outcomes. Explain why a scenario normally has one outcome step but may need several when the outcomes are tightly bound to the same rule.
- Alternatives within scenario steps. Explain why an “or” within a step makes the example non-deterministic and how to revise the scenario.
- Purpose and optionality of tables. Explain that Gherkin includes data tables and examples tables to improve the readability of feature files, but any scenario can be written without tables.
- Data tables and steps. Explain that a data table presents structured information as a two-dimensional grid attached to the preceding step, making information such as order details or a pricelist easier to read than prose.
- Scenario outline expansion. Explain how an examples table turns a scenario outline into separate scenarios and why this can be more readable than repeating similar scenarios.
- Tabular data variations. Explain why tables of examples are a natural way to describe calculations and data-driven validation, including acceptable input permutations.
- Value and cost of example rows. Justify checking what distinct behavior each example row illustrates before adding or retaining it, using the performance story as evidence.
- Scenario outline readability. Explain when to consider replacing similar scenarios with a scenario outline and why readability, rather than brevity alone, should determine the choice.
- Readable table size. Explain why data and examples tables should stay small, and describe the screen-fit rule of thumb for a scenario or scenario outline.
- Readable Gherkin docstrings. Explain when to use a Gherkin docstring and how it represents formatted text for a scenario step.
What it builds on
- Gherkin overview (chapter 6) · The introduction to Gherkin as a format for scenarios.
- Using example maps to provide focus (chapter 7) · The example map used to focus the replacement scenarios.
- (chapter intro) (chapter 3) · The earlier discussion of examples.
- The principles (chapter 7) · The BRIEF principle of including only essential detail.
- Communication, not testing (chapter 7) · The priority of communicating behavior rather than treating the scenario primarily as a test script.
Section by section
Introduction
Introduces feature files as Gherkin’s way of grouping related scenarios into readable documentation.
- Cohesive feature file organization: Explain that Gherkin scenarios are organized into feature files, and that each file should focus on one area of functionality so its scenarios form readable, cohesive documentation.
Why it matters: Grouping related scenarios makes a feature file useful as documentation, not just a container for scenarios.
Key terms: Gherkin, feature file, scenarios, cohesive
8.1 A sample feature file
This section introduces a feature file containing scenarios derived from the previous chapter’s example map.
- Example map to feature file: Trace how the team turned its example map into scenarios collected in a feature file, replacing the old scenario.
Why it matters: This connects the earlier example map to the feature file the chapter uses.
Key terms: example map, scenarios, feature file
8.2 Gherkin basics
Introduces Gherkin as a simple language designed to make documentation readable to people and processable by automation tools.
- Gherkin’s dual purpose: Explain why Gherkin combines natural-language readability with enough structure for automation tools to process its documentation.
Why it matters: This balance explains why Gherkin is meant to work for both readers and automation tools.
Key terms: Gherkin, natural language, automation tools
8.2.1 Keywords
This section distinguishes Gherkin block and step keywords and explains what each keyword contributes to a feature file.
- Block and step keyword distinction: Distinguish block keywords from step keywords by their colon requirement, and describe how descriptive text can follow a block keyword.
Why it matters: This distinction helps you read the structure of a feature file without confusing its blocks with its steps. - Feature and behavior blocks: Describe what Feature, Background, Rule, and Scenario introduce or describe in a feature file.
Why it matters: Each block tells a reader what kind of information the following text describes. - Scenario templates and example data: Explain the respective roles of Scenario Outline and Examples.
Why it matters: The two keywords show how a feature file presents similar scenarios alongside their example data. - Context action and outcome steps: Describe what Given, When, and Then express, and how And and But combine steps readably.
Why it matters: These keywords make a scenario's context, initiating action, and expected result easy to follow.
Key terms: block keywords, step keywords, Feature, Background, Rule, Scenario, Scenario Outline, Examples, Given, When
8.2.2 Non-English language support
Gherkin supports readable, automatable documentation in many languages and encourages teams to use their organization’s business language.
- Multilingual Gherkin keywords: Explain that Gherkin keywords are available in over 70 languages, that some languages offer multiple variants of a keyword, and why teams should use their organization’s business language.
Why it matters: Using familiar business language can make automatable specifications easier for non-technical colleagues to read.
Key terms: Gherkin keywords, business language, variants
8.2.3 Strict reading of the text
This section explains why automated scenarios require consistent spaces, punctuation, and capitalization.
- Exact scenario text conventions: Explain why spaces, punctuation, and capitalization must be consistent in scenarios, using the section’s examples of correct keyword formatting.
Why it matters: Careful formatting avoids corrections when a scenario is automated.
Key terms: scenarios, automation, Scenario:, Given
8.3 The structure and syntax of a feature file
This section explains how a Gherkin feature file begins, what its Feature block can contain, and why teams must maintain descriptive text themselves.
- Feature block structure: Describe how a feature file begins and where its name and overview go.
Why it matters: This gives readers a clear entry point to the behavior specified in a feature file. - Feature description and rule association: Explain what can go in a feature description and how the Rule keyword improves the connection between rules and scenarios.
Why it matters: Readers can use the description for helpful context while keeping illustrated rules clearly associated with their scenarios. - Descriptive text maintenance: Explain why a team must keep feature descriptions and other extra background information up to date.
Why it matters: Helpful background can mislead readers if nobody updates it when the feature changes.
Key terms: Feature keyword, Feature block, feature file, feature description, Rule keyword, scenario automation tools, living documentation
8.3.1 Rules
This section explains how Gherkin Rule blocks connect discovery rules to the scenarios that illustrate them.
- Rule and scenario association: Explain how a Rule block documents a discovery rule and determines which scenarios illustrate it, including where scenarios without a rule must appear.
Why it matters: The position of a scenario in a feature file tells readers which rule it illustrates.
Key terms: Rule keyword, Rule block, scenarios, feature file
8.3.2 Scenario structure
This section explains how a Gherkin scenario turns a discovery example into named steps that illustrate a rule, and why outcome wording should fit the organization.
- Scenario purpose and naming: Explain that a Scenario block formulates a concrete example discussed during discovery, should illustrate its containing Rule, and should have a descriptive name.
Why it matters: A clear name and connection to a rule help readers see what behavior the example illustrates. - Given When Then structure: Describe how a scenario's steps express the context, triggering action, and expected outcome of an example using Given, When, and Then.
Why it matters: This structure makes the behavior illustrated by a scenario easier to read. - Outcome wording and business language: Explain why some practitioners use “should” in Then steps and why that wording is optional rather than a requirement.
Why it matters: Outcome wording should support discussion without clashing with the customer's established language.
Key terms: Scenario, Rule, discovery, Given, When, Then, steps, context, triggering action, should
8.3.3 Multiple contexts
This section explains how to express multiple essential pieces of scenario context clearly and when a crowded context step should prompt a closer look at the domain.
- Separate essential context steps: Explain why a scenario may use And to extend a Given with another essential piece of context, rather than combine both into one step.
Why it matters: Clear, separate context steps help readers see exactly which conditions matter to the rule. - Conjunctions as domain signals: Describe why a conjunction inside a context step can prompt reconsideration of the domain, and how the section qualifies that advice.
Why it matters: An awkwardly joined step can reveal a question about the domain, not just a wording problem.
Key terms: Given, And, context, rule, conjunction, context step, domain abstraction
8.3.4 Keeping context essential
This section explains how to keep scenario context focused on the rule being illustrated, even when implementation requires additional setup.
- Essential scenario context: Apply the test of whether a reader needs each context step to understand the rule being illustrated, removing steps that do not pass it. Explain why basket contents need not appear in a scenario whose rule does not depend on them.
Why it matters: Keeping context tied to the rule makes a scenario easier to understand. - Readability over automation convenience: Justify leaving inessential setup out of scenario text even when automation must perform it, using the effects on readability and maintenance.
Why it matters: A scenario should remain useful when unrelated setup changes.
Key terms: context steps, specific rule, implicit context, essential principle, inessential details, brittle, ease of maintenance, ease of automation
8.3.5 Is it a Given or a When?
This section shows how to distinguish a scenario’s triggering action from its context by identifying which action directly produces the expected outcome.
- Context and trigger distinction: Distinguish Given context, the When action, and the Then outcome in the collection-order example. Explain how the business’s validation sequence determines whether providing unacceptable contact details or choosing collection is the triggering action.
Why it matters: Identifying the actual trigger makes a scenario accurately describe the business behavior. - Single When constraint: Justify why a scenario should typically have one When step and describe what to reconsider if two apparent actions compete for that role.
Why it matters: The single-When guideline helps expose unclear or missing details about what actually triggers a behavior.
Key terms: context, Given, When, Then, triggering action, single When step, enabling constraint
8.3.6 Multiple outcomes
This section explains when a focused scenario can have multiple outcomes and how to review conjunctions in scenario steps.
- Tightly coupled scenario outcomes: Explain why a scenario normally has one outcome step but may need several when the outcomes are tightly bound to the same rule.
Why it matters: It helps you keep a scenario focused without omitting an outcome essential to the rule. - Alternatives within scenario steps: Explain why an “or” within a step makes the example non-deterministic and how to revise the scenario.
Why it matters: Separating alternatives makes each scenario a definite example. - Judging conjunctions in steps: Describe why an “and” within step text needs judgment rather than an automatic ban, and distinguish it from the And and But step keywords.
Why it matters: It prevents a blanket rule about “and” from replacing careful review of what a step says.
Key terms: focused principle, BRIEF, Then, single rule, multiple outcomes, or, non- determinism, scenario, and, But
8.4 Gherkin tables
Introduces Gherkin tables as optional ways to make feature files easier for everyone to read.
- Purpose and optionality of tables: Explain that Gherkin includes data tables and examples tables to improve the readability of feature files, but any scenario can be written without tables.
Why it matters: You can choose tables when they make a scenario clearer, rather than treating them as mandatory syntax.
Key terms: Gherkin, feature files, data tables, examples tables
8.4.1 Data tables
This section explains how Gherkin data tables make structured information readable and how step wording can connect a table to its preceding step.
- Data tables and steps: Explain that a data table presents structured information as a two-dimensional grid attached to the preceding step, making information such as order details or a pricelist easier to read than prose.
Why it matters: A table can make the information a scenario supplies to a step much easier to scan. - Step wording with tables: Describe optional ways to signal that a step continues into a data table, and explain why special wording is not required.
Why it matters: The wording is a reading aid, not a requirement for the tool to recognize the table.
Key terms: data tables, step, two-dimensional grid, data table, colon, incomplete sentence
8.4.2 Scenario outlines and examples tables
This section explains how examples tables expand scenario outlines into multiple scenarios and how they can make similar examples easier to read.
- Scenario outline expansion: Explain how an examples table turns a scenario outline into separate scenarios and why this can be more readable than repeating similar scenarios.
Why it matters: You can read one outline as a set of concrete scenarios without losing sight of what they share. - Optional outline keyword: State how recent versions of Gherkin determine whether to process a scenario as an outline.
Why it matters: An outline need not literally use the Scenario Outline keyword in recent Gherkin. - Explanatory examples columns: Describe how unused examples-table columns can clarify individual examples and why a description column is best placed first.
Why it matters: A short description can tell readers why each data row is there without changing the scenario steps.
Key terms: scenario outline, examples table, Examples keyword, parameter placeholders, Scenario Outline keyword, Scenario, Examples block, description column, parameter placeholder
8.4.3 Data variations
Explains when data variations suit scenario-outline tables and why each example row must earn its place.
- Tabular data variations: Explain why tables of examples are a natural way to describe calculations and data-driven validation, including acceptable input permutations.
Why it matters: The format should make the behavior easier to understand, not merely put more tests on a page. - Value and cost of example rows: Justify checking what distinct behavior each example row illustrates before adding or retaining it, using the performance story as evidence.
Why it matters: A smaller set of purposeful examples can communicate behavior more clearly and run faster.
Key terms: data variations, scenario outlines, examples tables, data-driven validation, example rows, scenario outline, automation
8.4.4 Similar wording
This section explains when a scenario outline can make similar scenarios easier to read and why teams should not use one by default.
- Scenario outline readability: Explain when to consider replacing similar scenarios with a scenario outline and why readability, rather than brevity alone, should determine the choice.
Why it matters: It helps the team choose the form that communicates the differences most clearly.
Key terms: scenario outline, simple scenarios, Gherkin
8.4.5 Keep tables readable
This section explains how to keep Gherkin tables readable by limiting their size and aligning their columns.
- Readable table size: Explain why data and examples tables should stay small, and describe the screen-fit rule of thumb for a scenario or scenario outline.
Why it matters: A table that overwhelms the scenario defeats its purpose of making the behavior easier to read. - Aligned table separators: Describe how vertical alignment of table separators affects readability and how it can be achieved.
Why it matters: Aligned columns make a table easier to scan without tedious manual formatting.
Key terms: data tables, examples tables, scenario outline, separators (“|”), columns, IDEs
8.5 Readable blocks of text
This section explains how Gherkin docstrings keep multiline text readable and how AI can provide review feedback on scenarios.
- Readable Gherkin docstrings: Explain when to use a Gherkin docstring and how it represents formatted text for a scenario step.
Why it matters: Docstrings make exact, multiline text readable in a feature file. - AI scenario review feedback: Describe what AI can review in formulated scenarios and how to handle its feedback and significant scenario changes.
Why it matters: Quick AI feedback can improve scenarios without replacing the team's judgment or the product owner's review.
Key terms: Gherkin, docstring, preceding step, whitespace, AI reviews, readability, consistency, product owner
8.6 Summary
Where this is used later
- Structuring the living documentation (chapter 10) · Structuring living documentation builds on organizing related behavior readably.
- Documenting the domain (chapter 10) · Feature files as the place where the team writes its specifications.
- Does repetition matter? (chapter 9) · Introduces Gherkin as the format used to express scenarios.
- Documenting with a tag (chapter 9) · Assumes familiarity with the structure of a Gherkin feature file.
- Documenting shared features (chapter 10) · Feature files have descriptions in which the dependency can be recorded.
- Documentation evolves (chapter 10) · Provides a reason to maintain descriptive documentation as it evolves
- Moving shared context into a background (chapter 9) · The distinction between features and rules in a Gherkin feature file.
- Stay focused on illustrating the rule (chapter 9) · Keeping a formulated scenario focused on illustrating its rule.
Concepts explained in this chapter
- resultAn outcome is a description of the system state after the behavior of interest has taken place in an example.
- scenario outlineA Gherkin construct that defines a parameterized scenario expanded into multiple examples.
- WhenA Gherkin step keyword that introduces the stimulus or event causing the behavior under specification.
- contextThe state or conditions established before an action takes place in an example.
- examples tableA Gherkin block containing the example data used to generate scenarios from a scenario outline.
- scenarioA business-readable description of an example system behavior and its expected outcome.
- feature fileA feature file is a structured text file that expresses a software feature and its behavior scenarios in a format interpretable by BDD tools.
- essential principleA scenario-writing principle that removes details that do not contribute directly to illustrating the behavior of a rule.
- readabilityThe ease with which written scenario text can be read and understood.
- GherkinA domain-specific language for writing human-readable behavior specifications using constructs such as Given, When, and Then.
- incidental detailInformation in a scenario that is unnecessary to convey the behavior or rule being illustrated.
- background blockA Gherkin section whose steps establish context shared by scenarios in a feature file.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
