#GivenWhenThenWithStyle

How to organise feature files?

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?

Here is the challenge

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

Solving: How to organise feature files?

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.

https://cucumber.io/blog/bdd/solving-how-to-organise-feature-files/