Code schreiben, ausführen und testen¶
Um einen Fehler zu beheben oder eine Funktion zu implementieren, musst du neuen Code schreiben.
Bevor Sie mit der Arbeit am Code beginnen, stellen Sie sicher, dass Sie eine Entwicklungsumgebung eingerichtet haben und dass Sie an einem Branch arbeiten.
Wir haben einen Code-Styleguide, der unsere Richtlinien für das Schreiben von Code für BeeWare enthält.
Testgetriebene Entwicklung¶
Eine gute Methode, um sicherzustellen, dass Ihr Code das tut, was Sie erwarten, besteht darin, zunächst einen Testfall zu schreiben, um dies zu überprüfen. Dieser Testfall sollte zunächst fehlschlagen, da der zu testende Code noch nicht vorhanden ist. Anschließend können Sie die erforderlichen Codeänderungen vornehmen, damit der Test erfolgreich verläuft, und so sicher sein, dass das, was Sie geschrieben haben, das erwartete Problem löst.
Führen Sie Ihren Code aus¶
Sobald Ihr Code geschrieben ist, müssen Sie sicherstellen, dass er auch funktioniert. Sie müssen Ihren Code manuell ausführen, um zu überprüfen, ob er das tut, was Sie erwarten. Falls Sie dies noch nicht getan haben, sollten Sie einen Testfall für Ihre Änderungen erstellen; wie oben erwähnt, sollte dieser Test fehlschlagen, wenn Ihr Code auskommentiert ist oder fehlt.
Sie fügen Ihren Testfall zur Testsuite hinzu, damit er zusammen mit den anderen Tests ausgeführt werden kann. Als Nächstes führen Sie die Testsuite aus.
Tests und Abdeckung¶
BeeWare nutzt tox zur Verwaltung des
Testprozesses und pytest für seine eigene
Testsuite.
Der Standardbefehl tox umfasst die Ausführung von:
- Pre-Commit-Hooks
towncrierÜberprüfung der Versionshinweise-
Dokumentationsprüfung
-
Testsuite für verfügbare Python-Versionen
-
Berichte zur Codeabdeckung
Das ist im Wesentlichen das, was CI ausführt, wenn du einen Pull-Request einreichst.
Um die gesamte Testsuite auszuführen, geben Sie Folgendes ein:
(.venv) $ tox
(.venv) $ tox
(.venv) C:\...>tox
Die Ausführung der vollständigen Testsuite kann eine Weile dauern. Sie können
den Vorgang erheblich beschleunigen, indem Sie tox parallel ausführen, und
zwar mit tox p (oder tox run-parallel). Wenn Sie die Testsuite parallel
ausführen, erhalten Sie während der Ausführung weniger Rückmeldung zum
Fortschritt, aber am Ende des Testlaufs erhalten Sie dennoch eine
Zusammenfassung aller gefundenen Probleme. Sie sollten eine Ausgabe erhalten,
die anzeigt, dass die Tests ausgeführt wurden. Möglicherweise sehen Sie
SKIPPED Tests, sollten aber niemals FAIL oder ERROR Testergebnisse
erhalten. Wir führen unsere vollständige Testsuite vor dem Zusammenführen jedes
Patches aus. Wenn dabei Probleme entdeckt werden, führen wir den Patch nicht
zusammen. Sollten Sie einen Testfehler oder einen Testausfall feststellen, liegt
entweder ein Problem in Ihrer Testumgebung vor oder Sie haben einen Randfall
entdeckt, den wir bisher noch nicht gesehen haben – in jedem Fall lassen Sie es
uns wissen!
Neben dem Bestehen der Tests sollte hier eine 100 %ige Testabdeckung angezeigt werden.
Testvarianten ausführen¶
Tests für mehrere Python-Versionen ausführen¶
Standardmäßig versuchen viele der tox-Befehle, die Testsuite mehrmals
auszuführen – einmal für jede von BeeWare unterstützte Python-Version.
Dazu muss jedoch jede dieser Python-Versionen auf Ihrem Rechner installiert und
für den Python-Erkennungsprozess von tox verfügbar sein. Im Allgemeinen gilt:
Wenn eine Python-Version über
(https://virtualenv.pypa.io/en/latest/explanation.html#python-discovery)
verfügbar ist, sollte PATH in der Lage sein, sie zu finden und zu verwenden.
Führe nur die Testsuite aus¶
Wenn Sie an einer neuen Funktion zügig arbeiten, müssen Sie nicht die gesamte Testsuite ausführen; Sie können nur die Unit-Tests ausführen. Führen Sie dazu folgenden Befehl aus:
(.venv) $ tox -e py
(.venv) $ tox -e py
(.venv) C:\...>tox -e py
Eine Teilmenge von Tests ausführen¶
Standardmäßig führt tox alle Tests der Unit-Test-Suite aus. Wenn Sie einen
neuen Test entwickeln, kann es hilfreich sein, nur diesen einen Test
auszuführen. Dazu können Sie beliebige pytest
Spezifikatoren
als Argument an tox übergeben. Diese Testpfade beziehen sich relativ auf das
briefcase Verzeichnis. Um beispielsweise nur die Tests in einer einzelnen
Datei auszuführen, geben Sie Folgendes ein:
(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py
(.venv) $ tox -e py -- tests/path_to_test_file/test_some_test.py
(.venv) C:\...>tox -e py -- tests/path_to_test_file/test_some_test.py
Auch wenn Sie nur einen Teil der Testsuite ausführen, erhalten Sie einen Abdeckungsbericht – allerdings werden in den Abdeckungsergebnissen nur die Codezeilen aufgeführt, die von den konkret ausgeführten Tests verarbeitet wurden.
Führe die Testsuite für eine bestimmte Python-Version aus¶
Standardmäßig wird tox -e py mit dem Interpreter ausgeführt, der auf Ihrem
Rechner als python erkannt wird. Wenn Sie mehrere Python-Versionen installiert
haben und eine bestimmte Python-Version aus den installierten Versionen testen
möchten, können Sie eine bestimmte Python-Version angeben. Um beispielsweise die
Testsuite unter Python 3.10 auszuführen, geben Sie Folgendes
ein:
(.venv) $ tox -e py310
(.venv) $ tox -e py310
(.venv) C:\...>tox -e py310
Eine Teilmenge von Tests kann ausgeführt werden, indem man --
und eine Testspezifikation an die Befehlszeile anhängt.
Die Testsuite ohne Abdeckung ausführen (schnell)¶
Standardmäßig führt tox die pytest-Suite im Single-Thread-Modus aus. Sie
können die Ausführung der Testsuite beschleunigen, indem Sie sie parallel
ausführen. In diesem Modus werden keine Abdeckungsdateien erstellt, da die
Erfassung der Abdeckung innerhalb der gestarteten Prozesse zu komplex ist. Um
eine einzelne Python-Version im „Fast“-Modus auszuführen, geben Sie Folgendes
ein:
(.venv) $ tox -e py-fast
(.venv) $ tox -e py-fast
(.venv) C:\...>tox -e py-fast
Eine Teilmenge von Tests kann ausgeführt werden, indem -- und
eine Testspezifikation an die Befehlszeile angehängt werden; eine bestimmte
Python-Version kann verwendet werden, indem die Version zum
Testziel hinzugefügt wird (z. B. py310-fast für die
Ausführung mit Python 3.10).
Codeabdeckung¶
BeeWare gewährleistet eine 100-prozentige Testabdeckung in seiner Codebasis. Wenn Sie Code zum Projekt hinzufügen oder ändern, müssen Sie Testcode hinzufügen, um sicherzustellen, dass alle vorgenommenen Änderungen abgedeckt sind.
Da BeeWare jedoch auf mehrere Plattformen sowie auf mehrere
Python-Versionen abzielt, kann eine vollständige Abdeckung nicht auf einer
einzigen Plattform und Python-Version überprüft werden. Um dem Rechnung zu
tragen, sind im Abschnitt tool.coverage.coverage_conditional_plugin.rules von
pyproject.toml mehrere bedingte Abdeckungsregeln definiert (z. B. kann
no-cover-if-is-windows verwendet werden, um einen Code-Block zu kennzeichnen,
der bei der Ausführung der Testsuite unter Windows nicht ausgeführt wird). Diese
Regeln dienen dazu, Codeabschnitte zu identifizieren, die nur auf bestimmten
Plattformen oder Python-Versionen abgedeckt sind.
Es ist zu beachten, dass die Berichterstellung zur Codeabdeckung bei verschiedenen Python-Versionen zu Unregelmäßigkeiten führen kann. Wenn beispielsweise die Codeabdeckungsdateien mit einer Python-Version erstellt wurden, die Berichterstellung jedoch mit einer anderen erfolgt, kann der Bericht falsche positive Ergebnisse für nicht abgedeckte Verzweigungen enthalten. Aus diesem Grund sollte für die Berichterstellung zur Codeabdeckung stets die älteste Python-Version verwendet werden, mit der die Codeabdeckungsdateien erstellt wurden.
Die Ergebnisse der Abdeckung verstehen¶
Am Ende der Ausgabe des Abdeckungstests sollte ein Bericht über die erfassten Abdeckungsdaten erscheinen:
Name Stmts Miss Branch BrPart Deckung Fehlende
---------------------------------------------------
GESAMT 7540 0 1040 0 100,0 %
Das bedeutet, dass die Testsuite jeden möglichen Verzweigungsweg im Code durchlaufen hat. Das ist zwar keine hundertprozentige Garantie dafür, dass keine Fehler vorhanden sind, aber es bedeutet, dass wir jede einzelne Zeile des Codes in der Codebasis testen.
Wenn Sie Änderungen am Code vornehmen, kann es sein, dass dadurch eine Lücke in
der Codeabdeckung entsteht. In diesem Fall zeigt Ihnen der Abdeckungsbericht an,
welche Zeilen nicht ausgeführt werden. Nehmen wir zum Beispiel an, wir hätten
eine Änderung an some/interesting_file.py vorgenommen und dabei neue Logik
hinzugefügt. Der Abdeckungsbericht könnte dann etwa so aussehen:
Name Anweisungen Fehlende Verzweigung BrPart Abdeckung Fehlende
-------------------------------------------------------------------------------
src/some/interesting_file.py 111 1 26 0 98,1 % 170, 302–307, 320–335
-------------------------------------------------------------------------------
GESAMT 7540 1 1726 0 99,9 %
Dies bedeutet, dass Zeile 170, die Zeilen 302–307 sowie ein Sprung von Zeile 320 nach Zeile 335 von der Testsuite nicht ausgeführt werden. Sie müssen neue Tests hinzufügen (oder einen bestehenden Test anpassen), um diese Abdeckung wiederherzustellen.
Bericht zur Abdeckung für die Host-Plattform und die Python-Version¶
Sie können einen Abdeckungsbericht für Ihre Plattform und Python-Version erstellen. Um beispielsweise die Testsuite auszuführen und einen Abdeckungsbericht für Python 3.10 zu erstellen, geben Sie Folgendes ein:
(.venv) $ tox -m test310
(.venv) $ tox -m test310
(.venv) C:\...>tox -m test310
Bericht zur Abdeckung der Host-Plattform¶
Wenn alle unterstützten Python-Versionen für tox verfügbar sind, kann die
Abdeckung für die Host-Plattform durch Ausführen des folgenden Befehls ermittelt
werden:
(.venv) $ tox p -m test-platform
(.venv) $ tox p -m test-platform
(.venv) C:\...>tox p -m test-platform
Berichterstattung in HTML¶
Ein HTML-Abdeckungsbericht kann erstellt werden, indem man an einen beliebigen
Namen der Abdeckungsumgebung -html den Zusatz tox anhängt, zum Beispiel:
(.venv) $ tox -e coverage-platform-html
(.venv) $ tox -e coverage-platform-html
(.venv) C:\...>tox -e coverage-platform-html
Es geht nicht nur darum, Tests zu schreiben!¶
Obwohl wir darauf achten, unseren gesamten Code zu testen, geht es bei dieser Aufgabe nicht nur darum, dieses Testniveau aufrechtzuerhalten. Ein Teil der Aufgabe besteht darin, den Code während der Entwicklung fortlaufend zu überprüfen. Man könnte zwar eine umfassende Reihe von Tests für eine bestimmte Rettungsweste schreiben … aber eine solche Rettungsweste wäre für den vorgesehenen Zweck dennoch unbrauchbar!
Bei der Entwicklung von Tests sollten Sie auch darauf achten, dass das Kernmodul
intern konsistent ist. Wenn dir Methodennamen auffallen, die intern nicht
konsistent sind (z. B. etwas, das in einem Modul on_select heißt, in einem
anderen aber on_selected), oder wenn Daten nicht konsistent behandelt werden,
markiere dies und mache uns darauf aufmerksam, indem du ein Ticket erstellst.
Oder, wenn du dir sicher bist, was zu tun ist, erstelle einen Pull Request, der
das von dir gefundene Problem behebt.
Sobald alles funktioniert, können Sie einen Pull Request einreichen mit Ihren Änderungen.