Test #

Matplotlib utilise le framework pytest .

Les tests sont dans lib/matplotlib/tests, et les personnalisations de l'infrastructure de test pytest sont dans matplotlib.testing.

Exigences #

Pour exécuter les tests, vous devrez configurer Matplotlib pour le développement . Notez en particulier les dépendances supplémentaires pour les tests.

Noter

Nous supposerons que vous souhaitez exécuter les tests dans une configuration de développement.

Bien que vous puissiez exécuter les tests sur une version installée standard de Matplotlib, il s'agit d'un cas d'utilisation beaucoup moins courant. Vous avez toujours besoin des dépendances supplémentaires pour les tests. Vous devez également obtenir les images de référence à partir du référentiel, car elles ne sont pas distribuées avec des packages Matplotlib prédéfinis.

Exécution des tests #

Dans le répertoire racine de votre référentiel de développement, exécutez :

python -m pytest

pytest peut être configuré via de nombreux paramètres de ligne de commande . Certains sont particulièrement utiles :

`-v`ou`--verbose`	Soyez plus verbeux
`-n NUM`	Exécuter des tests en parallèle sur les processus NUM (nécessite pytest-xdist )
`--capture=no`ou`-s`	Ne pas capturer stdout

Pour exécuter un seul test à partir de la ligne de commande, vous pouvez fournir un chemin de fichier, éventuellement suivi de la fonction séparée par deux deux-points, par exemple (les tests n'ont pas besoin d'être installés, mais Matplotlib devrait l'être) :

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

Écrire un test simple #

De nombreux éléments de Matplotlib peuvent être testés à l'aide de tests standards. Par exemple, voici un test de matplotlib/tests/test_basic.py:

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

Pytest détermine quelles fonctions sont des tests en recherchant les fichiers dont les noms commencent par "test_"puis dans ces fichiers les fonctions commençant par "test"ou les classes commençant par "Test".

Certains tests ont des effets secondaires internes qui doivent être nettoyés après leur exécution (comme des figures créées ou modifiées rcParams). Le luminaire pytest matplotlib.testing.conftest.mpl_test_settingsles nettoiera automatiquement; il n'est pas nécessaire de faire quoi que ce soit d'autre.

Données aléatoires dans les tests #

Les données aléatoires sont un moyen très pratique de générer des données pour des exemples, mais le caractère aléatoire est problématique pour les tests (car les tests doivent être déterministes !). Pour contourner ce problème, définissez la graine dans chaque test. Pour le générateur de nombres aléatoires par défaut de numpy, utilisez :

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

puis à utiliser rnglors de la génération des nombres aléatoires.

La graine est l'anniversaire de John Hunter.

Rédaction d'un test de comparaison d'images #

Rédiger un test basé sur des images n'est que légèrement plus difficile qu'un simple test. La principale considération est que vous devez spécifier les images "de base", ou attendues, dans le image_comparison décorateur. Par exemple, ce test génère une seule image et la teste automatiquement :

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)

La première fois que ce test est exécuté, il n'y aura pas d'image de référence à comparer, donc le test échouera. Copiez les images de sortie (dans ce cas result_images/test_lines/test_line_dashes.png) dans le sous-répertoire correct de baseline_imagestree dans le répertoire source (dans ce cas lib/matplotlib/tests/baseline_images/test_lines). Mettez ce nouveau fichier sous contrôle de révision du code source (avec ). Lors de la réexécution des tests, ils devraient maintenant réussir.git add

Les images de base prennent beaucoup de place dans le référentiel Matplotlib. Une approche alternative pour les tests de comparaison d'images consiste à utiliser le check_figures_equaldécorateur, qui doit être utilisé pour décorer une fonction prenant deux Figureparamètres et dessine les mêmes images sur les figures en utilisant deux méthodes différentes (la méthode testée et la méthode de base). Le décorateur organisera la mise en place des figures, puis collectera les résultats dessinés et les comparera.

Consultez la documentation de image_comparisonet check_figures_equalpour plus d'informations sur leur utilisation.

Création d'un nouveau module dans matplotlib.tests #

Nous essayons de garder les tests classés par le module principal qu'ils testent. Par exemple, les tests liés au mathtext.pymodule sont en test_mathtext.py.

Utilisation des actions GitHub pour le CI #

