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 builds, integrates, and supports enterprise software for global brands. Tacit’s primary focus is Digital Commerce and we’ve won multiple awards for our work in this area. Our international experience extends to implementations within mobile commerce, social commerce and high-scale. Our world-class track record derives from specialization in key technologies and fielding teams with deep domain expertise. We also offer consulting services around product selection, creative and UX design, Agile coaching, system stabilization and performance tuning. And lastly, we offer 24/7 “follow the sun” application support, world class monitoring and alerting, and incident management.
Risk vs Reward. How investing in new headless technology from SAP paid off big dividends
ECOMMERCE THOUGHTS

Risk vs Reward. How investing in new headless technology from SAP paid off big dividends

Learn how one brand reaped big rewards taking a calculated risk implementing new headless technology.
Read More
Enable a better customer experience with SAP Spartacus
ECOMMERCE THOUGHTS

Enable a better customer experience with SAP Spartacus

Learn the immediate benefits from a successful headless commerce implementation of SAP Spartacus realized by a Tacit Knowledge client.
Read More
1 2 3 9
operator@tacitknowledge.com