Writing better Feature Files!

Table of contents
Reading Time: 4 minutes

My endeavors in recent times have exposed me to BDD in general and to Feature Files in specific. I have over the time realized that there are nuances in writing good FFs, which we tend to overlook. I suggest we do not. In this blog post, I am wanting to give some checkpoints to be considered while writing FF.

  1. Do not make grammatical errors. Our Feature files turn out to be the documentation for the functionality of the project that we are building. Hence, they should also be grammatically correct. This eases out the understanding curve and reduces the learning curve about what the project does. This includes simple things like –
    1. Expressing the vowels correctly
      • “The store sells a banana and a apple.”
      • “The store sells a banana and an apple.”
    2. Expressing singularity and plurality correctly
      • “The store has 1 mirror”
      • “The store has 100 mirror”
      • “The store has 100 mirrors”
    3. Expressing the tenses correctly
      • “Total 10 mirrors sell yesterday”
      • “Total 10 mirrors were sold yesterday”
  2. Do not end up writing redundant scenarios. Before writing a new scenario, ensure that one has done due diligence to ensure that the same scenario has not already been covered up. Redundancy can easily happen when we write scenarios for the new functionality as we may end up repeating ourselves across different scenarios depicting more or less same functionality.
  3. Try expanding the scenarios wherever possible rather writing a whole new scenario. When we write scenarios in a project which already has a lot of scenarios written, we may end up finding certain new functionalities which can be easily covered up by extending an already existing scenario. Strive for this. Remember that these scenarios do consume execution time and less number of scenarios means less time consumed.
  4. We may have scenarios where output may differ mostly because of the kind of inputs provided and not basis the flow in general. In such cases, Scenario Outline should be used instead of multiple individual scenarios. Look at the two scenarios below that only differ on the input system gets and the output system produces. The steps are all the same.

    Scenario: As a user, I should be able to correctly perform multiplication of two positive numbers

       Given the system is running
       When the user provides numbers 5 and 6
       Then the result should be 30

    Scenario: As a user, I should be able to correctly perform multiplication of two negative numbers

        Given the system is running
        When the user provides numbers -5 and -6
        Then the result should be 30

    The above two scenarios combined together as Scenario Outline.

Scenario Outline: As a user, I should be able to correctly perform multiplication on the provided inputs.

   Given the system is running
   When the user provides numbers and
   Then the result should be

   | First Number | Second Number | Result  |
   | 5                       | 6                           | 30         |
   | -5                      | -6                          | 30         |
   | 5                       | -6                          | -30        |

5. Proper layout of Given, When and Then. Our scenarios should have exactly one occurrence of each which can be separated by And/But.

  • Given – sets the system into a state after which user interaction can happen. In this step avoid making any user interaction.
  • When – the point at which the interaction with the user (or an external system) starts.
  • Then – the point at which the outcomes of such interactions are observed.

6. Move the recurring common steps into background. Consider the first example with two scenarios above for this. Look at the Given step for both the scenarios. Caught it? Yes, both are exactly the same. The ideal case of making them the common background step. Background steps execute with every scenario so functionally the same thing is performed but this style saves a lot of redundancy and typing. Example:


    Given the store has total 100 hats
Scenario: As a store owner, I want to see updated count of hats as soon as the purchase completes.

    When the customer buys 10 hats
    And the payment is made
    Then the store has total 90 hats
Scenario: As a store owner, I want to see updated count of hats if customer returns them.
    When the customer returns 10 hats
    And the return is accepted in the system
    Then the store has total 110 hats
Scenario: As a store owner,  I want a chain of sales to update the number of hats correctly.
    When the customer buys 10 hats
    And the payment is made
    And the customer buys 10 hats
    And the payment is made
   Then the store has total 80 hats

7. An important point to remember always is that our FFs should be easy to understand. Avoid having lengthy descriptions. Ideally, description should be

  • simple and straight
  • correct to the functionality depicted in the scenario
  • not having any unnecessary details

Also, the scenarios within a FF should not be complex. A scenario should holistically depict one and only one functionality without introducing any unnecessary complexities. If we notice that a scenario is getting complex or is doing more than one thing, then it is better to split such scenario into two. Keeping it simple is the key to a good scenario and in turn a good FF writing skill.

8. Avoid using technical jargon. Most of the time it is the system users who study the FFs to understand the system. Most of the time it is a developer who is writing the FFs and he/she knows a lot about the technical terms used within the project (read code base). The endeavor of the developer then should be to avoid using any such technical words with which the user may not be familiar with. Keep the simplicity of the FFs intact.

This is it. These are the suggestions that I have. There can be more to this and I will be very interested to listen from anyone who has an input. Till then, happy learning!


Written by 

Sonu Mehrotra is a Software Developer with industry experience of 5+ years. He is a Clean Code practitioner and an Agile follower. Sonu has helped financial institutions develop trading systems that make trading activities easier and more accessible to customers.