The next is about organising scenarios into files, especially on how to organise feature files at a higher level. Because of the upcoming holiday season, we’re giving you a bit more time than usual to participate. The challenge will be open until January 11th next year.
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.
Option 1 – one feature file per story
All features in the same directory, grouped by the story/change item.
features/ story-1.feature story-2.feature story-3.feature
Option 2 – split by development cycle, group by story
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
Option 3 – split by story, group by capability
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
Option 4 – split by functional area, group by capability
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
Option 5 – split by system component, group by function
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 can propose the solution directly in the form linked below. For a longer explanation, please post it somewhere online, and just submit the link to the post. We will publish the results on 12th of January.
PS: … and don’t forget to share the challenge with your friends and team members by clicking on one of the social icons below 👇