Build living documentation from your Unit Tests

If you have done any Agile or Behaviour Driven Development (BDD) you probably heard of the Given-When-Then formula. This formula is primarily used by product owners to guide writing of acceptance tests and user stories.

Today we will use BDDfy to demonstrate how easy it is to create living documentations from unit tests. In BDD, each software feature is captured in a story. Stories are usually products of conversations between the client (whoever asked for the software), product owners and developers.

Story’s narrative is constructed using the following formula:

As a [role] (example of role: a customer]
I want [feature] (Example of feature: Login to the portal)
So that [benefit] (Example of benefit: View my order history)

Within each story we define one or many scenarios (acceptance criteria). Scenarios are constructed using a Title and a narrative. The scenario’s narrative template follows the following guidelines:

Given [context]
And [some more context]... (Optional)
When  [event]
Then  [outcome]
And [another outcome] ...(Optional)

So now that we have some understanding of BDD, we can use BDDfy to create living documentations from our unit tests. The first thing we need to do is to create a Windows library project or you can download the demo project at the end of the article to skip all of the set up settings.

Once you have your project created, open the Package Manager Console and execute the following command:

Install-Package TestStack.BDDfy 

then run the following command:


Install-package xunit

Create a new class and paste the following code snippet:

namespace usingBddfyConsole
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using Xunit;
    using TestStack.BDDfy;
    using TestStack.BDDfy.Core;
    using TestStack.BDDfy.Scanners.StepScanners.Fluent;
    AsA = "As a Customer",
    IWant = "I want to logon and click on a button",
    SoThat = "So that I can view my purchase history", Title = "Customer logon to view purchase history")]
    public class CustomerLogonToViewPurchaseHistory
        public void CustomerCanOrder()
            this.Given(X => LoginToWebSite(), "Customer Login to website")
                .And(x => CustomerIsActive(), "Customer is Active")
                 .When(x => ClickOnHistory(), "Click on History button")
                .Then(x => x.ViewMyPurchaseHistory(), "View purchase history")
        public void LoginToWebSite()
            // test customer login functionality
        public void CustomerIsActive()
            //check if customer is active
        public void ClickOnHistory()
            //test click event functionality
        public void ViewMyPurchaseHistory()
            //test navigate to Purchase History

Build your project, then click on Run All in Visual Studio Test Explorer (if you chosen to use XUnit, you will have to have Xunit Test Explorer extension installed first) then click on the output link:

To view the documentations right click on the project file in visual studio, click on open folder in explorer, then navigate to bin directory. Debug and double click on DDBfy.html file to view the test documentations (you will see the story followed by all scenarios).

Experiment with failing tests while checking the BDDfy.html to see the changes when test cases fail.

Download source from

Here (480.68 kb)

Comments (5) -

Keep up the good work,


Hussain Qupar 4/10/2014 9:49:59 AM

great article, thank you Smile

Jason Bronks 5/27/2014 4:35:13 PM

Any future plans for this topic?
Please email me when you additional posts.


Jason Clark 5/30/2014 10:42:12 AM

This almost identical to SpecFlow

You are correct. I also think SpecFlow is richer in features. However, in order to create the documentations from specflow you have to use a command line utility. With BDDfy the framework will generate the documentations on the fly.

Comments are closed