Auto-documenting Robot Framework Scripts

Auto-documenting Robot Framework Scripts

From my point of view, documenting Robot Framework (RF) test cases is very redundant, as long as you write meaningful test cases with meaningful keywords names. But what if we need to deliver documentation because our client asked for it? Now let’s assume that we have a complete framework built and zero documentation, how much time would we need to document our test cases? It seems to be a time consuming task, doesn’t it?.

Fortunately RF offers a couple of tools to create documentation based on what already exists in your test and keywords code:

They make use of Robot [Documentation] tags and generate an html document with the lines in them. Libdoc and testdoc are two Python/Robot modules that can be used separately in the command line, using the following syntax:

python -m robot.libdoc [options]
python -m robot.testdoc [options]

Wouldn’t it be awesome if we could generate our documentation each time our Jenkins jobs finish? This way we keep our documentation always in sync with our code. We can do this by creating a bash script that takes care of this, like so:

#!/bin/bash# Create folders
mkdir documentation
mkdir documentation/keywords
mkdir documentation/test-cases
echo $PATH
echo $PYTHONPATH
# Create Keywords documentation
python -m robot.libdoc steps-definitions/*.txt documentation/keywords/Utilities_doc.html
for folder in $(ls -d steps-definitions/*/)
do
for file in $(ls $folder)
do
python -m robot.libdoc $folder$file documentation/keywords/${file%.txt}’_doc.html’
done
done
# Create test cases documentation
for folder in $(ls -d test-suites/*/)
do
for file in $(ls $folder)
do
no_slases=${folder//[\/]/}
no_text_no_slases=${no_slases#test-suites}
python -m robot.testdoc $folder$file documentation/test-cases/$no_text_no_slases’_’${file%.txt}’_doc.html’
done

The result will be a documentation folder with two subfolders: keywords and test-cases, where each test case or resource file will have an html file created (resulting name will be: *_doc.html)
Now you only have to add [Documentation] tags with its proper documentation to your code. I never said it did all the work for you, a self documenting framework? That’s crazy!.
At least you don’t have to execute above commands every time you add a new test case or keyword.

About Tacit Knowledge

Tacit Knowledge develops, integrates, and supports enterprise software for household name brands and retailers. Together with our parent, Pitney Bowes, we offer solutions across all consumer touchpoints, from device to doorstep. We connect the entire ecosystem of our customers’ digital commerce business. We build and support the Ecommerce website and associated technologies through to providing fulfillment (Pick & Pack, Kitting) through to Delivery, Returns, and Post-purchase customer engagement tools.
How to Have a Happy Holiday Returns Season – and Keep the Goodwill Going Year-Round
THOUGHTS

How to Have a Happy Holiday Returns Season – and Keep the Goodwill Going Year-Round

Tis the week after Christmas and all through the land, merchants have loads of returns on their hands. That’s especially true for...
Read More
Retail in Alternate Realities
ECOMMERCE THOUGHTS

Retail in Alternate Realities

In retail and Ecommerce, we’re seeing an increase in the adoption of AR & VR technologies. We look at how these technologies are being used and, more importantly, if they are effective in improving the customer experience.
Read More
1 2 3 4 5 6
operator@tacitknowledge.com