The unequivocal role of communication in Behavior Driven Development may frighten the newbies in the BDD world.
To the trained and veteran users, this strain is easily taken care of with high quality and up-to-date documentation. After all, the documentation is where the “shared understanding” is formed, and breathing life into your documentation will make the journey easier for everyone.
Now what does it mean to “breathe life into documentation”?
Well, the answer is simple, it means creating and maintaining documentation in a way that it truly reflects your progress throughout the development journey, rather than leaving it as a static document that you work on at the start and end of development. Remember, living documentation must be readable, verifiable, and kept up to date via an automated test suite so it can maintain its pivotal role.
Big expectations you might say! Yes, but thankfully there is SpecFlow+ LivingDoc to make all of the above easily achievable.
To generate living documentation SpecFlow gives you two options :
- A stand-alone CLI tool called SpecFlow+LivingDoc Generator that can generate local or self-hosted documentation out of your Gherkin feature files.
- An Azure DevOps extension that generates documentation out of your Gherkin feature files but within the Azure DevOps environment.
Now both of these tools achieve the same thing with minor differences but if you and your team use Azure DevOps as your agile planning tool then using the extension is an absolute no-brainer.
Extension installation and configuration
Lets take a quick look at how to install and use the SpecFlow+LivingDoc Azure DevOps extension:
- First stop, install the FREE extension from the marketplace, the installation process is simple and straightforward. Once finished you will see SpecFlow+ LivingDoc under the overview section of your projects in Azure DevOps.
- Next, you want to add SpecFlow+LivingDoc as a build step in your Pipelines. You can do this either through the DevOps interface or by using a YAML file. For the purpose of this example we will add the build step using the DevOps interface:
Note that you can always add SpecFlow+LivingDoc to an existing Pipeline
- The build step is easy to configure, lets take a quick look at the key settings
Feature Folder: This is a mandatory field and the bare minimum you need to specify. Simply point to the folder where you are keeping your feature files. Remember, at the start of your development journey you may only have your feature files or simply plain markdown files ready with no automation implemented yet. SpecFlow+LivingDoc allows you to generate only the documentation tree from feature files without any test results and later on add your test results as you make progress in development.
Note: If you want to include your test execution results, you must enter the path to your project root folder here instead of your feature files folder.
Test Execution JSON paths: Once development starts, you can add the test execution JSON file paths here to generate living documentation WITH the test results.
Binding Assemblies: If you are interested in your project’s Unused Step Definitions, enter your Binding Assembly paths here.
Generating test execution JSON file
You may be asking yourself, how do I generate the JSON file mentioned above and add it to my build step so I can have my test results displayed? Well, that is where SpecFlow’s core product comes in – SpecFlow. SpecFlow has a vast number of features that help you build your feature files and bind them to their respective step definition. As your progress through the automation phase, the JSON file generated by a Plugin for SpecFlow carries all the necessary data needed for SpecFlow+LivingDoc to display your test results. Check out our step by step guide on how to install and use SpecFlow in a build step before you run SpecFlow+ LivingDoc.
Once you have added SpecFlow+LivingDoc build step to your pipeline and successfully ran the pipeline, navigate to the overview page to view LivingDoc.
You have a number of navigation options at your disposal here, for a detailed look at these please check the LivingDoc documentation page.
Here is a quick snapshot:
The analytics tab provides a results summary of all the steps, features, scenarios and an unused step definition report which lists any implemented binding that is not linked to a scenario, remember this report requires the binding assemblies from the build step :
Now, check out what else SpecFlow+LivingDoc has to offer and how it can help you and your team.