Enhancing Feature Files for SpecFlow+ LivingDoc

Behaviour-Driven Development (BDD) is a software development process that prioritizes human-readable descriptions of software requirements. These requirements are written using Gherkin syntax which is the most commonly used syntax for describing examples with Given/When/Then in plain text files called feature files. Although it is important to keep the feature files simple and easy to read, it is also vital that they carry all the necessary information and leave no room for ambiguity.

At SpecFlow, we figured that the feature files shouldn’t be just about Gherkin syntax. As we worked on making SpecFlow + LivingDoc the single source of documentation, we realized adding Mark Down support would bring a lot of benefits.

Lets take a quick peak at how this is done in a feature file :

Note the placement of Mark Down should be between the “Feature” row and the first scenario. If you want to use this space just for plain Mark Down with no Gherkin syntax following it, you are free to do so, simply add a feature row followed by Mark Down.

We have used a range of Mark Down features in the above example, and you can see the resulting output in SpecFlow + LivingDoc as per below:

Apart from the usual formatting options that comes with Mark Down such as bold/italic text, lists, etc., we also included table formatting, embedding images, internal links, and linking to an external application lifecycle management (ALM) system.

Embedding images

Embedding images allow you to visually communicate with the reader. In the above example we are displaying the mock up the UX designer has put together for this feature, taking away the need to navigate to another application to view a mock up. When embedding images, the path to the image can be specified as a relative or absolute path. You also have the option to embed images stored externally, such as on a website.

You can read more on how to embed images in LivingDoc here.

Internal links

In the above example the “search results” link navigates you to another feature within the document. Placing these links throughout your feature files, gives the readers the option to quickly jump to the relevant feature within the document:

The resulting output in SpecFlow+LivingDoc:

External links

Another handy feature you can include in your feature files is using Gherkin tags to point to the work item behind a particular feature. These tags will show up as links that would allow readers to quickly access the work item(s) in an external application and see additional information such as status of the ticket, assigned person, and back log item status.

You can link to any agile planning you wish, just make sure you tag the work item in the feature file and include the link in the LivingDoc setup step:

During the LivingDoc setup, if you defined the Gherkin tag prefix as WI as per example above and you want link to Azure DevOps then you can use the following command to generate the LivingDoc:

livingdoc test-assembly C:\Work\MyProject.Specs\bin\Debug\netcoreapp3.1\MyProject.Specs.dll --work-item-prefix WI --work-item-url-template https://dev.azure.com/specflow/BookShop/_backlogs/backlog/BookShop%20Team/Stories/?workitem={id}

The resulting output in SpecFlow+LivingDoc:

Importance of enhanced feature files

What we know from BDD is that in its core lies communication and shared understanding, and as we progress through the BDD journey we build a detailed map of the behaviors of our product in feature files. Therefore, the feature files and the information they hold play a crucial role in overall success of a project. Using the options and capabilities mentioned here truly enable you to convert feature files into lasting product documentation that would be easy to read, interactive and informative for every stakeholder.