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 Markdown 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 Markdown should be between the “Feature” row and the first scenario. If you want to use this space just for plain Markdown with no Gherkin syntax following it, you are free to do so, simply add a feature row followed by Markdown.
We have used a range of Markdown 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 Markdown 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.