Documenting Custom Robot Framework Keyword Libraries - codecentric AG Blog

:

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.

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

python libdoc.py YourKeywordlib.html

python libdoc.py 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.

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"/>
      <sequential>
         <echo>--------------------------------------------------
Python   : ${python.runtime}
Script   : @{script}
Arguments: @{arguments}
--------------------------------------------------</echo>
         <exec executable="${python.runtime}" failonerror="true">
            <arg value="@{script}" />
            <arg line="@{arguments}"/>
      </exec>
   </sequential>
</macrodef>

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

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/libdoc-2.5.7.py" />

<!-- 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/libdoc-2.5.7.py" />

The task itself looks like this:

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

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

Its execution …

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

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

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

Keyword documentation