Behaviour Driven Development: Tips for writing better feature files

Senior Developer

Tagged with:

Behaviour Driven Development a.k.a BDD is a software development approach being followed by most of the projects across the BBC. One of the key benefits of BDD is improved communication between technical and non-technical people.

BDD has drastically changed the roles of the members of the agile team. It encourages a collaborative way of working between product owners, business analysts, project managers, developers and test engineers. Please read my post on Eurostar blogs explaining how the tester’s role has changed in BDD.

We use Cucumber as a BDD tool to automate acceptance criteria. Feature files are written in the domain specific language ‘Gherkin’.

In this post I will share a few tips for writing better feature files.

Quick Introduction to Gherkin

Gherkin is the domain specific language used in BDD for writing software requirements in the form of feature files. Feature files are written in the Given-When-Then [GWT] format. Feature files usually consist of Feature Title, Narrative, Background, Scenarios, Steps, Tags, Example Tables and Doc Strings.


Feature is the user story template. A feature has two components; a feature title and a narrative.

The feature title is a short description of the story we are talking about. It should be ideally be a sentence that describes the scope of the story. An example of the feature title for the brand page of the BBC Television programmes looks like this:

Feature : BBC Television brand page

A narrative describes the story in detail with role and benefit. There are two most commonly used format of the narrative.

1] Connextra Format:

As a [Role]

I want [feature]

So that [Benefit]

The BBC /programmes team uses the Connextra format for all of our features.

2] Another variant on how to approach narratives, which has recently become popular, looks like this:

In order to [benefit]

As a [Role]

I want [feature]

An example of the Connextra narrative of the BBC TV brand page looks like this:

As a user of BBC website

I want to have a web page for every TV brand of the BBC

So that I can get all the information about my favourite Brand


The Background step acts as pre-requisite for each scenario and runs before each scenario. Using Background is a way of abstracting the repetitive scenario steps in order to avoid duplication of the steps. Background acts as replacement of the before hook in the code.


A scenario is a case with multiple steps within it. A feature file may consist of multiple scenarios.


Steps are written in the Given-When-Then [GWT] format. It looks like this:

Given [Pre-condition]

When [Action]

Then [Outcome]


Tags are used to organize the feature file and scenarios. Tags are written on the top of scenario or feature with “@” sign. More on Tags later in this blog post.

Example Tables and PyStrings (Doc String)

Example table are used to check for the multiple examples for a scenarios. PyStrings are used for specifying large chunk of text into the feature file.

One of the feature files for the BBC /programmes team looks like this :

TV Brands Feature File

Quick Tips for Feature files

Let's see how can use some tips to write better feature files for each section mentioned above.

General tips for feature files

1] Avoid long descriptions

Features should have a short and sensible title and description. Features with long descriptions can be boring to read and put off stakeholders. Generally features should be a sentence describing the scope and context.

2] Chose a single format all across your features

Decide which formats for you are going to use for writing features. You should choose an appropriate format and keep it consistent across your feature files. We have used the Connextra format. You should clearly mention the role, feature and benefit for each feature, to help decide the business value.

Tips: Background

Whenever possible, keep using background for the shared steps which are required for every scenario in the feature file.

1] Keep your background short

Background reduces the repetitive steps and proper use of background can avoid lots of duplication in the feature file. The background step should not be longer than 4 lines and it should be acting as pre-requisite for each scenario within the feature file. Whilst reading the scenarios in the feature files users may not keep the background in mind so let it be something very generic e.g. "Given I have logged in"

2] Don't include technical stuff in the background

We should avoid using technical language or actions in the background step. For example, we shouldn't have a background step that starts/stops Apache, clears the cache, truncates database etc. as user don't care about these. When you need to do technical actions, these and can be implemented in the step definitions or in the before hook instead.

Here is an example of a good background step:

Background: Brand is available

Given BBC TV brand is available to public or coming soon

A bad (overly technical) background step:

Background: Brand is available

Given group entity for the brand pid available in the PIPS datastore.

3] Never tag the background

You should never tag the background. We can tag scenarios and features but not the background.

4] Never use a background for feature files which contain only one scenario.

It doesn't make sense to use background for the features, which has only one scenario as we can include the details in the GIVEN step directly.

5] Don't use both background and before hook

Sometimes there might be duplication of the same context where we have before hook in the code and background in the feature file. Make sure you have used either background or before hook and not both.

Tips: Scenarios and steps

Gherkin provides a way to use a ‘scenario’ to deal with single examples, and ‘scenario outline’ to deal with multiple examples.

1] Think of Scenario Or Scenario Outline

Decide how many examples we think of for the particular scenario, if we have a scenario that can have only one example then we can use 'scenario' otherwise we need use 'scenario outline' to cover many examples using a table. Good use of scenario outlines will not only avoid duplication of steps but also makes scenarios more readable and maintainable.

2] Keep scenarios short by hiding implementation details

Avoid long and descriptive scenarios with lots of 'AND'' steps as this makes scenarios brittle as well as less readable. We should not include implementation details in the steps but we should have enough description to understand the context of the scenario. Never use technical details or the implementation details in the scenario steps like using XPath or CSS selector in the step.

3] Use Given-When-Then in the right order

We should write scenarios with GIVEN-WHEN-THEN sequence with proper use of AND and BUT.

Always start the scenario with the GIVEN step even you have used GIVEN in the 'BACKGROUND' section. Scenarios become less readable if we miss the order of GIVEN-WHEN-THEN.

