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
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>
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" />
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>
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
… generates the desired aggregated HTML view of our keyword library:
Was this post helpful?
More articles
fromTobias Trelle
17.12.2018 Your job at codecentric?
Jobs
Agile Developer und Consultant (w/d/m)
Alle Standorte
More articles in this subject area
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.
Blog author
Tobias Trelle
Software Architect
Do you still have questions? Just send me a message.
Do you still have questions? Just send me a message.