Test #

Matplotlib verwendet das Pytest- Framework.

Die Tests sind lib/matplotlib/testsda, und Anpassungen an der Pytest-Testinfrastruktur sind da matplotlib.testing.

Anforderungen #

Um die Tests auszuführen, müssen Sie Matplotlib für die Entwicklung einrichten . Beachten Sie insbesondere die zusätzlichen Abhängigkeiten zum Testen.

Notiz

Wir gehen davon aus, dass Sie die Tests in einem Entwicklungssetup ausführen möchten.

Während Sie die Tests mit einer normal installierten Version von Matplotlib ausführen können, ist dies ein weitaus seltenerer Anwendungsfall. Zum Testen benötigen Sie noch die zusätzlichen Abhängigkeiten . Sie müssen die Referenzbilder zusätzlich aus dem Repository holen, da sie nicht mit vorgefertigten Matplotlib-Paketen verteilt werden.

Ausführen der Tests #

Führen Sie im Stammverzeichnis Ihres Entwicklungs-Repositorys Folgendes aus:

python -m pytest

pytest kann über viele Kommandozeilenparameter konfiguriert werden . Einige besonders nützliche sind:

`-v`oder`--verbose`	Seien Sie ausführlicher
`-n NUM`	Tests parallel über NUM Prozesse ausführen (erfordert pytest-xdist )
`--capture=no`oder`-s`	Erfassen Sie nicht stdout

Um einen einzelnen Test über die Befehlszeile auszuführen, können Sie einen Dateipfad angeben, optional gefolgt von der Funktion, getrennt durch zwei Doppelpunkte, z. B. (Tests müssen nicht installiert werden, aber Matplotlib sollte installiert sein):

pytest lib/matplotlib/tests/test_simplification.py::test_clipping

Einen einfachen Test schreiben #

Viele Elemente von Matplotlib können mit Standardtests getestet werden. Hier ist zum Beispiel ein Test von matplotlib/tests/test_basic.py:

def test_simple():
    """
    very simple example test
    """
    assert 1 + 1 == 2

Pytest bestimmt, welche Funktionen Tests sind, indem es nach Dateien sucht, deren Namen mit beginnen, "test_"und dann innerhalb dieser Dateien nach Funktionen, die mit beginnen, "test"oder nach Klassen, die mit beginnen "Test".

Einige Tests haben interne Seiteneffekte, die nach ihrer Ausführung bereinigt werden müssen (z. B. erstellte Zahlen oder geänderte rcParams). Das pytest-Fixture matplotlib.testing.conftest.mpl_test_settingswird diese automatisch bereinigen; es ist nichts weiter zu tun.

Zufallsdaten in Tests #

Zufallsdaten sind ein sehr bequemer Weg, um Daten für Beispiele zu generieren, jedoch ist die Zufälligkeit für Tests problematisch (da die Tests deterministisch sein müssen!). Um dies zu umgehen, setzen Sie den Seed in jedem Test. Verwenden Sie für den Standard-Zufallszahlengenerator von numpy:

import numpy as np
rng = np.random.default_rng(19680801)

und dann rngbeim Generieren der Zufallszahlen verwenden.

Der Samen ist John Hunters Geburtstag.

Einen Bildvergleichstest schreiben #

Das Schreiben eines bildbasierten Tests ist nur geringfügig schwieriger als ein einfacher Test. Die Hauptüberlegung ist, dass Sie die "Basislinie" oder erwarteten Bilder im image_comparison Dekorator angeben müssen. Dieser Test generiert beispielsweise ein einzelnes Bild und testet es automatisch:

from matplotlib.testing.decorators import image_comparison
import matplotlib.pyplot as plt

@image_comparison(baseline_images=['line_dashes'], remove_text=True,
                  extensions=['png'])
def test_line_dashes():
    fig, ax = plt.subplots()
    ax.plot(range(10), linestyle=(0, (3, 3)), lw=5)

Wenn dieser Test zum ersten Mal ausgeführt wird, gibt es kein Basisbild zum Vergleichen, sodass der Test fehlschlägt. Kopieren Sie die Ausgabebilder (in diesem Fall result_images/test_lines/test_line_dashes.png) in das richtige Unterverzeichnis von baseline_imagestree im Quellverzeichnis (in diesem Fall lib/matplotlib/tests/baseline_images/test_lines). Setzen Sie diese neue Datei unter Quellcode-Revisionskontrolle (mit ). Wenn Sie die Tests erneut ausführen, sollten sie jetzt bestanden werden.git add

Baseline-Images nehmen viel Platz im Matplotlib-Repository ein. Ein alternativer Ansatz für Bildvergleichstests ist die Verwendung des check_figures_equalDecorators, der verwendet werden sollte, um eine Funktion mit zwei FigureParametern zu dekorieren und dieselben Bilder mit zwei verschiedenen Methoden (der getesteten Methode und der Basislinienmethode) auf die Figuren zu zeichnen. Der Dekorateur veranlasst das Aufstellen der Figuren und sammelt dann die gezeichneten Ergebnisse und vergleicht sie.

Weitere Informationen zu ihrer Verwendung finden Sie in der Dokumentation von image_comparisonund .check_figures_equal

Erstellen eines neuen Moduls in matplotlib.tests #

Wir versuchen, die Tests nach dem primären Modul zu kategorisieren, das sie testen. Zum Beispiel sind die Tests zum mathtext.pyModul in test_mathtext.py.

