Framework UnitTest - API Doctest

L'API doctest s'articule autour des deux classes de conteneurs suivantes utilisées pour stocker des exemples interactifs à partir de docstrings -

• Example - Une seule instruction Python, associée à sa sortie attendue.

• DocTest - Une collection d'exemples, généralement extraits d'une seule docstring ou d'un fichier texte.

Les classes de traitement supplémentaires suivantes sont définies pour rechercher, analyser, exécuter et vérifier les exemples de doctest -

• DocTestFinder - Recherche toutes les docstrings dans un module donné et utilise un DocTestParser pour créer un DocTest à partir de chaque docstring contenant des exemples interactifs.

• DocTestParser - Crée un objet doctest à partir d'une chaîne (comme la docstring d'un objet).

• DocTestRunner - Exécute les exemples dans un doctest et utilise un OutputChecker pour vérifier leur sortie.

• OutputChecker - Compare la sortie réelle d'un exemple doctest avec la sortie attendue et décide si elles correspondent.

Classe DocTestFinder

C'est une classe de traitement utilisée pour extraire les doctests qui sont pertinents pour un objet donné, de sa docstring et des docstrings de ses objets contenus. Les doctests peuvent actuellement être extraits des types d'objets suivants - modules, fonctions, classes, méthodes, méthodes statiques, méthodes de classe et propriétés.

Cette classe définit la méthode find (). Il renvoie une liste des DocTests qui sont définis par la docstring de l' objet , ou par l'une des docstrings de ses objets contenus.

Classe DocTestParser

Il s'agit d'une classe de traitement utilisée pour extraire des exemples interactifs d'une chaîne et les utiliser pour créer un objet DocTest. Cette classe définit les méthodes suivantes -

• get_doctest() - Extrayez tous les exemples doctest de la chaîne donnée et rassemblez-les dans un DocTest objet.

• get_examples(string[, name]) - Extraire tous les exemples doctest de la chaîne donnée et les renvoyer sous forme de liste Exampleobjets. Les numéros de ligne sont basés sur 0. Le nom de l'argument facultatif est un nom identifiant cette chaîne et n'est utilisé que pour les messages d'erreur.

• parse(string[, name]) - Divisez la chaîne donnée en exemples et texte intermédiaire, et renvoyez-les sous forme de liste Exampleset des cordes. Numéros de ligne pour leExamplessont basés sur 0. Le nom de l'argument facultatif est un nom identifiant cette chaîne et n'est utilisé que pour les messages d'erreur.

Classe DocTestRunner

Il s'agit d'une classe de traitement utilisée pour exécuter et vérifier les exemples interactifs dans un DocTest. Les méthodes suivantes y sont définies -

report_start ()

Signaler que le testeur est sur le point de traiter l'exemple donné. Cette méthode est fournie pour autoriser les sous-classes deDocTestRunnerpour personnaliser leur sortie; il ne doit pas être appelé directement

report_success ()

Signalez que l'exemple donné s'est exécuté avec succès. Cette méthode est fournie pour permettre aux sous-classes de DocTestRunner de personnaliser leur sortie; il ne doit pas être appelé directement.

report_failure ()

Signaler que l'exemple donné a échoué. Cette méthode est fournie pour autoriser les sous-classes deDocTestRunnerpour personnaliser leur sortie; il ne doit pas être appelé directement.

report_unexpected_exception ()

Signalez que l'exemple donné a soulevé une exception inattendue. Cette méthode est fournie pour permettre aux sous-classes de DocTestRunner de personnaliser leur sortie; il ne doit pas être appelé directement.

exécuter (test)

Exécutez les exemples dans test (un objet DocTest) et affichez les résultats à l'aide de la fonction d'écriture out .

résumer ([verbeux])

Imprimez un résumé de tous les cas de test qui ont été exécutés par ce DocTestRunner et retournez un tuple nommé TestResults (échec, tentative). L' argument détaillé facultatif contrôle le niveau de détail du résumé. Si la verbosité n'est pas spécifiée, la verbosité du DocTestRunner est utilisée.

Classe OutputChecker

Cette classe est utilisée pour vérifier si la sortie réelle d'un exemple doctest correspond à la sortie attendue.

Les méthodes suivantes sont définies dans cette classe -

check_output ()

Revenir Truesi la sortie réelle d'un exemple ( obtenu ) correspond à la sortie attendue ( souhaitée ). Ces chaînes sont toujours considérées comme identiques si elles sont identiques; mais en fonction de l'option que le testeur utilise, plusieurs types de correspondance non exacte sont également possibles. Voir la section Indicateurs d'option et directives pour plus d'informations sur les indicateurs d'option.

output_difference ()

Renvoie une chaîne décrivant les différences entre la sortie attendue pour un exemple donné ( exemple ) et la sortie réelle ( got ).

Intégration de DocTest avec Unittest

Le module doctest fournit deux fonctions qui peuvent être utilisées pour créer des suites de tests unittest à partir de modules et de fichiers texte contenant des doctests. Pour intégrer avec unittest test Discovery, incluez une fonction load_tests () dans votre module de test -

import unittest
import doctest
import doctestexample

def load_tests(loader, tests, ignore):
   tests.addTests(doctest.DocTestSuite(doctestexample))
   return tests

Une suite de tests combinée de tests unittest et doctest sera formée et elle peut maintenant être exécutée par la méthode main () ou run () du module unittest.

Voici les deux principales fonctions de création unittest.TestSuite instances de fichiers texte et modules avec les doctests -

doctest.DocFileSuite ()

Il est utilisé pour convertir les tests doctest d'un ou plusieurs fichiers texte en un unittest.TestSuite. Unittest.TestSuite retourné doit être exécuté par le framework unittest et exécute les exemples interactifs dans chaque fichier. Si l'un des exemples d'un fichier échoue, le test unitaire synthétisé échoue et unfailureException l'exception est levée indiquant le nom du fichier contenant le test et un numéro de ligne (parfois approximatif).

doctest.DocTestSuite ()

Il est utilisé pour convertir les tests doctest d'un module en un unittest.TestSuite.

Unittest.TestSuite retourné doit être exécuté par le framework unittest et exécute chaque doctest dans le module. Si l'un des doctests échoue, le test unitaire synthétisé échoue et unfailureException l'exception est levée indiquant le nom du fichier contenant le test et un numéro de ligne (parfois approximatif)

Sous les couvertures, DocTestSuite () crée un unittest.TestSuite hors des instances doctest.DocTestCase, et DocTestCase est une sous-classe de unittest.TestCase.

De même, DocFileSuite () crée un unittest.TestSuite à partir des instances doctest.DocFileCase, et DocFileCase est une sous-classe de DocTestCase.

Donc, les deux façons de créer une instance unittest.TestSuite exécutent DocTestCase. Lorsque vous exécutez vous-même les fonctions doctest, vous pouvez contrôler directement les options doctest utilisées, en passant des indicateurs d'option aux fonctions doctest.

Cependant, si vous écrivez un framework unittest, unittest contrôle finalement quand et comment les tests sont exécutés. L'auteur du framework veut généralement contrôler les options de rapport doctest (peut-être, par exemple, spécifié par les options de ligne de commande), mais il n'y a aucun moyen de passer des options via unittest aux exécuteurs de test doctest.