From previous posts, we have established that Automation framework development should be treated as software project. This means, that most, if not all activities applicable in other software projects should apply.  At each phase from requirement gathering up to release, there will be relevant documentation applicable.

If the framework is being developed in an agile manner for example, requirements could be in the form of Epics. Epics could further be broken down into backlog of user stories. We could decide to write these stories using the Gherkin language probably with a Bdd tool such as cucumber or specflow in a feature file. These feature file consisting of the different scenarios could actually serve as our Requirement documentation. Each story will identify the characteristics, attributes for a piece of the framework functionality being developed. e.g. logging function, reporting function e.t.c

Agenda:

  • Documentation in Automation Framework
  • Install Relevant Tools
  • Technical Documentation Generation UI
  • Automating Technical Documentation Generation

Pre-requisite/ Tools:

  • Knowledge of visual studio
  • Sandcastle
  • GhostDoc

 

During development, we could have design-specific documentation, to show the architecture of the framework we are developing. On the first iteration when the framework is shippable, it might be required to include the Scripting Manual. In our case, shippable will mean Testers can start making use of the framework to write scripts to test the AUT. This manual will give a high level overview of how to use the framework for scripting. It might include explanation of the Internal Domain Specific Language, and probably other setup requirements to use the framework.

The Documentation I am covering in this post is the technical documentation. We might return to previous ones described in more detail at a later time.

As we write more lines of code in the framework, going back to previously written code and trying to understand what we have done could become a challenge. Now imagine a developer that needs to get up to speed with the code written by someone else.

I will not cover documentation style etc. itself, but rather I will cover integration of tools to help auto-generate the documentation from the code itself using the in-built XML documentation comments in .NET. This will save a lot of time and aid easy maintenance. There are few available tools but I will be using Sandcastle help file builder in conjunction with Ghostdoc. We can probably achieve the same thing by just using Ghostdoc Pro version on its own.

You can grab Sandcastle from here. 

GhostDoc from here.

Install Relevant Tools

Setup Sandcastle

Extract the content of the zipped file and click on the installer and follow the wizard.

When u get to this screen click install SHFB and follow the wizard.

Setup Ghostdoc

Run the executable in the zipped folder, follow the wizard selecting the version of visual studio you are using. Now all the tools are ready.

Commenting

  • Let’s open up our project in visual studio. The project we are concerned about for now is our .Web projects.
  • Lets open up the MenuPObject.cs on each of the methods insert 3 (\\\) forward slashes.

Alternatively right click on a method

  • Hover over Ghostdoc, and click Document this.

Document this ghostdoc

If we do this on the properties, we will get comments generated as well. GhostDoc will help to fill in the blanks as much as possible. In the case of a method. It will use the method name to form a meaningful summary description. This is another benefit of giving methods meaningful name. I used to have what I call long method name phobia, but in as much as we should avoid extremely long method names, (that will just be ridiculous), we should not be afraid to name methods accordingly such that another person looking into our code can guess what it is trying to achieve. And as we have seen, I technically do not need to edit the comment, as for me, the auto generated comment is meaningful and sufficient.

Technical Documentation Generation UI

Description

  • Right click on the .Web Project and select properties
  • Under build ensure XML documentation file is ticked.

  •  Start-up sandcastle from installation location

  • Create a new project and save.

There are quite a few goodies this tool provide and they are fun to play around with, you can customize what should be included in your help files, the format you want it, you can include a Logo of your organisation. Etc.

Let’s generate a .chm help file.

  • Under the build select relevant formats.

  • On the right pane under project Explorer, right click on documentation source,

There are different sources we can use as input, a solutions file, a project file, or even a dll.

  • Lets select a .sln solutions file for the sake of it and we have the opportunity add multiple projects at once.

  • Back to the main page lets do a few more tweaks
  • Click summaries on the left hand pane, and select edit Namespace Summaries
  • Enter brief summary of what is included in the namepaces available in your project

Example

The TatAutomationFramework.Web namespace contains types that include test automation sut common web functions and sut specific page objects…

Or

The TatAutomationFramework.Web.Pages namespace contains types that include sut specific page objects that exposes functions for user interaction.

  • Apply and click close.
  • Click Build help file from the tasks bar

  • If you scroll down the logs, it should show the location the help files are saved.

Automating Technical Documentation generation

This final topic is probably the one you will find most useful. This is because in the real world you will not want to have to repeatedly deal with creating documentation using the UI. We are automation testers, anything tasks that looks repeatable, we get the machine to do it.

Can can directly include our existing sandcastle project file into visual studio. but let create a fresh one from within instead.

To accomplish this we will follow few steps:

  • Install Sandcastle Help File Builder Visual Studio Package – if not installed already
  • You can find this in the ‘InstallResources’ in the extracted sandcastle Zip file
  • Close visual studio and install the .visx file

  • Create a new documentation project in your solution
  • Right click on solution and add new project name it Documentation

  • Within this new project , right click on the document Sources folder
  • Add our .Web project as source

  • Go to the project properties by right clicking
  • Under Build, we will leave the setting as-is unless you want a different output
  • Under Visibility lets set it as we have done previously
  • Under Summaries, Click on edit namespace
  • We will put in the text we added earlier for our namespace description.

  •  Lastly before we build, open the ContentLayout.content file within the project
  • Topic properties, under Title, Type in “Welcome to the Test Automation Tribe Framework Documentation”

 

  • Build the Documentation project
  • If you navigate in windows explorer to the local directory of the project, under Help folder, You should see the generated Documentation.

Evaluation

The later approach is the one i favor for obvious reasons as we can directly use the Sandcastle Help File Builder tool to create help files and Scripts to generate it can be easily version controlled. There is more. We could use the nugget version instead of sandcastle help file builder. I will leave this till later. This is particularly helpful in situations where you do not want to install sandcastle on the build server for example. We will be able to deploy the required tools inside the project.

Completed Files:

Click Here to Download the Complete Working Solution and the help file created.

References:

Sandcastle documentation

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Show Buttons
Hide Buttons