So schreiben Sie Tests in Python mit doctest

Als Entwickler schreiben wir häufig Testfälle und Kommentare, um unseren Code zu erläutern. Kommentare verbessern die Lesbarkeit und Qualität der Codebasis. Ausführliche Kommentare können uns daran erinnern, warum wir eine bestimmte Funktionalität implementiert haben. Außerdem helfen sie anderen Programmierern dabei, Codebasen zu verstehen, zu warten, zu nutzen und zu erweitern.

Zu den Best Practices gehört es, zunächst Kommentare und Testfälle für Ihre Funktionen zu schreiben. So können Sie qualitativ hochwertigeren Code erstellen und zugleich die verschiedenen Sonderfälle und Anforderungen der Funktion im Blick behalten. Traditionelle Methoden sind jedoch äußerst zeitaufwendig, da wir für jeden Test eine separate Fall-Datei vorbereiten und umfangreiche Funktionen schreiben müssen.

In solchen Situationen ist Pythons doctest-Tool äußerst hilfreich. Die Open-Source-Community hat das doctest-Modul als effizientes Test-Framework für die Entwicklung geschaffen. Mit doctest können wir Tests für den Code in unserer Funktion schreiben, indem wir sowohl Eingabe- als auch Ausgabewerte festlegen. Das spart Zeit und Aufwand und hilft uns, qualitativ hochwertigen Code zu schreiben.

Das klingt gut, aber wie schreiben Sie eigentlich einen doctest in Python? In diesem Artikel zeigen wir Ihnen, wie Sie Ihren ersten doctest einrichten, schreiben und testen – mit allen Informationen, die Sie für den Einstieg benötigen.

So schreiben Sie Ihren ersten doctest

Bevor Sie mit Ihrem ersten Python-doctest beginnen, stellen Sie sicher, dass Python 3 und eine geeignete Programmierumgebung wie Visual Studio Code (VS Code) auf Ihrem Computer installiert sind. In diesem Tutorial verwenden wir VS Code als integrierte Entwicklungsumgebung (IDE).

Einrichten der IDE

Vergewissern Sie sich nach der Installation von Python 3, dass die Installation erfolgreich war. Geben Sie unter Windows den folgenden Codeausschnitt in die Eingabeaufforderung ein:

1py -3 --version

Öffnen Sie unter macOS oder Unix das Terminal und geben Sie den folgenden Befehl ein:

1python3 --version.

Laden Sie als Nächstes die IDE Visual Studio Code herunter.

Starten Sie den Setup-Assistenten und folgen Sie den Anweisungen auf dem Bildschirm, um VS Code zu installieren.

Laden Sie nach dem Start von VS Code im Tab Extensions die Python-Erweiterung herunter. Jetzt können Sie Python in VS Code verwenden.

Einführung in Docstrings

Python verfügt über ein Modul namens docstring. Docstrings sind String-Literale, die wir in Funktions-, Klassen- oder Moduldeklarationen verwenden, um Kommentare und Testfälle in unseren Funktionen zu verfassen. Docstrings sind daher sowohl für die Dokumentation als auch für Tests unverzichtbar.

Wir können einen Docstring zwischen drei Anführungszeichen schreiben:

1"""

Nach dem Docstring können wir sowohl die Kommentare als auch die Tests schreiben, ebenfalls zwischen drei Anführungszeichen.

1"""

Im Laufe dieses Tutorials lernen wir die Syntax von Testfällen und Kommentaren kennen. Auf den ersten Blick können Docstrings und Kommentare ähnlich wirken. Sie erfüllen jedoch unterschiedliche Zwecke. Kommentare erläutern die Implementierung des Codes, während Docstrings Klassen, Methoden und Funktionen dokumentieren. Sie helfen anderen Programmierern, den Zweck einer Funktion zu verstehen und zu erfahren, wie sie diese bei ihrer Arbeit einsetzen können.

Das doctest-Modul erkennt Docstrings in Funktionen oder Klassendefinitionen. Testfälle im Docstring kennzeichnen wir mit dem Symbol >>>, um sie von den Kommentaren zu unterscheiden.

Öffnen Sie die Befehlszeile Ihres Betriebssystems und geben Sie python3 ein.

Die interaktive Python-3-Shell verwendet das Symbol >>> als Prompt und gibt die Ausgabe ohne dieses Symbol zurück. Nehmen wir an, wir geben einen Wert aus. Die interaktive Sitzung sieht dann so aus:

Das doctest-Modul sucht in Docstrings nach Mustern, die wie interaktive Python-Sitzungen aussehen, und erkennt sie. Anschließend führt doctest sie aus. Die doctests müssen direkt nach dem Funktionsaufruf oder Methoden-Header im ersten Docstring stehen. Achten Sie darauf, nach dem Schreiben des doctests keine zusätzlichen Leerzeichen einzufügen, um unerwartete Fehler oder Fehlschläge zu vermeiden.

