-
Notifications
You must be signed in to change notification settings - Fork 164
Home
Have you had your features locked up in your code too long? Been struggling for a way to share them with your client and use them as a reference? Interested in starting living documentation? If so, then Pickles is for you. What better way to preserve your cukes than to pickle them !
Pickles was greatly influenced by the Specification by Example book from Gojko Adzic and the Relish project. While I love the idea behind Relish I don't use Ruby and I'm on a corporate intranet so a SaaS application that is only on the internet is useless to me. With no alternative out there, the only real option was to build one.
Pickles is very simple at heart. You point it to a directory tree containing your feature files and it will search that tree, cataloging each .feature file it finds and converting it to HTML, storing the HTML files in a location of your choosing. Pickles turns the plain-text feature into easy-to-read HTML that have a table of contents included so that you can easily navigate among the features. I have plans for other features for customising the output that you would like to see. See the Contributions page for some ideas.
See the Getting Started page for more details.
There are currently several ways of running Pickles:
The console application should be easy to add into any build process and the NAnt and MSBuild runners are meant to work with the most popular build tools in the .NET space right now.
Each of the runners provides a set of arguments to let you control the output of Pickles.
There are a lot of options available to you here for using the generated output. Here are some ideas:
- Deploy the static HTML to any web server and allow users to access it from there, no special plugins, mods, assemblies, etc. required -- A variant on this idea might be to create a small HTML introduction page that links to different versions of the documentation
- Zip up the static HTML into an archive and deploy it alongside your executable
When I first started doing acceptance tests, I was using FitNesse. That worked great for a while but the wiki syntax can be limiting and it can be a real pain to include in your continuous integration workflow, especially if you're using .NET like me. Having to start a server whenever I wanted to run tests was a little painful.
After a while I started searching for alternatives, came across Concordion and really liked it. I liked it so much that I ported it to .NET! The free-form HTML seemed kind of cool and the nice way it built up an index of pages was very handy. I was able to write the test runner so that it was easy to run the tests from either Visual Studio or a continuous integration build quite easily. However, the rule of one fixture per page and having to write HTML was limiting. The developers and clients did not like the idea much, unfortunately.
Then I stumbled upon Cucumber and SpecFlow. SpecFlow is an excellent tool. It integrates very well with Visual Studio, provides several different test runners and is under active development. It uses the common and easy to understand Given-When-Then syntax and builds upon the great work done by the Cucumber people. SpecFlow uses NUnit, xUnit, etc. underneath so its easy to make part of a continuous integration build. It does have one drawback and this is that the feature files live in your Visual Studio project in source control. Really they are only navigable from within Visual Studio.
I built Pickles to overcome this last limitation and help make SpecFlow be part of a truly living documentation system.
See the Contributions page.
- Get a Github account
- Fork the project
- Make your feature addition or bugfix.
- Send us a pull request via GitHub
If you look at the source code you'll see I'm building on the shoulders of giants! Here is a (not-exhaustive) list of projects incorporated into Pickles
A big thanks to all projects as they were extremely helpful in building this project quickly and easily.