Documenting Custom Robot Framework Keyword Libraries

No Comments

Right now, I’m introducing the robot framework for automated web tests for one of our customers. Beside the basic robot framework, we are using the SeleniumLibrary and RIDE. This tool stack is going to be rolled out to all software development teams in the whole enterprise.

Since the customer has its own web application framework, we are developing a set of keywords that on the one hand hides the details of this framework and on the other hand also encapsulates the SeleniumLibrary (so it could be replaced without having to change all testcases of all the teams). This set of keywords will be included as a robot resource file by all development teams in their tests. Therefore it needs to be well documented.

Let’s assume a keyword Starte Anwendung is defined and documented like this:

Starte Anwendung Keyword

The documentation will not only be helpful inside the RIDE …

RIDE inline documentation

… but it will also be used to generate a HTML page containing all keywords, something like the BuiltIn documentation.

Using the Library Documentation Tool libdoc

The Library documentation tool is doing this job for us. For Java developers that are not too familiar with robot and python: is the equivalent to JavaDoc. The usage is very simple:

python YourKeywordlib.html

For details, have a look at the libdoc documentation. The documentation syntax itself (formatting, tables, etc.) is described in the user guide of the robot framework.

Build Integration

Since the customer’s build process is based on ant, we integrated the generation of the documentation as an ant task. I will show you the details. First of all, I wrote an ant macro to call the python runtime:

<property name="python.runtime" value="/dev/Python27/python.exe" />
<macrodef name="run-python">
   <attribute name="script"/>
   <attribute name="arguments"/>
Python   : ${python.runtime}
Script   : @{script}
Arguments: @{arguments}
         <exec executable="${python.runtime}" failonerror="true">
            <arg value="@{script}" />
            <arg line="@{arguments}"/>

In order to make the ant task reusable, we introduce some configuration properties:

<!-- folder to store documentation into -->
<property name="doc.folder" value="./doc"/>
<!-- keywords to document -->
<property name="doc.keywords" value="CustomKeywordLib.html"/>
<!-- path to libdoc tool -->
<property name="python.libdoc" value="../python/" />

The task itself looks like this:

<target name="generate-keyword-documentation">
   <mkdir dir="${doc.folder}"/>
      arguments="-f HTML -o ${doc.folder}/${doc.keywords} ${doc.keywords}"

Its execution …

Buildfile: C:\dev\workspaces\blog\robotdoc\src\robot\robot-build.xml
     [echo] --------------------------------------------------
     [echo] Python   : /dev/Python27/python.exe
     [echo] Script   : ../python/
     [echo] Arguments: -f HTML -o ./doc/CustomKeywordLib.html CustomKeywordLib.html
     [echo] --------------------------------------------------
     [exec] CustomKeywordLib -> C:\dev\workspaces\blog\robotdoc\src\robot\doc\CustomKeywordLib.html
Total time: 2 seconds

… generates the desired aggregated HTML view of our keyword library:

Keyword documentation

Dipl.-Math. Tobias Trelle is a Senior IT Consultant at codecentric AG in Solingen/Germany. He’s into IT business for nearly 20 years and is interested in software architecture and scalability. Tobias gives talks at conferences and meetups and is the author of the German book “MongoDB: Der praktische Einstieg”.

More content about Agile Testing


Your email address will not be published.