BDD is a great way to collaboratively define features within your system and understand there intent by writing scenarios using the gherkin language (given, when, then). Another bonus to writing scenarios in such a style is it is easy to take scenarios written in plain English and turn them into automated tests. Frameworks such as SpecFlow and Cucumber are but two such options. With that, scenarios will generally live within the code base and for example with SpecFlow can only be accessed easily through Visual Studio and to ensure you have the latest version you will need access to the source code repository. Effectively you need a dev setup! In any software project the code base is always the only truth you can rely on, therefore it is correct to house the scenarios within the code base. But then problems arise in that now you need a development IDE to view them. You definitely don’t want everyone having to install and use the IDE to view the files but you also don’t want to be sending around copies of features files, which could become soon out of date. Roll up Pickles!
Pickles is an open source living documentation generator that works on feature files written in the Gherkin language and supports frameworks such as SpecFlow and Cucumber. Pickles is simple enough to use, you tell it where to find the features files, and then you tell it where to put the results. You can output the results in a number of formats including JSON, Word and the default option HTML.
You can get Pickles via NuGet with the following command
Pickles has a number of options to how you can invoke the generation of the documentation. This can be as a Nant task, an MSI task or even a PowerShell command. With these options it is very simple to add the generation of the documentation as part of your continuous integration process. Lets take the PowerShell example
Import-Module 'C:\Pickle\Pickles.PowerShell.dll' Pickle-Features -FeatureDirectory 'C:\MyFeatures' -OutputDirectory 'C:\MyOutput'
A simple two liner. The Pickles NuGet package includes a PowerShell module, which you will first need to import. This module contains a single CmdLet called Pickle-Features. -FeatureDirectory tells pickles where to find your feature files. Pickles will search for feature files in this directory and also any sub directories. -OutputDirectory tells Pickles where to write the results too.
So a typical scenario like the one below found in SpecFlow.
Can be viewed as HTML through a web browser by running Pickle over the feature file.
We use TeamCity for our continuous integration. We have added a step to the build process to run Pickles from PowerShell to generate the documentation files. Then we have added an extra tab on the build results screen. so that it can always be viewed for every checkin. In addition to this we copy the files over to a virtual directory folder so they can always be accessed, directly in a browser without the need to also have to go to TeamCity. This now means that anyone in the office can view the feature files at any time with the same URL they can be sure they are always viewing the latest version.