If your doing specification by example or BDD you will soon realize that the tooling still points towards developers. WIth that I mean, that Cucumber and SpecFlow allows you to write your (executable) specifications in plain text, but you still check it into the source repository. This is of course a good thing since you’d want to version the specification with your code - but it also effectively hides it and keeps the spec out of reach for any non-developing member of the team.
Make no mistake here: the .feature-file is the master and original. That’s how it should be since it’s versioned together with the code. But we want everyone in the team to be able to read the specifications and see the test result easily. So we generate documentation off the .feature-files.
Pickles is a nice OSS framework that helps you solve this problem by generating documentation in a variety of formats from your specifications. This can be done in build scripts to keep the site up to date.
In this blog post I’ll show you two easy ways to include the generation of an HTML-site from your features with Pickles: via PowerShell and via MSBuild. Let’s start with the latter since I know that the best.
If you want to skip ahead you can download my code here.
Pickles and how to get it
Pickles describes itself as: “Pickles is an open source living documentation generator that works on feature files written in the Gherkin language, popularized in tools like Cucumber and SpecFlow”. It’s run by Jeffrey Cameron and has a thriving community. I’ve done some small commits but love the tool and “sell” it to almost every client doing specification by example.
There are other tools like this like Relish and SpecLog. But they both have a cost associated with them. In the Relish case you can get it for free but then you have to publish your specs on their site, something that most companies doesn’t want. SpecLog is a great tool and not a perfect fit for just documentation. It’s more for collaboration around the early phases of Specification by example.
Pickles supports 4 formats (Html, Word, DITA and json) with HTML being the most common one and also default value for the runners. I should tell you that a new version of the HTML-site is on the way. The one that’s generated now is static and doesn’t allow search and stuff. The Json-format (one of my small contributions) was thought of as being the foundation for a javascript based site. The new HTML site looks a lot like what we dreamt of then. It will be great!
The simplest way to get hold of pickles is from NuGet. This will download all the runners (MSBuild, Powershell, Nant and Console) and, in-fact, allow you to run Pickles directly from the NuGet console (package manager I think it’s called).
This can be a good start but pretty soon you’ll need to start using this in a build scrip. To be able to demo that easily I’ve created a little bundle with all the Pickles files in one zip.
The folder structure is like this:
pickles - pickles stuff that I’ve downloaded via NuGet
- MsBuild - just the stuff you’ll need to call Pickles from MsBuild
- Powershell - just the stuff you’ll need to call Pickles from PowerShell
Specs - a big structure with a lot of .feature files that you can use as a demo. Deep in the belows of that structure (/Specs/bin/debug/TestResult.xml) you’ll find a testresult file that is important if you want to display the tests result.
MSBuild
Enough talk already: let’s get down to business and create a little MsBuild file that you can incorporate (or call) from your build script.
The example build script shows it all really:
Let’s go through it line by (interesting) line:
On line 5 you import the PicklesDoc.Pickles.MSBuild.Tasks.dll that contains the Pickles task. This is where you get the ability to access the Pickles functionality. You need to have that DLL and all of it’s dependencies (found in the Pickles/msbuild-folder in my download) accessible from you build script.
We then set up a PropertyGroup (lines 7-16) for all the currently supported variables. Doing this allows you to override these values if you where to call this file from another file. You can of course write this directly in the Pickles-task if you want to.
Line 18 sets up our target (in msbuild lingo a target contains several tasks. Think of it like a method calling out to other methods)
On line 19 we create a new directory with MakeDir
Line 20-26 calls Pickles with all the supported parameters. It’s pretty self-explanatory. The only ones that is required are FeatureDirectory and OutputDirectory. The other defaults to:
- Format: Html
- ResultsFormat: Nunit
You can try this out by openening a Visual Studio Command Prompt and go:
msbuild PicklesMsBuild.proj
The most common problems you’ll run into is that Pickles and it’s dependencies cannot be found. Make sure you point the using-statement (line 5) to the place where all the dll’s are. I’ve used relative paths from the root of my sample.
PowerShell
I’m by no means a powershell master. Ok - I’m a total noob. There I’ve said it. But I got plenty of help from the guys at Tradera (thanks Torkel and Frank).
A lot of build scripts are executed using powershell scripts and you can call Pickles from powershell as well. This is, strangely enough, my second contribution. I’ve created a little commandlet called “Pickle-Features”. Come on - that was fun. Please?
To call into pickles you can do the following: Let’s go through that one line by line too. You’ll recognize the parameter names etc.:
- Line 2-9 is setting up the variables for our script. Change this to match your situation.
- Line 12 imports the module (DLL with the commandlet). This is needed in order to call into the commandlet
- Line 15-21 calls Pickles with all our parameters. As before, remember that only the FeatureDirectory and the OutputDirectory is required. I’ve supplied them all for clarity and for you to extend
Summary
There we go - a help for you to call Pickles from MsBuild and PowerShell. Remember that you can call it from Nant and as a console application too. It works much the same and is easy to figure out how to get to work from these samples.
Pickles will greatly enhance how the non-developers in your team can read and access the specification. You want them to read, comment and be a part of daily work with the specs. Don’t let developer-centric tools stop you from doing that.
My example as described above can be downloaded here, as a zip.