GitHub Actions est un système CI hébergé "dans le cloud".

GitHub Actions est configuré pour recevoir des notifications de nouveaux commits sur les référentiels GitHub et pour exécuter des builds ou des tests lorsqu'il voit ces nouveaux commits. Il recherche un fichier YAML .github/workflowspour voir comment tester le projet.

GitHub Actions est déjà activé pour le référentiel Matplotlib GitHub principal -- par exemple, voir les workflows Tests .

Les actions GitHub doivent être automatiquement activées pour votre fourche Matplotlib personnelle une fois que les fichiers de flux de travail YAML s'y trouvent. Il n'est généralement pas nécessaire d'examiner ces flux de travail, car toute demande d'extraction soumise sur le référentiel Matplotlib principal sera testée. Le flux de travail Tests est ignoré dans les référentiels dupliqués, mais vous pouvez déclencher une exécution manuellement à partir de l' interface Web GitHub .

Vous pouvez voir les résultats des actions GitHub sur https://github.com/your_GitHub_user_name/matplotlib/actions -- voici un exemple .

Utiliser tox #

Tox est un outil pour exécuter des tests sur plusieurs environnements Python, y compris plusieurs versions de Python (par exemple, 3.7, 3.8) et même différentes implémentations Python (par exemple, CPython, PyPy, Jython, etc.), tant que toutes ces versions sont disponible sur le $PATH de votre système (envisagez d'utiliser votre gestionnaire de paquets système, par exemple apt-get, yum ou Homebrew, pour les installer).

tox permet de déterminer facilement si votre copie de travail a introduit des régressions avant de soumettre une pull request. Voici comment l'utiliser :

$ pip install tox
$ tox

Vous pouvez également exécuter tox sur un sous-ensemble d'environnements :

$ tox -e py38,py39

Tox traite tout en série, ce qui peut prendre beaucoup de temps pour tester plusieurs environnements. Pour l'accélérer, vous pouvez essayer d'utiliser une nouvelle version parallélisée de tox appelée detox. Essayez ceci :

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

Tox est configuré à l'aide d'un fichier appelé tox.ini. Vous devrez peut-être modifier ce fichier si vous souhaitez ajouter de nouveaux environnements à tester (par exemple, py33) ou si vous souhaitez modifier les dépendances ou la manière dont les tests sont exécutés. Pour plus d'informations sur le tox.inifichier, consultez la spécification de configuration Tox .

Construire d'anciennes versions de Matplotlib #

Lors de l'exécution d'un pour voir quel commit a introduit un certain bogue, vous devrez peut-être (rarement) créer de très anciennes versions de Matplotlib. Les contraintes suivantes sont à prendre en compte :git bisect

Matplotlib 1.3 (ou antérieur) nécessite numpy 1.8 (ou antérieur).

Test des versions publiées de Matplotlib #

L'exécution des tests sur une installation d'une version publiée (par exemple, le package PyPI ou le package conda) nécessite également une configuration supplémentaire.

Noter

Pour un utilisateur final, il n'est généralement pas nécessaire d'exécuter les tests sur les versions publiées de Matplotlib. Les versions officielles sont testées avant publication.

Installer des dépendances supplémentaires #

Installez les dépendances supplémentaires pour les tests .

Obtenir les images de référence #

De nombreux tests comparent le résultat du tracé à des images de référence. Les images de référence ne font pas partie des versions packagées régulières (roues pip ou packs conda). Si vous souhaitez exécuter des tests avec des images de référence, vous devez obtenir les images de référence correspondant à la version de Matplotlib que vous souhaitez tester.

Pour ce faire, téléchargez la distribution source correspondante matplotlib-X.Y.Z.tar.gzà partir de PyPI ou bien, clonez le référentiel git et . Copiez le dossier dans le dossier de votre installation matplotlib à tester. Le dossier cible correct peut être trouvé en utilisant :git checkout vX.Y.Zlib/matplotlib/tests/baseline_imagesmatplotlib/tests

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

Une copie analogue de lib/mpl_toolkits/tests/baseline_images est nécessaire pour les tests mpl_toolkits.

Lancez les tests #

Pour exécuter tous les tests sur votre version installée de Matplotlib :

python -m pytest --pyargs matplotlib.tests

La portée de la découverte de test peut être réduite à des modules de test uniques ou même à des fonctions uniques :

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