Verwenden von GitHub-Aktionen für CI #

GitHub Actions ist ein gehostetes CI-System „in der Cloud“.

GitHub Actions ist so konfiguriert, dass es Benachrichtigungen über neue Commits an GitHub-Repositorys erhält und Builds oder Tests ausführt, wenn es diese neuen Commits sieht. Es sucht nach einer YAML-Datei, um .github/workflowszu sehen, wie das Projekt getestet wird.

GitHub Actions ist bereits für das Haupt-Matplotlib-GitHub-Repository aktiviert – siehe zum Beispiel die Tests-Workflows .

GitHub-Aktionen sollten automatisch für Ihren persönlichen Matplotlib-Fork aktiviert werden, sobald sich die YAML-Workflow-Dateien darin befinden. Es ist im Allgemeinen nicht notwendig, sich diese Workflows anzusehen, da jede Pull-Anfrage, die gegen das Haupt-Matplotlib-Repository gesendet wird, getestet wird. Der Tests-Workflow wird in Fork-Repositories übersprungen, aber Sie können eine Ausführung manuell über die GitHub-Weboberfläche auslösen .

Sie können die Ergebnisse von GitHub Actions unter https://github.com/your_GitHub_user_name/matplotlib/actions sehen – hier ist ein Beispiel .

Verwendung von Tox #

Tox ist ein Tool zum Ausführen von Tests für mehrere Python-Umgebungen, einschließlich mehrerer Versionen von Python (z. B. 3.7, 3.8) und sogar verschiedener Python-Implementierungen insgesamt (z. B. CPython, PyPy, Jython usw.), solange alle diese Versionen vorhanden sind verfügbar im $PATH Ihres Systems (erwägen Sie die Verwendung Ihres Systempaketmanagers, z. B. apt-get, yum oder Homebrew, um sie zu installieren).

tox macht es einfach festzustellen, ob Ihre Arbeitskopie Regressionen eingeführt hat, bevor Sie einen Pull-Request senden. So verwenden Sie es:

$ pip install tox
$ tox

Sie können tox auch in einer Teilmenge von Umgebungen ausführen:

$ tox -e py38,py39

Tox verarbeitet alles seriell, sodass es lange dauern kann, mehrere Umgebungen zu testen. Um es zu beschleunigen, könnten Sie versuchen, eine neue, parallelisierte Version von tox namens detox. Probieren Sie es aus:

$ pip install -U -i http://pypi.testrun.org detox
$ detox

Tox wird mit einer Datei namens tox.ini. Möglicherweise müssen Sie diese Datei bearbeiten, wenn Sie neue Umgebungen zum Testen hinzufügen möchten (z. B. py33) oder wenn Sie die Abhängigkeiten oder die Art und Weise, wie die Tests ausgeführt werden, anpassen möchten. Weitere Informationen zu der tox.iniDatei finden Sie in der Tox Configuration Specification .

Alte Versionen von Matplotlib erstellen #

Wenn Sie einen ausführen, um zu sehen, welcher Commit einen bestimmten Fehler verursacht hat, müssen Sie möglicherweise (selten) sehr alte Versionen von Matplotlib erstellen. Folgende Einschränkungen sind zu berücksichtigen:git bisect

Matplotlib 1.3 (oder früher) erfordert numpy 1.8 (oder früher).

Freigegebene Versionen von Matplotlib testen #

Das Ausführen der Tests auf einer Installation einer freigegebenen Version (z. B. PyPI-Paket oder Conda-Paket) erfordert außerdem eine zusätzliche Einrichtung.

Notiz

Für einen Endbenutzer besteht normalerweise keine Notwendigkeit, die Tests auf veröffentlichten Versionen von Matplotlib auszuführen. Offizielle Releases werden vor der Veröffentlichung getestet.

Zusätzliche Abhängigkeiten installieren #

Installieren Sie die zusätzlichen Abhängigkeiten zum Testen .

Holen Sie sich die Referenzbilder #

Viele Tests vergleichen das Plotergebnis mit Referenzbildern. Die Referenzbilder sind nicht Teil der regulären Paketversionen (Pip Wheels oder Conda-Pakete). Wenn Sie Tests mit Referenzbildern durchführen möchten, müssen Sie die Referenzbilder erhalten, die der Version von Matplotlib entsprechen, die Sie testen möchten.

Laden Sie dazu entweder die passende Quelldistribution matplotlib-X.Y.Z.tar.gzvon PyPI herunter oder klonen Sie alternativ das Git-Repository und die . Kopieren Sie den Ordner zum Testen in den Ordner Ihrer Matplotlib-Installation. Den richtigen Zielordner finden Sie mit:git checkout vX.Y.Zlib/matplotlib/tests/baseline_imagesmatplotlib/tests

python -c "import matplotlib.tests; print(matplotlib.tests.__file__.rsplit('/', 1)[0])"

Zum Testen ist ein analoges Kopieren von lib/mpl_toolkits/tests/baseline_images notwendig mpl_toolkits.

Führen Sie die Tests aus #

So führen Sie alle Tests auf Ihrer installierten Version von Matplotlib aus:

python -m pytest --pyargs matplotlib.tests

Der Umfang der Testerkennung kann auf einzelne Testmodule oder sogar einzelne Funktionen eingegrenzt werden:

python -m pytest --pyargs matplotlib.tests.test_simplification.py::test_clipping