Step-by-step guide for LivingDoc Azure DevOps

Step 1 - Installation

1- Go to the SpecFlow+LivingDoc page on the Visual Studio marketplace and install the free extension. Since this extension is tied to Microsoft Azure DevOps, you will need to sign in with your Microsoft account.

Once the installation finishes, you will see the SpecFlow+ LivingDoc menu item show up under the overview section of Azure DevOps:

2- The first time you click on SpecFlow+ LivingDoc from the overview pane, you will also be asked to sign up for a SpecFlow account. Click on Sign in with Microsoft and follow the instruction to create a free SpecFlow account.

3- If you want to generate LivingDoc with test execution results you also need to install the SpecFlow.Plus.LivingDoc Plugin for your SpecFlow project. The plugin will generate the necessary JSON file that will carry the test results data.

Step 2 - Build step

The next step is to add the build step to your pipelines. You have two options here, you can either use a YAML file to configure the build step or use the Azure DevOps interface. For the purpose of this guide, we will use the Azure DevOps interface as it is easier to use. If you like to use a YAML file you can find all the details here.

Before we move on, it is also important to note that the build step only generates the documentation; it does not execute any tests or build your solution.

1- Navigate to the desired pipeline from the list (or add a new one) and select Edit.

2- Add the SpecFlow+ build step as per below:

Step 3 - Configuration

The main point to keep in mind during the build step configuration is whether you want to generate LivingDoc with or without test execution results. This depends on what stage of development journey you are in. Remember you can always hide your test results using the toggle, see point 4 here for more info.

Let’s take a quick look at the main configs:

A - There are 3 sources to pick from to parse the documentation data:

Feature folder - The folder containing the feature files. Use the test project root folder if you want to include test execution results.

Test Assembly - Relative or absolute path to the test assembly. Glob patterns are supported e.g.: MyProject\**\MyProject.dll

Feature Data - Relative or absolute path to the feature data JSON file. Glob patterns are supported e.g.: MyProject\**\FeatureData.json

B - Enter the path to the generated JSON file by the SpecFlow.Plus.LivingDoc Plugin. This file carries all the necessary data needed for SpecFlow+LivingDoc to display your test results and is generated when you run your tests. Therefore, if you want to generate LivingDoc with test results, this step is mandatory.

C - If you are interested to see the Unused Step Definitions in the analytics tab, enter your Binding Assembly paths (newline delimited) here. If your bindings are in the same assembly as your feature files you don’t have to specify this field.

We have covered the basics here to get you going and generating your documentation. There are a number of other configurations here, you can find further details on them here.

Step 4 - Viewing LivingDoc

1- Once the configurations are done and the pipeline run is finished, simply navigate to the overview section of Azure DevOps as per step 1 and click on SpecFlow+LivingDoc.

2- You will find your LivingDoc here. Make sure you check out the Viewing LivingDoc & Test results sections to read about all the features and options you have here. The Enhancing LivingDoc section in docs also provides additional information on functionalities such as Markdown and Embedding images.