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




