Comment écrire des tests en Python avec doctest

En tant que développeurs, nous écrivons souvent des cas de test et des commentaires pour expliquer notre code. Les commentaires améliorent la lisibilité et la qualité de la base de code. Des commentaires détaillés peuvent nous rappeler pourquoi nous avons implémenté une fonctionnalité précise. Ils peuvent aussi aider d’autres programmeurs à comprendre, maintenir, utiliser et faire évoluer les bases de code.

L’une des bonnes pratiques consiste à rédiger d’abord les commentaires et les cas de test de vos fonctions. Cela vous aide à écrire du code de meilleure qualité tout en gardant à l’esprit les différents cas limites et exigences de la fonction. Toutefois, les méthodes traditionnelles prennent énormément de temps, car il faut préparer un fichier de cas de test distinct et écrire des fonctions détaillées pour chaque test.

Dans ce genre de situation, l’outil doctest de Python est particulièrement utile. La communauté open source a développé le module doctest pour fournir un framework de test efficace pour le développement. Avec doctest, nous pouvons écrire des tests pour le code de notre fonction en définissant les valeurs d’entrée et de sortie, ce qui nous fait gagner du temps et des efforts tout en écrivant du code de grande qualité.

Cela semble intéressant, mais comment écrire concrètement un doctest en Python ? Dans cet article, nous allons voir comment configurer, écrire et tester votre premier doctest, et vous donner toutes les informations nécessaires pour vous lancer.

Comment écrire votre premier doctest

Avant de commencer à écrire votre premier doctest Python, assurez-vous d’avoir installé Python 3 et un environnement de programmation adapté sur votre ordinateur, comme Visual Studio Code (VS Code). Dans ce tutoriel, nous utiliserons VS Code comme environnement de développement intégré (IDE).

Configurer l’IDE

Après avoir installé Python 3, vérifiez que l’installation a réussi. Sous Windows, saisissez l’extrait de code suivant dans l’invite de commandes :

1py -3 --version

Sous macOS ou Unix, ouvrez le terminal et saisissez la commande suivante :

1python3 --version.

Téléchargez ensuite l’IDE Visual Studio Code.

Lancez l’assistant d’installation et suivez les instructions à l’écran pour installer VS Code.

Après avoir lancé VS Code, téléchargez l’extension Python depuis l’onglet Extensions. Vous êtes maintenant prêt à utiliser Python dans VS Code.

Présentation des docstrings

Python dispose d’un module nommé docstring. Les docstrings sont des chaînes littérales que nous utilisons dans la déclaration d’une fonction, d’une classe ou d’un module pour ajouter des commentaires et des cas de test à nos fonctions. Les docstrings sont donc essentielles à la documentation comme aux tests.

Nous pouvons écrire une docstring entre trois guillemets :

1"""

Après la docstring, nous pouvons écrire les commentaires et les tests, eux aussi entre trois guillemets.

1"""

Nous allons découvrir la syntaxe des cas de test et des commentaires au cours de ce tutoriel. À première vue, une docstring et un commentaire peuvent sembler similaires. Pourtant, ils ont des objectifs différents. Les commentaires expliquent l’implémentation du code, tandis que les docstrings documentent les classes, les méthodes et les fonctions. Elles aident les autres programmeurs à comprendre l’objectif d’une fonction et comment l’utiliser dans leur travail.

Le module doctest repère les docstrings dans les définitions de fonctions ou de classes afin de les traiter. Nous faisons précéder les cas de test dans la docstring du symbole >>> pour les identifier et les distinguer des commentaires.

Ouvrez la ligne de commande de votre système d’exploitation et saisissez python3.

« L’interpréteur interactif de Python 3 utilise le symbole >>> comme invite et renvoie le résultat sans ce symbole. Imaginons que nous affichions une valeur. La session interactive ressemble à ceci : »

Le module doctest recherche dans la docstring les motifs qui ressemblent à des sessions interactives Python et les détecte. Une fois repérés, les doctests les exécutent. Les doctests doivent figurer dans la docstring initiale, juste après l’appel de fonction ou l’en-tête de méthode. Veillez à ne pas ajouter d’espaces superflus après avoir écrit le doctest afin d’éviter les erreurs ou les échecs inattendus.

Écrire un doctest

Pour pouvoir utiliser des doctests, commençons par écrire un exemple de code. Dans ce tutoriel, nous allons créer un module simple nommé square.py, qui contient une fonction nommée square. Cette fonction calcule le carré de la valeur fournie en entrée.

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

Nous ajoutons maintenant une docstring à notre fonction. Elle contient une documentation qui précise le rôle de la fonction, ainsi que deux cas de test avec les valeurs d’entrée et les résultats attendus. Ces valeurs servent à tester le résultat obtenu.

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

Comment le résultat obtenu est-il testé ?

Le module doctest analyse la docstring et produit du texte. Il exécute le texte analysé comme une commande de l’interpréteur Python. Il compare ensuite le résultat au résultat attendu indiqué dans la docstring.

Comment exécuter un doctest

Pour exécuter le doctest de notre module, square.py, nous ajoutons la fonction testmod de doctest. La fonction doctest.testmod teste le module m ou le module "_main_" si m n’est pas fourni. Cette fonction est nécessaire pour exécuter doctest.

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.

Il nous suffit ensuite d’exécuter le module square.py dans le terminal à l’aide de la commande :

1python square.py

Comme square.py ne contient qu’une seule fonction, le module doctest ne teste que celle-ci.

Comme aucun résultat ne s’affiche, tous les tests ont réussi. Si un test échoue, l’erreur apparaît dans le terminal et nous pouvons la corriger. Si nous voulons afficher le journal, nous modifions le script en ajoutant -v :

1python square.py -v

Les journaux nous donnent une vue plus détaillée des résultats en affichant les taux de réussite et d’échec de nos tests. Nous pouvons également utiliser un raccourci pratique pour exécuter la fonction testmod sans la fonction main : le module doctest peut être exécuté directement à l’aide de la bibliothèque standard. Pour cela, nous transmettons le nom du module à l’interface de ligne de commande :

1python -m doctest -v square.py

Développons maintenant un peu l’exemple précédent. Que faire si vous souhaitez préciser les types des données d’entrée et de sortie de votre fonction ? Pour cela, il suffit de modifier légèrement notre docstring. À partir de l’exemple précédent, nous ajoutons simplement :

1:param a: int
2:return: int

Notre docstring devient donc :

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

Si nous avons plusieurs paramètres d’entrée, nous pouvons modifier :param. Imaginons que nous ayons deux paramètres d’entrée. La docstring correspondante serait :

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

Nous pouvons répéter cette opération pour autant de paramètres d’entrée que nécessaire.

Félicitations ! Vous venez d’écrire un doctest.

Conclusion

Cet article vous a présenté le module doctest de Python et ses principes de base, et a montré comment les doctests peuvent améliorer la qualité du code et offrir une meilleure approche de la programmation.

L’article a également montré comment intégrer des doctests aux fonctions et les exécuter à l’aide du fichier de code et du terminal, tout en illustrant la simplicité d’utilisation du module doctest dans notre code.

La méthode classique pour tester des fonctions consiste à écrire un script distinct contenant les cas de test. Les doctests évitent d’avoir à écrire de tels scripts et nous permettent de tester notre code plus efficacement. En résumé, ils facilitent les tests et améliorent la qualité de notre code Python.