Phillip Trelford's Array

POKE 36879,255

What makes a good feature file

Back in March, Gojko Adzic and David De Florinier ran an illuminating interactive session at the excellent Cukeup! conference entitled What makes a good feature file. A feature file is a file containing a set of scenarios specified in Gherkin for consumption by Cucumber or a derivative thereof. No really ;)


Gojko’s opening statement rang true for me:

People focus on the automation part of Cucumber initially. Then they write 100s and 100s of feature files, which usually aren’t as useful as they could be

Clearly writing good feature files is important. However writing good feature files, as any good documentation, takes time, effort and collaboration.

Here’s Gojko & David’s tips for what makes a good feature file taken from the slides:

  • About the business domain – not software design
  • In domain language
  • Specification – not a script
  • Easy to understand
  • Focused on a single thing
  • Precise and testable
  • Self-explanatory
  • Consistent
  • Easy to access

There’s a great section in The Secret Ninja Cumber Scrolls also titled:

 What makes a good feature file

Our story needn't end there though…

Feature file style

Smells Like Teen Spirit

With the content for a good feature file explained, it’s time to turn our attention to style.

Sometimes it’s easier to say what we don’t like than what we do. So in a similar fashion to Martin Fowler’s Refactoring book let’s categorize some feature file bad smells and then define ways to neutralize the odour.

Categories of bad smell in a feature file:

  • Long sentences
  • Repetitious sentences
  • Repetitive scenarios
  • A Never ending story
  • Commentary
  • And another thing

Long sentences

Doing time

Diagnosis: There’s no easier way to lose a reader’s attention than overtly verbose sentences. If you find yourself having to use horizontal scroll to read a line then it’s probably too long.


Repetitious sentences


Diagnosis: The words in consecutive sentences somehow line up and few words vary between them. Nothing works better for putting the reader to sleep.


  • Extract the parts that vary into a table

Repetitive scenarios


Diagnosis: The sentences in consecutive scenarios look almost identical, bar a few words varying between them. Nothing works better for confusing the reader.


A Never ending story

Neverending story

Diagnosis: Just like the 80s film of the same name, the story goes on and on, until the reader’s eyes start to glaze over. As a rule of thumb if a paragraph is longer than say 7 sentences, then it’s too long, the same can be applied for scenarios.


  • Consider using a background
  • Break up the scenario
  • Break the scenario up with tables



Diagnosis: The scenario is so hard to follow that it has been commented. Yes, the document needs documentation. Documentation is not code.


  • Start again

And Another Thing 

And another thing

Diagnosis: Just when you thought you’d reached the end… Given proceeds When which proceeds Then, but wait there’s another thing, another Given.


  • Try describing the initial state in a single line.
  • Split into multiple scenarios

Positive Example

How does a good feature file look then? Here’s an example from Gojko & David’s slides:

Feature: Free Delivery 
In order to increase customer loyalty VIP customers buying a lot of books should get free delivery 

Scenario outline: Free delivery 
Given the threshold for free delivery is 10 books 
And the customer is <type> with <books> in the cart 
When checking out 
Then free delivery is <free delivery> 

| type   | books | free delivery | 
| VIP    |   9   | not offered   | 
| VIP    |  10   | offered       | 
| VIP    |  11   | offered       | 
| Normal |  10   | not offered   |


Drawing Collaboration

In Liz Keogh’s words from the article Step Away from the Tools:

Start by having conversations, engaging both testers and business stakeholders

If you can’t have those conversations, stop. You can’t do BDD


Feature files are documents, and good documents should be short and to the point, easy to read and not put the reader to sleep. The real secret to good documentation is collaboration and review.

Has anyone read your feature file? Try inserting a particularly fallacious or comical statement towards the end and see if anyone mentions it ;)

Do you have some bad smells to share?

Further reading

Comments (1) -

  • jrnail23

    9/6/2011 9:19:40 AM |

    Haha... love that "Commentary" photo with Arsene Wenger.  Seriously, when was the last time Arsenal were in such disarray?

Pingbacks and trackbacks (1)+

Comments are closed