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:
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.