Einen doctest schreiben

Um doctests verwenden zu können, schreiben wir zunächst Beispielcode. Für dieses Tutorial erstellen wir ein einfaches Modul namens square.py mit einer Funktion namens square. Die Funktion berechnet das Quadrat des übergebenen Eingabewerts.

1def square(x):
2    return x*x

Nun fügen wir unserer Funktion einen Docstring hinzu. Dieser Docstring enthält eine Beschreibung der Funktion. Außerdem umfasst er zwei Testfälle mit den Eingabewerten und den erwarteten Ausgaben. Anhand dieser Werte wird die verarbeitete Ausgabe getestet.

1def square(x):
2    """
3    This function returns the square of the input.
4    >>> square(2)
5    4
6    >>> square(5)
7    25
8    """
9    return x*x

Wie wird die verarbeitete Ausgabe getestet?

Das doctest-Modul analysiert den Docstring und erzeugt Text. Diesen führt es als Python-Shell-Befehl aus. Anschließend vergleicht es das Ergebnis mit dem erwarteten Resultat im Docstring.

Einen doctest ausführen

Um den doctest mit unserem Modul square.py auszuführen, fügen wir die Funktion testmod aus doctest hinzu. Die Funktion doctest.testmod testet das Modul m oder – falls m nicht angegeben ist – das Modul "_main_". Diese Funktion ist erforderlich, um doctest auszuführen.

1def square(x):
2    """
3    This function returns the square of the input.
4    >>> square(2)
5    4
6    >>> square(5)
7    25
8    """
9    return x*x
10
11if __name__ == "__main__":
12    import doctest
13    doctest.testmod() #test the whole module.

Anschließend führen wir das Modul square.py einfach mit dem folgenden Befehl im Terminal aus:

1python square.py

Da square.py nur eine Funktion enthält, testet das doctest-Modul auch nur diese Funktion.

Da keine Ausgabe erscheint, wurden alle Tests bestanden. Schlägt ein Test fehl, wird der Fehler im Terminal angezeigt und wir können ihn entsprechend beheben. Wenn Sie das Protokoll anzeigen möchten, ändern Sie das Skript und fügen Sie -v hinzu:

1python square.py -v

Protokolle zeigen die Ergebnisse detaillierter an und machen sichtbar, wie viele unserer Tests bestanden wurden oder fehlgeschlagen sind. Außerdem können wir die Funktion testmod mit einer praktischen Abkürzung auch ohne die Funktion main ausführen – das doctest-Modul lässt sich direkt über die Standardbibliothek aufrufen. Dazu übergeben wir der Befehlszeilenschnittstelle den Modulnamen:

1python -m doctest -v square.py

Erweitern wir nun das vorherige Beispiel ein wenig. Was ist, wenn Sie die Datentypen der Eingaben und Ausgaben Ihrer Funktion angeben möchten? Dafür nehmen wir eine einfache Änderung an unserem Docstring vor. Im vorherigen Beispiel fügen wir einfach Folgendes hinzu:

1:param a: int
2:return: int

Unser Docstring sieht dann so aus:

1def square(x):
2    """
3    This function returns the square of the input.
4    :param a: int
5    :return: int
6    >>> square(2)
7    4
8    >>> square(5)
9    25
10    """
11    return x*x

Wenn wir mehr als einen Eingabeparameter haben, können wir :param entsprechend anpassen. Angenommen, wir haben zwei Eingabeparameter. Der passende Docstring würde dann so aussehen:

1:param a: int
2:param b: int
3:return: int

Das können wir für beliebig viele Eingabeparameter wiederholen.

Herzlichen Glückwunsch! Sie haben gerade einen doctest geschrieben.

Fazit

Dieser Artikel hat Ihnen das doctest-Modul von Python vorgestellt und gezeigt, wie doctests die Codequalität verbessern und zu einer besseren Programmierweise beitragen können.

Außerdem wurde gezeigt, wie Sie doctests in Funktionen integrieren und mithilfe der Codedatei und des Terminals ausführen. Dabei wurde deutlich, wie einfach sich das doctest-Modul beim Programmieren einsetzen lässt.

Beim klassischen Ansatz zum Testen von Funktionen schreiben Sie ein separates Skript mit Ihren Testfällen. Doctests machen solche Skripte überflüssig und ermöglichen es uns, unseren Code effizienter zu testen. Zusammengefasst vereinfachen sie das Testen und verbessern die Qualität unseres Python-Codes.