BDD – An introduction to feature files



A colleague recently wrote about Gherkin scenarios (e.g. Given, When, Then), and discussed why they should be considered by BAs who work with BDD (Behavioural Driven Development) in their teams. It’s an excellent read and I’d highly recommend starting with that. You can find it here.

The purpose of this article is to explore feature files. Feature files are documents that contain those Gherkin scenarios & requirements – they can be very useful to teams working on BDD projects. Feature files may be a key deliverable for BAs.

Feature files are where BAs store requirements & can create the bridge between requirements and automated tests (more on that later).

Why use Gherkin?

Gherkin is a simple language used to explain the expected behavior of a system. 

It consists of 10 keywords (Given, When, Then, And etc). 

BAs may write scenarios in Gherkin to specify the expected behavior of a system. It has 2 key advantages:

  1. It can be understood by the business and all types of users, this is because it’s a relatively simple language by using 10 keywords, we can explain the story and give a background, give an example and define a test.
  2. It can also be interpreted by a framework called Cucumber – which ties the BA specifications into automated tests. If the system’s behaviour doesn’t match the BA’s scenarios – then the automated test fails. Feature files are key to achieving this.

What are feature files?

Feature files are documents that contain Gherkin scripts & other relevant content. They are saved with the .feature extension (e.g. payment.feature). Here’s an example:

Feature files are often stored in the same repository as the project code that the developers work from (e.g. GitHub). This means that the Gherkin acceptance tests can be run as part of the integration tests but also over time, will form part of the regression pack of tests that the QA will run for the project to ensure end to end functionality is maintained at each iteration/release.

BA’s will often write the Gherkin script, but it’s a “living document” that can be developed and reviewed collaboratively (e.g. with the 3 Amigos).

Feature files can be written using a text editor (such as Notepad++) or by using a code editor (such as Sublime). These highlight the keywords and help provide structure to your document.

A typical feature file will include:

  • Title of the feature (e.g. Payments)
  • The user story for the feature
  • Bullet pointed acceptance criteria at the top
  • Any useful links for the developers (e.g. link to UX repository)
  • Gherkin scenarios

Why use feature files?

Feature files allow you to build up test packs for features and activities, creating a set of regression tests that can be maintained easier than individual stories. We can use tags to run a subset of common tests, e.g all tests around a user logging in. When QA runs the regression tests, they can choose to run only the tagged tests.

Traditionally, we would write our story into a project tool, such as Jira, and it would stay there, rarely, if ever, being reviewed/updated. When we come to design a new iteration of a feature, we write out a new story and a new test to support it. Feature files allow you to create a living document of the system’s expected behaviour.

When QAs and developers run their automated tests, if a feature file has changed but the code hasn’t been updated, their tests will fail. Similarly if the underlying code has changed and the feature file hasn’t been updated, the tests will fail highlighting a potential issue. At this point the Developer and the BA should review the existing Feature File to determine if the test is still relevant and therefore a defect has been introduced, or the test is no longer required and can be removed.

Using feature files allows BAs to write stories in a way similar to how developers write solutions. By using feature files, new requirements can be added by updating the feature file. We can refer developers to the existing acceptance criteria and provide the new detail needed. This reduces the effort needed to write new tests.

Source control

To get the full benefit from using feature files, source controlling them and including them as part of the build process creates automated acceptance testing. When a developer commits their solution, the acceptance tests we have written, or provided to QA, will be run against that particular feature. Similarly, the pack of tests we have written previously, will also be run, as part of regression testing.

The collection of feature files we’ve created will be stored in a repository, like GitHub, and will form a pack similar to the example below. This is the single source of truth for the requirements.

What’s the catch?

As with most things, starting out with something new is always hard. Setting standards and adhering to them is the hardest part of creating a culture of using feature files. Additionally, a lot of people will find it intimidating writing “code”. But, as with most things, the more practice the better you will become. Here’s a few tips:

  1. Try to install an editor, such as Sublime, with a feature file plugin to highlight keywords in your feature files – it will highlight an errors with the Gherkin syntax. This makes it much easier to write and understand feature files
  2. Work with QA and developers collaboratively. Using feature files will affect the development and testing process. Work to make sure everyone is onboard with this
  3. After you’ve written your first feature file – have a review of what worked and what didn’t. Some teams find they write too many automated tests that reference the UI and become difficult to maintain; some teams find it easier if the BA writes the scenario headline but QA write the steps; some teams will want the BA to own the feature files - while others will want the entire team to own them
  4. Don’t be afraid to ask for help!! We’ve put some useful links to sites & books that help you learn more about Cucumber, Gherkin and BDD. There’s plenty of information out there


Using feature files to store your Gherkin scripts will not be suitable for every application or project. But where you can find a use for them, you will find your conversations with the developers and testers will become more relevant to the feature being created, less focus on the smaller details and a greater appreciation that the tests cover the end-to-end system functionality.

Further reading

Cucumber IO (

Gherkin (

Link to SfA Git (

Introduction to Behaviour Driven Development (BDD) (

Author: Ian Tidmarsh, Business Analyst


Ian is a Business Analyst and has worked for UK Government for 15 years. Ian has a number of years experience in software development and Agile delivery and has led BA activities on several high profile projects.



Copyright 2006-2024 by Modern Analyst Media LLC