Heute im Fokus: Testen von Funktionen mit den DocStrings.

Auch unter Programmierern sind Stammtischgespräche verbreitet. Je nach Bewusstseinszustand vertritt der eine oder andere sogar die Meinung, dass der überwiegende Anteil der Zeit beim Entwickeln einer Software auf das Debuggen, Fehlersuchen und Testen verwendet wird. Auch wenn das wahr sein sollte, besteht für Python-Programmierer keinen Grund zur Unruhe, denn es gibt das doctest-Modul, welches das Testen von Python-Code leichter macht.

In dem Artikel “Python Dokumentation mit DocString bin ich bereits auf die DocStrings und die Möglichkeiten, welche diese bieten etwas eingegangen. Ganz beiläufig hieß es dabei (Zitat):

Somit ergeben sich folgende Vorteile für Anwender und Coder:

• …
• Beispiele in DocStrings können zum Veranschaulichen und Testen verwendet werden.

Dieser Aussage möchte ich heute anhand eines kleinen Beispiels mehr Inhalt geben. Zumindest was das “Testen” angeht.

Szenario

Die modulare Entwicklung von Software birgt etliche Vorteile, von denen an dieser Stelle besonders eine ganz wichtig ist. Zum Einen steigert die modulare Methode die Übersichtlichkeit und erleichtert das Verstehen der kleineren Bausteine im Vergleich zum großen Ganzen. Der größte Vorteil ist jedoch der enorme Zeitgewinn. An jedem Modul kann ein anderer Programmierer sich die Finger wund tippen. Am Ende werden die voll funktionsfähigen Einzelmodule zusammengeführt und ergeben das endgültige Produkt.

Damit das Zusammenführen reibungslos vonstatten gehen kann, müssen die Einzelmodule zuvor eingehen getestet werden. An dieser Stelle kommen die DocStrings mit dem doctest-Module ins Spiel.

Einleitend in dieses Thema lässt sich die Funktion der Kombination aus DocString und doctest-Modul folgendermaßen zusammenfassen: Innerhalb des DocStrings wird der Python-Kommandozeilenaufruf nachgestellt und das zu erwartende Ergebnis angegeben.

An einem kleinen Beispiel wird dies deutlicher.

Komplizierte Beispielfunktion

Um den Kurztipp anschaulicher zu gestalten, habe ich mir eine sehr wichtige Funktion einfallen lassen :

def addtwo(x):
    """Addiert zu jeder Zahl eine Zwei hinzu:

    >>> addtwo(3.0)
    5.0

    >>> addtwo(0.0)
    2.0
    """

    return x + 2.0

Die Beispielfunktion erhöht jede Zahl x um zwei und gibt diese zurück. Damit mit Sicherheit klar ist, was sie tut, wird der Zweck und Sinn innerhalb eines DocStrings beschrieben. Zusätzlich wird die Funktion im DocString zwei Mal “aufgerufen” und das dazugehörige Ergebnis angegeben.

Die drei spitzen Klammern sollen hierbei die Python-Kommandozeile symbolisieren.

Wie erfolgt nun der Test, ob die Funktion auch das richtige Ergebnis liefert?

Das doctest-Modul führt die Anweisungen, vor denen der Python-Prompt (>>>) steht, aus und vergleicht das Ergebnis mit dem erwarteten Wert, welcher unterhalb des Prompts steht. In der Standardeinstellung liefert doctest nichts zurück, wenn beide Zahlen gleich sind, stimmen sie nicht überein, so gibt es eine Fehlermeldung:
> python -m doctest addtwo.py

Dieser Skriptaufruf hat keine Ausgabe zur Folge, weswegen man sich entspannen und davon ausgehen kann, dass die Funktion in Ordnung ist.

Möchte man auf etwas Feedback nicht verzichten, dann lässt sich das Skript auch mit einer ausführlichen Version starten:
> python -m doctest -v addtwo.py
Trying:
addtwo(3.0)
Expecting:
5.0
ok
Trying:
addtwo(0.0)
Expecting:
2.0
ok
1 items had no tests:
addtwo
1 items passed all tests:
2 tests in addtwo.addtwo
2 tests in 2 items.
2 passed and 0 failed.
Test passed.

Und wenn etwas nicht richtig läuft, wenn zum Beispiel statt zwei nur eins hinzu addiert wird:
> python -m doctest -v addtwo.py
Trying:
addtwo(3.0)
Expecting:
5.0
***************************************************
File "addtwo.py", line 4, in addtwo.addtwo
Failed example:
addtwo(3.0)
Expected:
5.0
Got:
4.0
Trying:
addtwo(0.0)
Expecting:
2.0
***************************************************
File "addtwo.py", line 7, in addtwo.addtwo
Failed example:
addtwo(0.0)
Expected:
2.0
Got:
1.0
1 items had no tests:
addtwo
***************************************************
1 items had failures:
2 of 2 in addtwo.addtwo
2 tests in 2 items.
0 passed and 2 failed.
***Test Failed*** 2 failures.


Fazit

DocStrings in Kombination mit doctest stellen in meinen Augen eine praktische und leicht handhabbare Methode dar, um Module, Funktion und Klassen zu testen und gleichzeitig den Funktionsaufruf direkt im DocString und damit in der Dokumentation zu demonstrieren.

Deine Stadt - Dein Preis
Mit CityDeal und vielen Anderen den Preis drücken!

© Muvik for muvik-multigrid, 2010. | Permalink | keine Kommentare | Teile es mit deinen Freunden: del.icio.us MisterWong Twitter
Tags: DocString, Python