Should the feature description look like a user story? #GivenWhenThenWithStyle

The challenge for this week deals with a common way of structuring feature file headers and scenario headers.

We write feature introductions in the user story format (As a… I want… So that…). Then we add scenarios related to different user personas and different user needs, and the original description no longer fits the contents. As the feature file grows, this becomes more and more wrong. Any ideas on structuring the story at the top to be more generic, but not too vague?

Gherkin, the format of Given-When-Then files, allows users to add any text after a scenario or a feature title, and just ignores it from an automation perspective. This is incredibly useful to provide more context for readers. Most online examples show the feature description in the Connextra user story format, such as the one below:

Feature: pending invoices report

  As a client account manager, 
  I want a report showing all pending (issued but unpaid) invoices for a client
  So that I can control control client credit risk


This usually works well when a feature is first introduced, since any new functionality should come with a clearly associated user need. But as more stories extend the feature, the connection between the feature and the stories becomes complicated.

For example, we might initially add a pending invoice report because an accounts manager wants it, in order to control client credit risk. But as the system grows, and we might add features to the pending invoice report that help accounts managers achieve other goals. A regular customer might be eligible for a discount, so client managers might want to know quarterly subtotals and averages to decide on discount amounts. Other types of users might want changes to the same report to achieve their own objectives. For example, call centre operators might need a few tweaks to solve client problems faster, or accountants might use it to prepare end-of-year tax returns. After a few such updates, the original value statement no longer captures the purpose for the feature. Teams sometimes try to make the user story at the top more and more generic, to encapsulate all the needs and personas, but then it becomes too vague.

The challenge for this week is: How to write a good description for a feature or a scenario? Think about a feature that evolved over time, potentially through dozens of stories or tasks. What are your ideas on how to structure those descriptions? Should they look like a user stories, or something else? What should they contain?

Post your suggestions using the link below. If you’d like to send a longer comment, perhaps write a blog post and then just send us the URL (you can do that using the same form, link below). The solution is already posted, see below.

Also, if you have a problem related to Given-When-Then that you’d like help with, or know a topic that might be interesting for the community to discuss, please propose it as a challenge for one of the next articles using the second link.

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 👇