4] Use declarative steps rather than imperative

Imperative steps mean unnecessarily exposing lots of internal details of the system. An example of the imperative steps would be a login scenario as follows:

Scenario: Login

Given I am on the login page

When I fill "username" with "ABC"

And I fill password with "XYZ"

And I checked the "Remember Me" checkbox

And I click on the "Submit" button

Then I should log into the system

And I should see then 'Welcome' message

Instead of writing too many steps like this, we can write couple of declarative steps like this:

Scenario: Login

Given I have logged into the system

Then I should see the 'Welcome' message

As you can see, using declarative steps in the scenario makes it shorter and more readable.

5] Use only key examples in the scenario outline

Using a scenario outline gives us the opportunity to include a table in the scenario and check many examples. Although this is a good approach for covering many scenarios at a time, we need to use only the most useful examples. We should not use more than 10 examples in a scenario outline.

6] Use Data tables with and without headers

You can use data table with and without table. Sometimes, it’s good idea to make use of data table without headers for better readability and maintainability. The example for the data table without scenario, which looks for the few EastEnders families.

Scenario: EastEnders Families

Given I am on the BBC EastEnders website

When I navigate to EastEnders families page

Then I should see EastEnders families

| Beale Family |

| Branning Family |

| Butcher Family |

| Carter Family |

| Fox Family |

| Masood Family |

Using inline tables like this will execute the scenario only once while example tables in the Scenario Outline execute a scenario for each example.

7] Use Doc Strings wherever appropriate.

Doc Strings (also known as ‘PyStrings’) allow us to include chunks of text in the feature file. We can include Doc Strings by three double quote marks in a line. Doc String helps us in checking chunks of text on the page, content or message body etc.

Below is a scenario, which checks a quote from the eleventh doctor on his profile page.

Scenario: Checks Doctors profile quote

Given I am on the Doctor Who website

When I visit the profile of the Eleventh Doctor

Then I should see the profile quote with content:

“ “ “

I have a thing.

It’s like a plan,

But with more


“ “ “

8] Make Scenarios Atomic

Scenario should run independently without any dependencies on other scenarios. This will help us debug faster when something goes wrong. Most BDD tools provide functionality to run a specific scenario by providing just the line number.

9] Avoid Conjunctive steps

Gherkin has an ‘AND’ step and we can make use of it. Avoid steps which include the word ‘and’ not at the start of the step. E.g:

Scenario: Homepage

Given I am on the homepage and scrolled page down

10] Cover both the happy and non-happy paths

Scenarios should cover both happy and non-happy paths. A happy path is a straightforward user journey while a non-happy path covers different edge cases around the happy path, including invalid inputs etc.

Tips: Tags

Tagging allows us to organize features and scenarios in the BDD project. If the feature files are across many different directories then tags help to filter specific scenarios and features. For example, if we have a set of scenarios for BBC Radio then we could tag those scenarios by using "@radio" tag. That way, whenever we want to see all of the scenarios for BBC Radio, we can easily search for the @radio tag.

1] How to decide name of the tag

In order to filter the scenarios by categories, we need to use smart tag names. Here are few suggestions for tagging:

Frequency of Execution: @daily, @hourly, @nightly

Dependencies: @database, @fixtures, @local, @proxy

Progress: @wip, @todo, @implemented, @blocked

Level: @functional, @acceptance, @smoke, @sanity

Environment: @integration, @test, @stage, @live

2] Tag your feature smartly

We should be aware of the fact that we can tag individual scenarios, so decide what value would be added by tagging an entire 'feature'. It may be useful in some instances. For example, you could tag a feature with the story number in a bug tracking system like JIRA.

3] Don't tag a scenario with the same tag used for tagging feature

If you tag an entire feature then any scenarios within the feature automatically inherit this tag. Don't use too many unnecessary tags in the project, as this will overcomplicated your feature files.

4] Remove @wip tag once you finished working on it.

Manage work in progress scenarios by using the @wip tag. Make sure you ignore the @wip tag for the scenarios running on continuous integration.

Tips: Miscellaneous

1] Use a Gherkin formatter/snippet

Many editors have plug-ins which support the Gherkin syntax, which formats the feature file by detecting the syntax error as we write.

There are plug-ins available for the Vim, Atom and Sublime Text editors but it’s worth searching for the gherkin syntax support for your favorite editor.

Vim has plug-in ‘vim-cucumber’ which supports syntax highlighting and editing commands. There is a package ‘sublime-gherkin-formatter’ for the Sublime Text. GitHub’s brand new editor Atom also has Gherkin formatting support.

Along with the formatting support, many editors also have Gherkin snippets which have in-built templates for the features, scenarios and example tables which speed up the feature writing process. Sublime Text has Gherkin snippets bundle.

2] Consider Living documentation

Living documentation is the specification of the system in the form of automated features. Feature files are the living documentation of the product and can be used by all stakeholders to view and edit feature files in an easy to read, user friendly way.

It is not a good idea to use a source control system for sharing feature files. Use an collaborative tool such as Relish instead.


Feature files help non-technical stakeholders engage and understand testing, resulting in collaboration and bridging the communication gap. For this reason, well-written feature files can be a valuable tool in ensuring teams uses the BDD process effectively.

Shashikant is a Senior Developer-in-Test in Platform Test, BBC Future Media

Tagged with:


More Posts