//

Documenting Custom Robot Framework Keyword Libraries

14.8.2011 | 2 minutes of reading time

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:

The documentation will not only be helpful inside the RIDE …

… 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: libdoc.py is the equivalent to JavaDoc. The usage is very simple:

1python libdoc.py YourKeywordlib.html
2

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:

1<property name="python.runtime" value="/dev/Python27/python.exe" />
2...
3<macrodef name="run-python">
4   <attribute name="script"/>
5   <attribute name="arguments"/>
6      <sequential>
7         <echo>--------------------------------------------------
8Python   : ${python.runtime}
9Script   : @{script}
10Arguments: @{arguments}
11--------------------------------------------------</echo>
12         <exec executable="${python.runtime}" failonerror="true">
13            <arg value="@{script}" />
14            <arg line="@{arguments}"/>
15      </exec>
16   </sequential>
17</macrodef>
18

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

1<!-- folder to store documentation into -->
2<property name="doc.folder" value="./doc"/>
3<!-- keywords to document -->
4<property name="doc.keywords" value="CustomKeywordLib.html"/>
5<!-- path to libdoc tool -->
6<property name="python.libdoc" value="../python/libdoc-2.5.7.py" />
7

The task itself looks like this:

1<target name="generate-keyword-documentation">
2   <mkdir dir="${doc.folder}"/>
3   <run-python
4      script="${python.libdoc}"
5      arguments="-f HTML -o ${doc.folder}/${doc.keywords} ${doc.keywords}"
6   />		
7</target>
8

Its execution …

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

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

share post

Likes

0

//

More articles in this subject area\n

Discover exciting further topics and let the codecentric world inspire you.

//

Gemeinsam bessere Projekte umsetzen

Wir helfen Deinem Unternehmen

Du stehst vor einer großen IT-Herausforderung? Wir sorgen für eine maßgeschneiderte Unterstützung. Informiere dich jetzt.

Hilf uns, noch besser zu werden.

Wir sind immer auf der Suche nach neuen Talenten. Auch für dich ist die passende Stelle dabei.