liveBook · Manning

Feature file

As explained in Effective Behavior-Driven Development

A feature file is a structured text file that expresses a software feature and its behavior scenarios in a format interpretable by BDD tools.

A feature file should not simply collect everything delivered for one user story. Stories help a team plan and discuss work; a feature file remains as documentation of a coherent area of business functionality. If its scenarios describe different concerns, the file becomes harder to consult and maintain. section 10.1 section 10.10

A feature file is a plain-text Gherkin document, usually ending in .feature. It starts with exactly one Feature statement naming the functionality. An optional description can add business context. The file then contains scenarios, optionally grouped under Rule statements. Each scenario expresses an example through Given, When, and Then steps: context, action, and expected outcome. No programming knowledge is needed to read the syntax. section 6.3 section 8.3

Listing 6.1 Sample feature file (with only one scenario fully fleshed out)
Feature: Change delivery address

  Rule: Allow address change if not picked up yet


    Scenario: Order waiting for pickup
      Given the customer has placed an order
      And the order is waiting for pickup
      When they request to change the delivery address
      Then the address change should be allowed

    Scenario: Request to change address received after order collection 
      Given …
      When …
      Then …
      
    Scenario: Order picked up during address change process
      Given …
      When …
      Then …
  
  Rule: New address should be in range

    Scenario: New address is in range
      Given …
      When …
      Then …

    Scenario: New address is out of range
      Given …
      When …
      Then …

The delivery-address example puts several scenarios under the rules they illustrate. Its first scenario shows how a concrete situation and request lead to an expected decision. section 6.3

Split by business concern, not by story

A rule about identifying restricted customers belongs with blocklisting. A rule preventing those customers from paying on collection belongs with pay-on-collection behavior, even if both arose during discussion of the same story. Move rules and scenarios as the team’s understanding improves. section 10.1 section 10.2

Keep each file focused on a distinct piece of business functionality; there is no fixed size limit. Use file-system folders to keep a growing collection findable, and keep broad journey scenarios separate from scenarios illustrating individual rules. Review names and groupings over time rather than preserving an arrangement that no longer makes sense. section 10.0 section 10.2 section 10.7

How Effective Behavior-Driven Development covers it

How deep it goes
Explains the basic file structure, keywords, and organization choices, while referring readers elsewhere for further Gherkin syntax details.
Examples
Uses a delivery-address file and a split between blocklisting and pay-on-collection files to show scenario grouping.
What it assumes
Requires no programming knowledge for Gherkin syntax and introduces the file’s basic keywords.
What you can do after
Build it from scratch by naming one coherent feature, grouping related scenarios under rules where useful, and revising files as concerns change.
How it connects
Connects Gherkin scenarios and rules to example mapping, while distinguishing feature files from user stories.

Also explained in

Compare how 5 books explain feature file →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Effective Behavior-Driven Development. The section links point to the parts of the book it draws on.