23

We're building up a specification in Gherkin, and we'd like to present the feature files to the business stakeholders. How can we export all our feature files in some sort of 'pretty' format?

For example:

  • Generate a document containing all features
  • OR integrate features into other documentation
  • OR publish the feature files on a web portal (nicely formatted)
Raedwald
  • 46,613
  • 43
  • 151
  • 237
dgmstuart
  • 728
  • 2
  • 7
  • 17

5 Answers5

12

The best I've seen so far is Pickles; http://github.com/picklesdoc/pickles

It's work in process but looks good already. Please supply your feedback on GitHub

Marcus Hammarberg
  • 4,762
  • 1
  • 31
  • 37
  • I've left the project now, but this was the one which looked most promising - we actually started using it, but I don't know how far the team got with it. – dgmstuart Jan 29 '12 at 22:22
  • 2
    @dgmstuart it's alive and kicking! They just added JSON and DITA support, as well as supporting running it from command line, powershell (in VS2010 for example), MsBuild and NAant. Check it out: http://nuget.org/packages/Pickles – Marcus Hammarberg Jan 30 '12 at 08:55
  • 7
    Unfortunately this only seems to be for Windows machines...No Mac or Linux support :( – Nosrettap Nov 11 '13 at 19:54
  • I just built GherkinDoc, an npm package that generates HTML sites from Gherkin features, https://www.npmjs.com/package/gherkindoc – AlexandrosD Oct 22 '16 at 19:33
3

Our team is currently using relish, a code project to nicely format your gherkins onto a website.

It does however have some drawbacks - it is only "free while in beta", but this might still give you some ideas.

A nice feature of relish is that your dev team can choose to push the gherkins whenever they are ready, and the stakeholders don't need to manage/receive new emails / documents etc - they can just refresh the project webpage.

perfectionist
  • 4,256
  • 1
  • 23
  • 34
  • 1
    Hi - thanks, yes I've seen Relish now, but unfortunately the business wasn't comfortable having the spec open for all to see - that's a Massive downside. We had a look at Pickle, which isn't very mature but looked interesting. I've left the company to which this problem was relevant... – dgmstuart Jan 29 '12 at 22:15
  • AFAIK "all to see" isn't accurate. You do need to upload the feature files to the relish website - so there is a third party involved, but your relish pages are only visible to your own log in. – perfectionist Jan 30 '12 at 09:05
  • Ah, they seem to have added Private projects since I last looked. – dgmstuart Feb 09 '12 at 13:23
2

Why do you think you want to do this?

I would suggest that the beauty of bdd is that it provides a ubiquitous language between business stakeholders, testers and developers. It can be used at any part of the testing cycle to describe the features you want and the scenarios they adhere to. With your gherkin style feature file as a simple text file, it can be edited directly by a business stakeholder and transferred straight back into a source code repository. You can literally take new scenarios from the business and confirm which features need work, before writing one line of code.

By providing a different format for these files you are interfering with the ease at which data can cross those bridges. Yes you can prettify it and group all of the features together, into a word document etc, but by doing that you lose the ability to directly take a set of scenarios straight from the business and demonstrating that the codebase "works" for them.

So, I would suggest that the best format for presenting to the business stakeholders is exactly the same as the format they are already in.

However, have you considered changing your runner of your tests. Even if the features are still in plain text, a runner such as concordion or Concordion.net will give you a very pretty display of a test run.

AlSki
  • 6,868
  • 1
  • 26
  • 39
  • 5
    Hi. Yes, I agree, I'd rather not mess with the format, but the main problem to be solved is presenting the spec to the users - they're not very tech-savvy at all so I'm hardly going to be able to get them to pull updates into a local repository! There are a number of really basic challenges: sharing from source control, presenting the spec in a visually readable way (e.g. with syntax highlighting), and presenting just the list of Feature descriptions for higher-level stakeholders. Any ideas from that angle? – dgmstuart Jan 29 '12 at 22:21
  • Have you considered implementing an interface? Somebody (lead developer / team lead / tech savvy project manager) liases with the users. They commit via email to the interface who then handles the actual commit. Yes, its not ideal, but it keeps everything moving, and who knows, once they get used to the idea, they will be committing directly too. – AlSki Jan 31 '12 at 17:11
  • 7
    I have inherited a system with 450 stories totaling over 46,000 words - and growing. Trying to understand the functionality from the raw story text files is like trying to understand the system architecture by reading thousands of lines of code. If the stories are to serve as documentation, there needs to be a mechanism to easily zoom in or out to the level you want to view at. – Chris Snow Jan 18 '14 at 11:09
1

Another option which requires no technical skill whatsoever. Similar to another answer on here, but is specifically designed to appeal to the business rather than technical stakeholders. It's a Chrome extension which auto formats any *.feature file opened in Chrome. See examples and install here: Pretty Gherkin feature file viewer

ItsMe-Rodders
  • 291
  • 2
  • 4
0

Have a go with Gherkin Viewer

I put together this chrome extention for this purpose as I didn't like the idea of exporting / republishing feature files. This allows you to view the original source truth :)

https://chrome.google.com/webstore/detail/gherkin-viewer/lfckgakamnfdbanfefglincnckfnlapp?hl=en-GB

Take a look, see if it works for you. Source is on GitHub, very basic start if anyone would like to contribute be greatly appreciated.

John Byrne
  • 1