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.

• Learn more about the Given-When-Then With Style challenge

Stay up to date with all the tips and tricks and follow SpecFlow on Twitter or LinkedIn.

PS: … and don’t forget to share the challenge with your friends and team members by clicking on one of the social icons below 👇