It’s time to write a new feature file. I open up a text editor and the user story on JIRA next to each other. I copy the description from the user story. I paste it into the feature description, job done. Hold on a second. Should the feature description look like a user story?

The short answer is generally no but sometimes yes, according to Gojko.

….to answer the question from the title, related to user stories: it may, but it doesn’t, and often it should not.

My takeaways

User stories are for planning work, feature files evolve

This is useful to keep in mind as user stories are for getting things done. Feature files is the one source of truth that reflects how the system currently works.

Consider the scenario of new stories or changes being created for existing functionality. How would we write the feature files? If we were to strictly follow the user story = feature file, then there would be little difference between a story and a feature file. In this case, it makes sense to modify or restructure the current feature files.

There are more ways to write the feature description

The most common way is the ‘As a, I want, so that’ format but I haven’t tried other formats. It’s useful for me not to limit myself to this format and try other formats. It was refreshing to see the following examples:

Where multiple roles are specified:

Feature: Account reporting

   The account reports are primarily used by account managers
   to control client credit risk. They also use these reports
   to decide on eligibility for discounts and special deals.

   Other users include:
     * call centre operators, who use them to quickly look
       at recent transactions to assist clients when on call
     * accountants to audit end-of year tax reports

Scenario: …

A more explicit way of narrating how it will work in a real life scenario.

Feature: Pending Invoice Report

  Sabine, an account manager, is responsible for maintaing Acme
  Financial's credit risk exposure within defined levels. One way
  she does this is to closely monitor whether customers who have a
  history of slow payment have paid their current invoices or if
  those invoices are at risk of becoming past due. When she does
  this, she wants to see a list of all customers with billing
  dates within the next three business days with invoices that are
  pending. (Pending means the invoice has been issued and payment
  has either not been received or not been settled.)

Special rules:

Feature: Pending Invoice Report

  Rule: Account Managers may only see pending invoices
       for their assigned customers
  Rule: Account management supervisors may see pending invoices
       for customer assigned to the account managers they supervise

Documenting decisions:

Feature: Account Reporting
  …
  This feature explicitly excludes transactions from the legacy
  database, which will be added in a future iteration (Christian
  approved this by email on 13th January).

A trap that I have definitely fallen into as well is treating feature files as places to store test cases. Although they can be used for test automation, the main purpose of a feature file is a specification for functionality (as opposed to a technical document for verifying requirements). Each file eventually becomes quite granular (more details to be added at a later date).

Links:

https://specflow.org/2020/the-given-when-then-with-style-challenge/

https://specflow.org/2020/solving-should-the-feature-description-look-like-a-user-story/