How many times have you come across a story that is ready for testing, but does not fit all the acceptance criteria? Did you know that a majority of cases are related to bad feature file writing? In this snippet, I am going to present some standards and tips on feature file writing. These tips will help prevent late and bad outcomes, as well as endorse software quality using techniques and approaches that will help the Agile team to accomplish a better outcome for the stories within the project.

By definition, Behavior Driven Development (BDD) is an Agile software development technique that supports collaboration among developers, quality assurance analysts, business analysts, and non-technical people in a software project. It does so by utilizing a simple domain-specific language that uses natural language constructions in order to express the behavior and expected outcomes. The language in which these files are written is called Gherkin. Basically, the entire development process is guided by dedicated files that contain behavioral specifications of the project features.

That being said, explicit texts inside the file are of the upmost importance. Confusing words and ambiguous statements may affect the final behavior, which will lead to a higher fixing cost. It is widely known that the cost of fixing a poorly written requirement is much less than fixing an incorrect behavior on a system that has already been developed.

Now that we know the importance of the feature files, let’s begin with our “guidelines”.  

By convention, every file should contain behavior specifications of a single feature, which usually contains many scenarios. The space between the word Feature, which starts the file, and the first scenario can be used to describe the feature itself. The scenario is a list of steps that start with one of the key words: Given, When, Then, And, But. See the example below:

Feature: Maintaining the fruit storage in Avenue Code

Fruits are stored in the fruit bowl which can store up to 100 fruits

Every fruit taken from the bowl should be decreased from the stock count

Every time the bowl hits a quarter of its capacity the vendor must be contacted

When the vendor arrives with new fruits, the storage must be updated

Scenario: As an administrator of the fruits storage, I want to update the stock count

Given the fruit bowl has 23 fruits

And the vendor arrives with 75 fruits

When the fruits are placed into the fruit bowl

Then the stock count should be updated

And the stock count should be equal to 98

Now let’s imagine a feature that all its scenarios have the same two steps, for example, the “My Account” page of a random website:

Feature: My account page

The page should display the company logo

A direct link to “My History” page should be on the page

The page should contain a “Sign Out” link

Scenario: As a user, I want to verify that the company logo is displayed in the “my account page”

Given I visit the website as a guest user

And I sign in using valid credentials

And I access my account page

Then I should see the company logo

Scenario: As a user, I want to verify that a click on “My History” link on “My Account” page redirects me to the “My History” page

Given I visit the website as a guest user

And I sign in using valid credentials

And I access my account page

When I click on the “My History” link

Then I should be redirected to “My History” page

Scenario: As a user, I want to verify that I’m able to sign out using the “Sign Out” link on the “My Account” page

Given I visit the website as a guest user

And I sign in using valid credentials

And I access my account page

When I click on the “Sign Out” link

Then I should be redirected to the homepage

And I should be signed out

As we can see, all scenarios contain the same first three steps, which may seem repetitive and boring to read. To solve this problem, Gherkin proposes the concept of the Background.

The Background can be written in a Feature File right after its description and before the first scenario. Basically, it can contain any of the keyword steps (Given, When, Then, But, And) and it represents something that will always happen before the execution of any scenario within the feature. Check out how the same feature would look using the “Background” concept:

Feature: My account page

The page should display the company logo

A direct link to “My History” page should be on the page

The page should contain a “Sign Out” link

Background:

Given I visit the website as a guest user

And I sign in using valid credentials

And I access my account page

Scenario: As a user, I want to verify that the company logo is displayed in “my account page”

Then I should see the company logo

Scenario: As a user, I want to verify that a click on “My History” link on “My Account” page redirects me to the “My History” page

When I click on the “My History” link

Then I should be redirected to “My History” page

Scenario: As a user, I want to verify that I’m able to sign out using the “Sign Out” link on the “My Account” page

When I click on the “Sign Out link

Then I should be redirected to the homepage

And I should be signed out

Another tool that can be used to make the file easy to read and avoid redundancy is the Scenario Outlines. Let’s use the same fruit stock manager example we were talking about. We could have some similar scenarios like listed above:

Feature: Fruit count

# Detailed business description of the feature

Scenario: Eat 3 out of 70

Given there are 70 fruits in the fruit basket

When I eat 3 fruits

Then the fruit count should  be equal to 67

Scenario: Eat 15 out of 30

Given there are 30 fruits in the fruit basket

When I eat 15 fruits

Then the fruit count should be equal to 15

Simply copying and pasting the same scenario only to use different values may quickly become tedious and repetitive. Scenario Outlines allow us to express these examples more concisely by using a template with placeholders. Notice the changes to the same feature file below:

Feature: Fruit count

# Detailed business description of the feature

Scenario Outline: Eating

Given there are <startNumber> fruits in the fruit basket

When I eat <eatenNumber> fruits

Then the fruit count should equal to <remainedNumber>

Examples:

|startNumber| |eatenNumber| |remainedNumber|

|          70           | |           3          | |              67             |

            |          30           | |           15        | |              15             |

If we want to add more data to the steps, we can utilize the concept of tables. Tables allow us to capture a richer data structure. Notice the example below:

Scenario: As an administrator user, I want to check the users list

Given the following account exists:

|name   | | id   |  |gender|

|Chris    | |78   |  |M         |

|Anna    | |79   |  |F          |

|Jorge    | |80   |  |F          |

When I access the users list

Then I should see all of the existing accounts

Now, let’s talk about how the scenarios are organized. Gherkin uses tags to create clusters and groups of scenarios. Using tags, a myriad of test suites can be created, separating the scenarios according to their severity. A tag should be written on the top of a scenario. Notice the example below:

Feature: My account page

Background:

Given I visit the website as a guest user

And I sign in using valid credentials

And I access my account page

@severity_1 @domain_1

Scenario: As a user, I want to verify that the company logo is displayed in “my account page”

Then I should see the company logo

@severity_1 @domain_2

Scenario: As a user, I want to verify that a click on “My History” link on “My Account” page redirects me to the “My History” page

When I click on the “My History” link

Then I should be redirected to “My History” page

@severity_3 @domain_3

Scenario: As a user, I want to verify that I’m able to sign out using the “Sign Out” link on the “My Account” page

When I click on the “Sign Out link

Then I should be redirected to the homepage

And I should be signed out

It’s important to keep some things in mind when writing a feature file:

1. Use declaratives, not imperatives 
2. Avoid unnecessary details
3. “Given” is usually used as a pre-condition
4. “When” should describe the key actions
5. “Then” should be used to observe the expected outcomes -> it’s usually an acceptance criteria of the story
6. Make it simple and concise

See? It’s easy to write and maintain all the complex business rules through BDD and feature files. Also, Gherkin is available in many languages, allowing you to write stories using localized keywords from your language. If you speak Portuguese like me, for example, you can write “Cenario” instead of “Scenario”.

Just keep in mind that the feature files represent the acceptance criteria of the stories and are made to keep the process simple for everyone involved, so the clearer they are written, the better the outcome.