Dokumentation eigener Robot Framework Keyword-Bibliotheken

Momentan arbeite ich an der Einführung des Robot Framework für automatisierte Web-Tests bei einem unserer Kunden. Neben dem Robot Framework werden wir auch die SeleniumLibrary and RIDE einsetzen. Diese Tool-Sammlung wird allen Entwicklerteams im Unternehmen zur Verfügung gestellt werden.

Da unser Kunde ein eigenes Framework zur Entwicklung von Web-Applikationen einsetzt, entwickeln wir eine eigene Keyword-Bibliothek, die einerseits von Details des Frameworks abstrahiert und anderseits den Zugriff auf die SelenimLibrary kapselt (um bei einem potentiellen Austausch nicht alle Testfälle in allen Teams ändern zu müssen). Diese Keyword-Bibliothek wird als Robot Resource-Datei von allen Entwicklerteams in ihren Tests eingebunden. Daher ist eine gute Dokumentation notwendig.

Nehmen wir an, ein Keyword Starte Anwendung wäre wie folgt definiert und dokumentiert:

Starte Anwendung Keyword

Die Dokumentation unterstützt den Entwickler nicht nur beim Arbeiten mit der RIDE …
RIDE inline documentation

… sie wird auch verwendet, um eine HTML-Seite mit der allen Keywords zu generieren, etwa so wie die BuiltIn Dokumentation.

Das Library Documentation Tool libdoc

Das Library Documentation Tool erledigt die Arbeit für uns. Für Java-Entwickler, die nicht allzu sehr mit Robot und Python vertraut sind: libdoc.py kann in etwa mit JavaDoc verglichen werden. Die Benutzung ist einfach:

python libdoc.py YourKeywordlib.html

Details zum Aufruf findet man in der libdoc Dokumentation. Die Syntax der Dokmentation (Formatierung, Tabellen, etc.) wird im User Guide des Robot Frameworks beschrieben.

Build Integration

Der Build-Prozess des Kunden basiert auf ant. Daher habe ich für die Erzeugung der Dokumentation einen ant-Task geschrieben, dessen Details ich im Folgenden erläutern möchte. Zuerst schreiben wir ein Macro zum Aufruf von Python:

<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>

Um den ant-Task wiederverwendbar zu halten, verwenden wir folgende Properties, die ggfs. beim Aufruf überschrieben werden können:

<!-- 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" />

Der Task selbst gestaltet sich dann sehr einfach:

<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>

Seine Ausführung …

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

… erzeugt die gewünschte aggregierte Sicht auf alle Keywords in Form einer HTML-Datei:

Keyword documentation

  • Facebook
  • Delicious
  • Digg
  • StumbleUpon
  • Reddit
  • Blogger
  • LinkedIn
Tobias Trelle

Hinterlasse eine Antwort

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind markiert *

Du kannst folgende HTML-Tags benutzen: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>