I believe that you should break the link between Gherkin files and the Epics / User Stories that triggered the Gherkin Scenarios. The Gherkin files should be organised in a way that usefully describes the evolving product. You need to accept that a User Story can affect Scenarios in multiple Gherkin files. Once the User Story is done you can and should forget about it. But the Gherkin Scenarios have a life long after the User Story is gone.
Terminology: Feature file about a feature
The term “Feature” is an overloaded term in software development. “Feature” is used for both:
- A Feature file – a .feature in Cucumber – that contains Gherkin Scenarios
- Feature level requirements – often called an Epic or Theme – that include lower level User Stories
(It gets worse when we add in Feature branches but I’ll leave that for a future discussion.)
For the purposes of this post I’ll refer to a:
- Gherkin file for a Feature file (.feature)
- Epic for high level requirement that includes multiple User Stories
Gherkin File per User Story (Anti-pattern)
In Specification by Example using Cucumber a User Story comes with associated Gherkin Scenarios. The question is where to put which Scenarios.
Unfortunately People’s natural instinct is to associate each User Story with a different Gherkin file. A team doing test-first development will write some Gherkin Scenarios as soon as they start work on a User Story. It is a natural step to put those Scenarios in a new Gherkin file.
Gherkin File per User Story
The example involves an Epic “Search for Customers” that has three User Stories:
- Search by Name
- Search by Address
- Search by Account Number
Each User Story could get a Gherkin file of it’s own, e.g. “search-by-name.feature”
This approach can get teams going but will soon run into problems. You get a mess once new User Stories demand updates to existing Gherkin Scenarios. User Stories are a thin vertical slice through the system. They are quickly followed by other thin vertical slices in the same area. Having different Gherkin files for each obscures the fact that the functionality is related at a higher level.
User Stories do describe the product but their main benefit is for scheduling development – for Agile Project Planning. Their life span is limited. Once they are done they become rather uninteresting.
Gherkin File per Epic (Anti-pattern)
The Gherkin files might also be associated with Epics but even that association tends to break down fairly quickly. Epics are more likely to the be right level of abstraction to be an interesting feature of a product but it isn’t guaranteed.
Gherkin File per Epic
Product Defined by Gherkin Files
From my perspective the set of Gherkin files defines the emerging product. They are the living spec. Software development is, after all, product development so our documentation (such as it is) should be about the product.
That means I divide the product into logical sections, each with a Gherkin file. And the new/changed scenarios from the User Stories go into these files. A User Story can and will change Scenarios in multiple Gherkin files (add/update/delete).
Product Defined by Gherkin Files
Despite the fact there is one Epic and three User Stories it might make sense to have two Gherkin files. Each Gherkin file would correspond to a major function about customers. In the example that means:
- Customer search
- Customer maintenance
All the Gherkin Scenarios about Customer Search go into that Gherkin file. All the Scenarios about Customer Maintenance go into the other.
The fact that a User Story will cause changes in one or more Gherkin files has major implications for version control. And that is a good topic to cover in a subsequent post in my series on Specification by Example.