Thursday, 8 March 2007

Automated Code Documentation for QTP Actions

Goal:
My goal was to be able to automatically produce code documentation for my QTP Test Actions to make it easier for others to re-use the actions and avoid having to manually create and maintain the documentation.
Background:
I had already selected NaturalDocs (http://www.naturaldocs.org/) for documenting my VBScript support functions. I wanted to be able to produce similar documentation for my re-usable QTP Test Actions.
Developing the solution:
Note: I often use the term Function to refer to a QTP Action.
On inspecting the QTP test script directory I found that each Action has a directory beneath the QTP Test directory and each Action directory contains a script file: Script.mts.
NaturalDocs recursively searches the specified directory looking for code files. It expects a file header and function headers in the code file. I added a file header and function header to the first Action of my QTP Test and added a function header to each of the remaining Actions. When I ran NaturalDocs it found each of the QTP Action script files and produced the documentation from the File and Function headers but because each Action has a separate script file only the first Action has the file header and hence the other Actions do not get associated with the QTP script name. To fix this problem I wrote a small perl script that concatenates all the individual Action scripts into a single file named after the QTP Test. These concatenated script files are placed in a dedicated directory and this directory is processed by NaturalDocs. This approach ensures all the QTP Actions are documented as part of their QTP Test. I added a call to this perl script in the batch file that is used to run NaturalDocs so that the concatenated files are produced each time I run NaturalDocs.
I extended the NaturalDocs configuration a little to recognise the keyword Action and document it in the same was as a Function. I had already added the keyword Parameter for documenting function parameters in my VBScript support libraries.


Problems
  • Keyword View: The large number of comment lines in the Action Header are all shown in the Keyword View. This doesn't look very good and just wastes screen space. perhaps there’s a way to configure Keyword View to no show the comment lines?
Example of documented QTP Test Actions: Screen Shot


Setup QTP automated code documentation