Generate Living Documentation with Pickles For Specflow Feature Files

How to Generate Living Documentation Through Pickles Using Specflow Files:

In this Beginners Guide on Specflow, we explored all about Step Argument Transformations & Specflow tables in detail in our previous tutorial.

In this tutorial, we will see how you can generate good looking living documentation through an open source framework called pickles using your existing Specflow files.

This documentation can serve as a ready reference for your documentation and should be a helpful resource for anyone working in the team and can help to understand the various features of the application under test and what kind of output it would produce against different types of supplied inputs.

What is Pickles?

Pickles is an Open Source Solution to generate living documentation for files written in Gherkin Syntax (which itself is open source and is used by other tools like Cucumber, RSpec as well).

As Specflow follows Gherkin syntax too, Pickles is a perfect fit to create documentation for Specflow Feature files as well.

What Documentation Format can I Create?

It supports 4 different formats of documentation as shown below:

1. HTML site with search (or a static HTML site)
2. Word file
3. Excel file
4. Raw JSON – which can be utilized to create documentation with any custom template/library.

Step by Step Guide For Creating Documentation

We will be creating the pickles documentation using a Powershell script which uses a Powershell.dll part of the Pickles package that we are going to install.

There are other options as well like:

1. Generating documentation through MSBuild scripts.
2. Through Pickles extension package for Visual Studio, it provides a UI to set up options.

Let’s see the step by step procedure.

Step 1:

Install Pickles package through Package Manager by running the below command in the package manager.

 Install-Package Pickles

Step 2:

Now, let’s create a Powershell script to create the documentation for the features. We will be mentioning the required parameters that are used for generating documentation.

Create a Scripts folder in the project and create a new file i.e. Pickles_documentation.ps1

This will contain the required config parameters as shown below:

# Setup variables
$root = "{rootDirOfProject}"
$FeatureDirectory = "$root\Features"
$OutputDirectory = "$root\Docs\{DocumentationType}"
$DocumentationFormat = "word"

# Import the Pickles-comandlet
Import-Module $root\packages\Pickles.2.20.1\tools\PicklesDoc.Pickles.Powershell.dll

# Call pickles
Pickle-Features -FeatureDirectory $FeatureDirectory `
-11111OutputDirectory $OutputDirectory `
-DocumentationFormat $DocumentationFormat

Let’s try understanding these parameters in detail:

#1) root: This is the root directory of the Visual Studio Project that we want to create our documentation for

#2) FeatureDirectory: Path of the Features folder (i.e. the folder/directory containing all feature files or specs)

#3) OutputDirectory: Path to the output folder where documentation will get generated. Refer to the {DocumentationType} parameter here. This is for simplicity purpose and we will be creating documentation of different formats in different folders.

#4) DocumentationFormat: The format in which we expect the documentation to get generated.

The supported formats are:

• DHTML (static html site)
• HTML (Different html pages for each spec or feature)
• Word (word / open office format)
• Excel (excel / open office format)

#5) The ImportModule commandlet expects the path to the Powershell dll library for pickles package and this can vary Depending on the version of Pickles installed.

After adding the Powershell script to the Specflow project and creating placeholders for different documentation formats, the project structure should look as shown below:

Step 3:

Let’s try executing this Powershell script now, and see how the generated documents would look like. We will see for 3 different formats i.e. DHTML, HTML, and Word

Let’s first run for format “Word” – In our Powershell script we will change 2 parameters i.e. OutputDirectory will contain a folder named “Word” to store the generated document, and the DocumentationFormat parameter will be “word”.

The script can be executed by opening the script in Power Shell script editor and executed from there.

Refer to the screenshot below for more details.

Let’s see how different documentation format’s look like:

Word Format: This is a formatted word document and is a single doc file containing all the features and scenarios.

HTML Format: This representation creates individual HTML files for each of the feature with separate formatting files for CSS and JS (This is the ideal format to place or host on a web server for documentation hosting over the web).

The folder structure for HTML format should look as shown below.

DHTML format: This creates a single static web page for all the features and scenarios present in the application.

This comes in really handy as it provides search feature as well to search for features/scenarios and is really helpful for large applications containing features/scenarios spanning multiple files were looking for a specific feature or scenario can be achieved directly by doing a search.

The DHTML folder structure will look as shown below:

Other Alternatives

Similar to Pickles, there are other document generators as well like Relish & Speclog. But both of them are not free (and the free versions have limited or restricted usage only). For more info, you can refer to Pickles Packages.

Conclusion

In this tutorial, we discussed all about creating living documentation for our feature files, which in turn provide an easy, user-friendly way to browse/search for different scenarios & features and can serve as an easy reference for the application for which features are created.

As Specflow features are already written in plain English language, it makes complete sense to document product’s Business requirements in the form which really makes it a single source of truth guide for all stakeholders involved in the application right from the Product to a developer and the tester.

Check out our upcoming Specflow tutorial to know more about the ways to Generate Test Reports and Execute Selective tests!

PREV Tutorial | NEXT Tutorial