The next challenge is about organising scenarios into files, especially on how to organise feature files at a higher level.
Here’s the actual challenge question:
How do you organise feature files, for example should they be grouped by user story, by capability, by level of detail or something else?
One of the best things about the Given-When-Then format, and probably the key reason why it won against competing ways of structuring examples, is that it provides just enough structure for good conversations. It has the basic feature/scenario/examples hierarchy to guide a discussion, but it is not overly prescriptive on what to put into those boxes, or how a larger hierarchy needs to be organised.
However, for anything that’s not a trivial project, keeping some consistent structure for information is key to getting the benefits of living documentation. Here are some some typical ways of structuring information with Given-When-Then feature files. Vote for the one you think is best, or propose an alternative.
All features in the same directory, grouped by the story/change item.
features/ story-1.feature story-2.feature story-3.feature
Files are organised into directories by iterations/development milestones, each user story has a single feature file documenting the required changes:
features/ Iteration_11/ story11-1.feature story11-2.feature story11-3.feature Iteration_12/ story12-1.feature story12-2.feature story12-3.feature
Files are organised into directories by stories, optionally with a higher level breakdown for development cycles. Inside each story directory, scenarios are grouped into files by capability they provide or function they affect.
features/ Iteration_11/ story_11_1/ payment-changes.feature login-provider.feature story_11_2/ user-report.feature
Files are organised into directories by functional areas, scenarios are grouped into files by the user capability they provide.
features/ payments/ cards/ mastercard-processing.feature visa-processing.feature reports/ account/ personal-account-report.feature company-account-report.feature
Files are organised into directories based on the system architecture. Scenarios are grouped into files by the affected system function.
features/ apis/ card-processing/ stripe-processing.feature paypal-processing.feature front-end/ payments-screen/ card-validation.feature admin-screens/ reporting-screen/ personal-account-report.feature company-account-report.feature invoice-report.feature
You voted for the best way to organise feature files during a development process. As a gift to the community, we again have a special guest replying to the challenge.
The wonderful Seb Rose, BDD advocate at Smartbear and co-author of two BDD books, posted the full response on his blog. Head over there to read the results and Seb’s ideas on how to structure good documentation from Gherkin feature files.