---
title: "Feature Files: Concepts and Tips"
description: Using Gherkin to organize feature files.
---

[Avenue Code Snippets](https://blog.avenuecode.com)

# [Feature Files: Concepts and Tips](https://blog.avenuecode.com/feature-files-concepts-and-tips)

 Written by [Gabriel Abreu](https://blog.avenuecode.com/author/gabriel-abreu) | 7/12/17 7:00 PM

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.

[View full post](https://blog.avenuecode.com/feature-files-concepts-and-tips)

```json
{
  "@context" : "http://schema.org",
  "@type" : "BlogPosting",
  "author" : {
    "@type" : "Person",
    "name" : "Gabriel Abreu"
  },
  "dateModified" : "2017-07-28T12:41:21.836Z",
  "datePublished" : "2017-07-12T19:00:00Z",
  "headline" : "Feature Files: Concepts and Tips",
  "image" : {
    "@type" : "ImageObject",
    "height" : 4000,
    "url" : "https://cdn2.hubspot.net/hubfs/2564010/hans-peter-gauster-252751.jpg",
    "width" : 5988
  },
  "mainEntityOfPage" : "https://blog.avenuecode.com/feature-files-concepts-and-tips",
  "publisher" : {
    "@type" : "Organization",
    "logo" : {
      "@type" : "ImageObject",
      "height" : 60,
      "url" : "/hs/hsstatic/content_shared_assets/static-1.4092/img/default-amp-logo.png",
      "width" : 60
    },
    "name" : "Avenue Code Snippets"
  }
}
```