unittest — Framework de tests unitaires

Code source : Lib/unittest/__init__.py

---

(Si vous êtes déjà familier des concepts de base concernant les tests, vous pouvez souhaiter passer à la liste des méthodes.)

Le cadre applicatif de tests unitaires unittest était au départ inspiré par JUnit et ressemble aux principaux frameworks de tests unitaires des autres langages. Il gère l'automatisation des tests, le partage de code pour la mise en place et la finalisation des tests, l'agrégation de tests en collections, et l'indépendance des tests par rapport au framework utilisé.

Pour y parvenir, unittest gère quelques concepts importants avec une approche orientée objet :

aménagement de test (fixture)

Un aménagement de test <test fixture> (fixture en anglais) désigne la préparation nécessaire au déroulement d'un ou plusieurs tests, et toutes les actions de nettoyage associées. Cela peut concerner, par exemple, la création de bases de données temporaires ou mandataires, de répertoires, ou le démarrage d'un processus serveur.

scénario de test

Un scénario de test est l'élément de base des tests. Il attend une réponse spécifique pour un ensemble particulier d'entrées. unittest fournit une classe de base, TestCase, qui peut être utilisée pour créer de nouveaux scénarios de test.

suite de tests

Une suite de tests est une collection de scénarios de test, de suites de tests ou les deux. Cela sert à regrouper les tests qui devraient être exécutés ensemble.

lanceur de tests

Un lanceur de tests est un composant qui orchestre l'exécution des tests et fournit le résultat pour l'utilisateur. Le lanceur peut utiliser une interface graphique, une interface textuelle, ou renvoie une valeur spéciale pour indiquer les résultats de l'exécution des tests.

Voir aussi

Module doctest

Un autre module de test adoptant une approche très différente.

Simple Smalltalk Testing: With Patterns

Le papier originel de Kent Beck sur les frameworks de test utilisant le modèle sur lequel s'appuie unittest.

pytest

Des cadres applicatifs tiers de tests unitaires avec une syntaxe allégée pour l'écriture des tests. Par exemple, assert func(10) == 42.

The Python Testing Tools Taxonomy

Une liste étendue des outils de test pour Python comprenant des frameworks de tests fonctionnels et des bibliothèques d'objets simulés (mocks).

Testing in Python Mailing List

Un groupe de discussion dédié aux tests, et outils de test, en Python.

The script Tools/unittestgui/unittestgui.py in the Python source distribution is a GUI tool for test discovery and execution. This is intended largely for ease of use for those new to unit testing. For production environments it is recommended that tests be driven by a continuous integration system such as Buildbot, Jenkins or Travis-CI, or AppVeyor.

Exemple basique

Le module unittest fournit un riche ensemble d'outils pour construire et lancer des tests. Cette section montre qu'une petite partie des outils suffit pour satisfaire les besoins de la plupart des utilisateurs.

Voici un court script pour tester trois méthodes de string :

import unittest

class TestStringMethods(unittest.TestCase):

    def test_upper(self):
        self.assertEqual('foo'.upper(), 'FOO')

    def test_isupper(self):
        self.assertTrue('FOO'.isupper())
        self.assertFalse('Foo'.isupper())

    def test_split(self):
        s = 'hello world'
        self.assertEqual(s.split(), ['hello', 'world'])
        # check that s.split fails when the separator is not a string
        with self.assertRaises(TypeError):
            s.split(2)

if __name__ == '__main__':
    unittest.main()

Un scénario de test est créé comme classe-fille de unittest.TestCase. Les trois tests individuels sont définis par des méthodes dont les noms commencent par les lettres test. Cette convention de nommage signale au lanceur de tests quelles méthodes sont des tests.

Le cœur de chaque test est un appel à assertEqual() pour vérifier un résultat attendu ; assertTrue() ou assertFalse() pour vérifier une condition ; ou assertRaises() pour vérifier qu'une exception particulière est levée. Ces méthodes sont utilisées à la place du mot-clé assert pour que le lanceur de tests puisse récupérer les résultats de tous les tests et produire un rapport.

Les méthodes setUp() et tearDown() vous autorisent à définir des instructions qui seront exécutées avant et après chaque méthode test. Elles sont davantage détaillées dans la section Organiser le code de test.

Le bloc final montre une manière simple de lancer les tests. unittest.main() fournit une interface en ligne de commande pour le script de test. Lorsqu'il est lancé en ligne de commande, le script ci-dessus produit une sortie qui ressemble à ceci :

...
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK

Passer l'option -v à votre script de test informera unittest.main() qu'il doit fournir un niveau plus important de détails, et produit la sortie suivante :

test_isupper (__main__.TestStringMethods) ... ok
test_split (__main__.TestStringMethods) ... ok
test_upper (__main__.TestStringMethods) ... ok

----------------------------------------------------------------------
Ran 3 tests in 0.001s

OK

Les exemples ci-dessus montrent les fonctionnalités d'unittest les plus communément utilisées et qui sont suffisantes pour couvrir les besoins courants en matière de test. Le reste de la documentation explore l'ensemble complet des fonctionnalités depuis les premiers principes.

Interface en ligne de commande

Le module unittest est utilisable depuis la ligne de commande pour exécuter des tests à partir de modules, de classes ou même de méthodes de test individuelles :

python -m unittest test_module1 test_module2
python -m unittest test_module.TestClass
python -m unittest test_module.TestClass.test_method

La commande accepte en argument une liste de n'importe quelle combinaison de noms de modules et de noms de classes ou de méthodes entièrement qualifiés.

Les modules de test peuvent également être spécifiés par un chemin de fichier :

python -m unittest tests/test_something.py

Cette fonctionnalité permet d'utiliser la complétion de l'interpréteur de commandes système (le shell) pour spécifier le module de test. Le chemin est converti en nom de module en supprimant le .py et en convertissant les séparateurs de chemin en '.'. Si vous voulez exécuter un fichier test qui n'est pas importable en tant que module, exécutez directement le fichier.

Pour obtenir plus de détails lors de l'exécution utilisez l'option -v (plus de verbosité) :

python -m unittest -v test_module

Quand la commande est exécutée sans arguments Découverte des tests est lancée :

python -m unittest

Pour afficher la liste de toutes les options de la commande utilisez l'option -h :

python -m unittest -h

Modifié dans la version 3.2: Dans les versions antérieures, il était seulement possible d'exécuter des méthodes de test individuelles et non des modules ou des classes.

Options de la ligne de commande

Le programme : unittest gère ces options de la ligne de commande :

-b, --buffer

Les flux de sortie et d'erreur standards sont mis en mémoire tampon pendant l'exécution des tests. L'affichage produit par un test réussi n'est pas pris en compte. Les sorties d'affichages d'un test en échec ou en erreur sont conservés et ajoutés aux messages d'erreur.

-c, --catch

Utiliser Control-C pendant l'exécution des tests attend que le test en cours se termine, puis affiche tous les résultats obtenus jusqu'ici. Une seconde utilisation de Control-C provoque l'exception normale KeyboardInterrupt.

Voir Signal Handling pour les fonctions qui utilisent cette fonctionnalité.

-f, --failfast

Arrête l'exécution des tests lors du premier cas d'erreur ou d'échec.

-k

Exécute uniquement les méthodes de test et les classes qui correspondent au motif ou à la chaîne de caractères. Cette option peut être utilisée plusieurs fois ; dans ce cas, tous les tests qui correspondent aux motifs donnés sont inclus.

Les motifs qui contiennent un caractère de remplacement (*) sont comparés au nom du test en utilisant fnmatch.fnmatchcase() ; sinon, une recherche simple de sous chaîne respectant la casse est faite.

Les motifs sont comparés au nom de la méthode de test complètement qualifiée tel qu'importé par le chargeur de test.

Par exemple, -k machin retient les tests machin_tests.UnTest.test_untruc, truc_tests.UnTest.test_machin, mais pas truc_tests.MachinTest.test_untruc.

--locals

Affiche les variables locales dans les traces d'appels.

Nouveau dans la version 3.2: Les options de ligne de commande -b, -c et -f ont été ajoutées.

Nouveau dans la version 3.5: Ajout de l'option de ligne de commande --locals.

Nouveau dans la version 3.7: Ajout de l'option de ligne de commande -k.

La ligne de commande peut également être utilisée pour découvrir les tests, pour exécuter tous les tests dans un projet ou juste un sous-ensemble.

Découverte des tests

Nouveau dans la version 3.2.

Unittest prend en charge une découverte simple des tests. Afin d'être compatible avec le système de découverte de tests, tous les fichiers de test doivent être des modules ou des paquets (incluant des paquets-espaces de nommage) importables du répertoire du projet (cela signifie que leurs noms doivent être des identifiants valables).

La découverte de tests est implémentée dans TestLoader.discover(), mais peut également être utilisée depuis la ligne de commande. Par exemple :

cd project_directory
python -m unittest discover

Note

Comme raccourci, python -m unittest est l'équivalent de python -m unittest discover. Pour passer des arguments au système de découverte des tests, la sous-commande discover doit être utilisée explicitement.

La sous-commande discover a les options suivantes  :

-v, --verbose

Affichage plus détaillé

-s, --start-directory directory

Répertoire racine pour démarrer la découverte (. par défaut).

-p, --pattern pattern

Motif de détection des fichiers de test (test*.py par défaut)

-t, --top-level-directory directory

Dossier du premier niveau du projet (Par défaut le dossier de départ)

Les options -s, -p et -t peuvent être passées en arguments positionnels dans cet ordre. Les deux lignes de commande suivantes sont équivalentes :

python -m unittest discover -s project_directory -p "*_test.py"
python -m unittest discover project_directory "*_test.py"

Il est aussi possible de passer un nom de paquet plutôt qu'un chemin, par exemple monprojet.souspaquet.test, comme répertoire racine. Le nom du paquet fourni est alors importé et son emplacement sur le système de fichiers est utilisé comme répertoire racine.

Prudence

Le mécanisme de découverte charge les tests en les important. Une fois que le système a trouvé tous les fichiers de tests du répertoire de démarrage spécifié, il transforme les chemins en noms de paquets à importer. Par exemple truc/bidule/machin.py est importé sous truc.bidule.machin.

Si un paquet est installé globalement et que le mécanisme de découverte de tests est effectué sur une copie différente du paquet, l'importation peut se produire à partir du mauvais endroit. Si cela arrive, le système émet un avertissement et se termine.

Si vous donnez le répertoire racine sous la forme d'un nom de paquet plutôt que d'un chemin d'accès à un répertoire, alors Python suppose que l'emplacement à partir duquel il importe est l'emplacement que vous voulez, vous ne verrez donc pas l'avertissement.

Les modules de test et les paquets peuvent adapter le chargement et la découverte des tests en utilisant le protocole load_tests protocol.

Modifié dans la version 3.4: Test discovery supports namespace packages for start directory. Note that you need to the top level directory too. (e.g. python -m unittest discover -s root/namespace -t root).

Organiser le code de test

Les éléments de base des tests unitaires sont les scénarios de tests (test cases en anglais) --- Des scénarios uniques qui sont mis en place et exécutés pour vérifier qu'ils sont corrects. Dans unittest, les scénarios de test sont représentés par des instances de unittest.TestCase. Pour créer vos propres scénarios de test, vous devez écrire des sous-classes de TestCase ou utiliser FunctionTestCase.

Le code de test d'une instance de TestCase doit être entièrement autonome, de sorte qu'il puisse être exécuté soit de manière isolée, soit en combinaison arbitraire avec un nombre quelconque d'autres scénarios de test.

La sous-classe TestCase la plus simple va tout simplement implémenter une méthode de test (c'est-à-dire une méthode dont le nom commence par test) afin d'exécuter un code de test spécifique :

import unittest

class DefaultWidgetSizeTestCase(unittest.TestCase):
    def test_default_widget_size(self):
        widget = Widget('The widget')
        self.assertEqual(widget.size(), (50, 50))

Notez que pour tester quelque chose, on utilise l'une des méthodes assert*() fournies par la classe de base TestCase. Si le test échoue, une exception est levée avec un message explicatif, et unittest identifie ce scénario de test comme un échec. Toute autre exception est traitée comme une erreur.

Les tests peuvent être nombreux et leur mise en place peut être répétitive. Heureusement, on peut factoriser le code de mise en place en implémentant une méthode appelée setUp(), que le système de test appelle automatiquement pour chaque test exécuté :

import unittest

class WidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

    def test_default_widget_size(self):
        self.assertEqual(self.widget.size(), (50,50),
                         'incorrect default size')

    def test_widget_resize(self):
        self.widget.resize(100,150)
        self.assertEqual(self.widget.size(), (100,150),
                         'wrong size after resize')

Note

L'ordre dans lequel les différents tests sont exécutés est déterminé en classant les noms des méthodes de test en fonction de la relation d'ordre des chaines de caractères .

Si la méthode setUp() lève une exception pendant l'exécution du test, le système considère que le test a subi une erreur, et la méthode test n'est pas exécutée.

De même, on peut fournir une méthode tearDown() qui nettoie après l'exécution de la méthode de test :

import unittest

class WidgetTestCase(unittest.TestCase):
    def setUp(self):
        self.widget = Widget('The widget')

    def tearDown(self):
        self.widget.dispose()

Si setUp() a réussi, tearDown() est exécutée, que la méthode de test ait réussi ou non.

Un tel environnement de travail pour le code de test s'appelle un aménagement de test (fixture en anglais). Une nouvelle instance de TestCase est créée sous la forme d'un dispositif de test unique utilisé pour exécuter chaque méthode de test individuelle. Ainsi setUp(), tearDown() et __init__() ne sont appelées qu'une fois par test.

Il est recommandé d'utiliser TestCase pour regrouper les tests en fonction des fonctionnalités qu'ils testent. unittest fournit un mécanisme pour cela : la suite de tests, représentée par TestSuite du module unittest. Dans la plupart des cas, appeler unittest.main() fait correctement les choses et trouve tous les scénarios de test du module pour vous et les exécute.

Cependant, si vous voulez personnaliser la construction de votre suite de tests, vous pouvez le faire vous-même :

def suite():
    suite = unittest.TestSuite()
    suite.addTest(WidgetTestCase('test_default_widget_size'))
    suite.addTest(WidgetTestCase('test_widget_resize'))
    return suite

if __name__ == '__main__':
    runner = unittest.TextTestRunner()
    runner.run(suite())

Vous pouvez placer les définitions des scénarios de test et des suites de test dans le même module que le code à tester (tel que composant.py), mais il y a plusieurs avantages à placer le code de test dans un module séparé, tel que test_composant.py :

• Le module de test peut être exécuté indépendamment depuis la ligne de commande.

• Le code de test est plus facilement séparable du code livré.

• La tentation est moins grande de changer le code de test pour l'adapter au code qu'il teste sans avoir une bonne raison.

• Le code de test doit être modifié beaucoup moins souvent que le code qu'il teste.

• Le code testé peut être réusiné plus facilement.

• Les tests pour les modules écrits en C doivent de toute façon être dans des modules séparés, alors pourquoi ne pas être cohérent ?

• Si la stratégie de test change, il n'est pas nécessaire de changer le code source.

Réutilisation d'ancien code de test

Certains utilisateurs constatent qu'ils ont du code de test existant qu'ils souhaitent exécuter à partir de unittest, sans convertir chaque ancienne fonction de test en une sous-classe de TestCase.

Pour cette raison, unittest fournit une classe FunctionTestCase. Cette sous-classe de TestCase peut être utilisée pour encapsuler une fonction de test existante. Des fonctions de mise en place (setUp) et de démantèlement (tearDown) peuvent également être fournies.

Étant donnée la fonction de test suivante :

def testSomething():
    something = makeSomething()
    assert something.name is not None
    # ...

on peut créer une instance de scénario de test équivalente, avec des méthodes optionnelles de mise en place et de démantèlement :

testcase = unittest.FunctionTestCase(testSomething,
                                     setUp=makeSomethingDB,
                                     tearDown=deleteSomethingDB)

Note

Même si la classe FunctionTestCase peut être utilisée pour convertir rapidement une base de test existante vers un système basé sur unittest, cette approche n'est pas recommandée. Prendre le temps de bien configurer les sous-classes de TestCase simplifiera considérablement les futurs réusinages des tests.

Dans certains cas, les tests déjà existants ont pu être écrits avec le module doctest. Dans ce cas, doctest fournit une classe DocTestSuite qui peut construire automatiquement des instances de la classe unittest.TestSuite depuis des tests basés sur le module doctest.

Ignorer des tests et des erreurs prévisibles

Nouveau dans la version 3.1.

Unittest permet d'ignorer des méthodes de test individuelles et même des classes entières de tests. De plus, il prend en charge le marquage d'un test comme étant une "erreur prévue". Un test qui est cassé et qui échoue, mais qui ne doit pas être considéré comme un échec dans la classe TestResult.

Ignorer un test consiste à soit utiliser le décorateur skip() ou une de ses variantes conditionnelles, soit appeler TestCase.skipTest() à l'intérieur d'une méthode setUp() ou de test, soit lever SkipTest directement.

Un exemple de tests à ignorer :

class MyTestCase(unittest.TestCase):

    @unittest.skip("demonstrating skipping")
    def test_nothing(self):
        self.fail("shouldn't happen")

    @unittest.skipIf(mylib.__version__ < (1, 3),
                     "not supported in this library version")
    def test_format(self):
        # Tests that work for only a certain version of the library.
        pass

    @unittest.skipUnless(sys.platform.startswith("win"), "requires Windows")
    def test_windows_support(self):
        # windows specific testing code
        pass

    def test_maybe_skipped(self):
        if not external_resource_available():
            self.skipTest("external resource not available")
        # test code that depends on the external resource
        pass

Ceci est le résultat de l'exécution de l'exemple ci-dessus en mode verbeux :

test_format (__main__.MyTestCase) ... skipped 'not supported in this library version'
test_nothing (__main__.MyTestCase) ... skipped 'demonstrating skipping'
test_maybe_skipped (__main__.MyTestCase) ... skipped 'external resource not available'
test_windows_support (__main__.MyTestCase) ... skipped 'requires Windows'

----------------------------------------------------------------------
Ran 4 tests in 0.005s

OK (skipped=4)

Les classes peuvent être ignorées tout comme les méthodes :

@unittest.skip("showing class skipping")
class MySkippedTestCase(unittest.TestCase):
    def test_not_run(self):
        pass

La méthode TestCase.setUp() permet également d'ignorer le test. Ceci est utile lorsqu'une ressource qui doit être configurée n'est pas disponible.

Les erreurs prévisibles utilisent le décorateur expectedFailure()

class ExpectedFailureTestCase(unittest.TestCase):
    @unittest.expectedFailure
    def test_fail(self):
        self.assertEqual(1, 0, "broken")

Il est facile de faire ses propres décorateurs en créant un décorateur qui appelle skip() sur le test que vous voulez ignorer. Par exemple, ce décorateur ignore le test à moins que l'objet passé ne possède un certain attribut :

def skipUnlessHasattr(obj, attr):
    if hasattr(obj, attr):
        return lambda func: func
    return unittest.skip("{!r} doesn't have {!r}".format(obj, attr))

Les décorateurs et exceptions suivants implémentent le système d'omission des tests et les erreurs prévisibles  :

@unittest.skip(reason)

Ignore sans condition le test décoré. La raison doit décrire la raison pour laquelle le test est omis.

@unittest.skipIf(condition, reason)

Ignore le test décoré si la condition est vraie.

@unittest.skipUnless(condition, reason)

Ignore le test décoré sauf si la condition est vraie.

@unittest.expectedFailure

Mark the test as an expected failure or error. If the test fails or errors it will be considered a success. If the test passes, it will be considered a failure.

exception unittest.SkipTest(reason)

Cette exception est levée pour ignorer un test.

Habituellement, on utilise TestCase.skipTest() ou l'un des décorateurs d'omission au lieu de le lever une exception directement.

Les tests ignorés ne lancent ni setUp() ni tearDown(). Les classes ignorées ne lancent ni setUpClass() ni tearDownClass(). Les modules sautés n'ont pas setUpModule() ou tearDownModule() d'exécutés.

Distinguer les itérations de test à l'aide de sous-tests

Nouveau dans la version 3.4.

Lorsque certains de vos tests ne diffèrent que par de très petites différences, par exemple certains paramètres, unittest vous permet de les distinguer en utilisant le gestionnaire de contexte subTest() dans le corps d'une méthode de test.

Par exemple, le test suivant :

class NumbersTest(unittest.TestCase):

    def test_even(self):
        """
        Test that numbers between 0 and 5 are all even.
        """
        for i in range(0, 6):
            with self.subTest(i=i):
                self.assertEqual(i % 2, 0)

produit le résultat suivant :

======================================================================
FAIL: test_even (__main__.NumbersTest) (i=1)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0

======================================================================
FAIL: test_even (__main__.NumbersTest) (i=3)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0

======================================================================
FAIL: test_even (__main__.NumbersTest) (i=5)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0

Sans l'utilisation d'un sous-test, l'exécution se termine après le premier échec, et l'erreur est moins facile à diagnostiquer car la valeur de i ne s'affiche pas :

======================================================================
FAIL: test_even (__main__.NumbersTest)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "subtests.py", line 32, in test_even
    self.assertEqual(i % 2, 0)
AssertionError: 1 != 0

Classes et fonctions

Cette section décrit en détail l'API de unittest.

Scénarios de tests

class unittest.TestCase(methodName='runTest')

Les instances de la classe TestCase représentent des tests logiques unitaires dans l'univers unittest. Cette classe est conçue pour être utilisée comme classe de base. Les scénarios de tests sont à implémenter en héritant de cette classe. La classe implémente l'interface nécessaire au lanceur de tests pour lui permettre de les exécuter ainsi que les méthodes que le code de test peut utiliser pour vérifier et signaler les différents types d'erreurs.

Chaque instance de la classe TestCase n'exécute qu'une seule méthode de base : la méthode nommée methodName . Dans la plupart des utilisations de la classe TestCase, vous n'avez pas à changer le nom de la méthode, ni à réimplémenter la méthode runTest().

Modifié dans la version 3.2: La classe TestCase peut désormais être utilisée sans passer de paramètre methodName. Cela facilite l'usage de TestCase dans l'interpréteur interactif.

Les instances de la classe TestCase fournissent trois groupes de méthodes : un groupe utilisé pour exécuter le test, un autre utilisé par l'implémentation du test pour vérifier les conditions et signaler les échecs, et quelques méthodes de recherche permettant de recueillir des informations sur le test lui-même.

Les méthodes du premier groupe (exécution du test) sont :

setUp()

Méthode appelée pour réaliser la mise en place du test. Elle est exécutée immédiatement avant l'appel de la méthode de test ; à l'exception de AssertionError ou SkipTest, toute exception levée par cette méthode est considérée comme une erreur et non pas comme un échec du test. L'implémentation par défaut ne fait rien.

tearDown()

Méthode appelée immédiatement après l'appel de la méthode de test et l'enregistrement du résultat. Elle est appelée même si la méthode de test a levé une exception. De fait, l'implémentation d'un sous-classes doit être fait avec précaution si vous vérifiez l'état interne de la classe. Toute exception, autre que AssertionError ou SkipTest, levée par cette méthode est considérée comme une erreur supplémentaire plutôt que comme un échec du test (augmentant ainsi le nombre total des erreurs signalées). Cette méthode est appelée uniquement si l'exécution de setUp() est réussie quel que soit le résultat de la méthode de test. L'implémentation par défaut ne fait rien.

setUpClass()

Méthode de classe appelée avant l'exécution des tests dans la classe en question. setUpClass est appelée avec la classe comme seul argument et doit être décorée comme une classmethod() :

@classmethod
def setUpClass(cls):
    ...

Voir Class and Module Fixtures pour plus de détails.

Nouveau dans la version 3.2.

tearDownClass()

Méthode de classe appelée après l'exécution des tests de la classe en question. tearDownClass est appelée avec la classe comme seul argument et doit être décorée comme une classmethod() :

@classmethod
def tearDownClass(cls):
    ...

Voir Class and Module Fixtures pour plus de détails.

Nouveau dans la version 3.2.

run(result=None)

Exécute le test, en collectant le résultat dans l'objet TestResult passé comme result. Si result est omis ou vaut None, un objet temporaire de résultat est créé (en appelant la méthode defaultTestResult()) et utilisé. L'objet résultat est renvoyé à l'appelant de run().

Le même effet peut être obtenu en appelant simplement l'instance TestCase.

Modifié dans la version 3.3: Les versions précédentes de run ne renvoyaient pas le résultat. Pas plus que l'appel d'une instance.

skipTest(reason)

Appeler cette fonction pendant l'exécution d'une méthode de test ou de setUp() permet d'ignorer le test en cours. Voir Ignorer des tests et des erreurs prévisibles pour plus d'informations.

Nouveau dans la version 3.1.

subTest(msg=None, **params)

Renvoie un gestionnaire de contexte qui exécute le bloc de code du contexte comme un sous-test. msg et params sont des valeurs optionnelles et arbitraires qui sont affichées chaque fois qu'un sous-test échoue, permettant de les identifier clairement.

Un scénario de test peut contenir un nombre quelconque de déclarations de sous-test, et elles peuvent être imbriquées librement.

Voir Distinguer les itérations de test à l'aide de sous-tests pour plus d'informations.

Nouveau dans la version 3.4.

debug()

Lance le test sans collecter le résultat. Ceci permet aux exceptions levées par le test d'être propagées à l'appelant, et donc peut être utilisé pour exécuter des tests sous un débogueur.

La classe TestCase fournit plusieurs méthodes d'assertion pour vérifier et signaler les échecs. Le tableau suivant énumère les méthodes les plus couramment utilisées (voir les tableaux ci-dessous pour plus de méthodes d'assertion) :

Méthode	Vérifie que	Disponible en
assertEqual(a, b)	a == b
assertNotEqual(a, b)	a != b
assertTrue(x)	bool(x) is True
assertFalse(x)	bool(x) is False
assertIs(a, b)	a is b	3.1
assertIsNot(a, b)	a is not b	3.1
assertIsNone(x)	x is None	3.1
assertIsNotNone(x)	x is not None	3.1
assertIn(a, b)	a in b	3.1
assertNotIn(a, b)	a not in b	3.1
assertIsInstance(a, b)	isinstance(a, b)	3.2
assertNotIsInstance(a, b)	not isinstance(a, b)	3.2

Toutes les méthodes assert prennent en charge un argument msg qui, s'il est spécifié, est utilisé comme message d'erreur en cas d'échec (voir aussi longMessage). Notez que l'argument mot-clé msg peut être passé à assertRaises(), assertRaisesRegex(), assertWarns(), assertWarnsRegex(), seulement quand elles sont utilisées comme gestionnaire de contexte.

assertEqual(first, second, msg=None)

Vérifie que first et second sont égaux. Si les valeurs ne sont pas égales, le test échouera.

En outre, si first et second ont exactement le même type et sont de type liste, tuple, dict, set, frozenset ou str ou tout autre type de sous classe enregistrée dans addTypeEqualityFunc(). La fonction égalité spécifique au type sera appelée pour générer une erreur plus utile (voir aussi liste des méthodes spécifiques de type).

Modifié dans la version 3.1: Ajout de l'appel automatique de la fonction d'égalité spécifique au type.

Modifié dans la version 3.2: Ajout de assertMultiLineEqual() comme fonction d'égalité de type par défaut pour comparer les chaînes.

assertNotEqual(first, second, msg=None)

Vérifie que first et second ne sont pas égaux. Si les valeurs sont égales, le test échouera.

assertTrue(expr, msg=None)

assertFalse(expr, msg=None)

Vérifie que expr est vraie (ou fausse).

Notez que cela revient à utiliser bool(expr) is True et non à expr is True (utilisez assertIs(expr, True) pour cette dernière). Cette méthode doit également être évitée lorsque des méthodes plus spécifiques sont disponibles (par exemple assertEqual(a, b) au lieu de assertTrue(a == b)), car elles fournissent un meilleur message d'erreur en cas d' échec.

assertIs(first, second, msg=None)

assertIsNot(first, second, msg=None)

Vérifie que first et second sont (ou ne sont pas) le même objet.

Nouveau dans la version 3.1.

assertIsNone(expr, msg=None)

assertIsNotNone(expr, msg=None)

Vérifie que expr est (ou n'est pas) la valeur None.

Nouveau dans la version 3.1.

assertIn(member, container, msg=None)

assertNotIn(member, container, msg=None)

Vérifie que member est (ou n'est pas) dans container.

Nouveau dans la version 3.1.

assertIsInstance(obj, cls, msg=None)

assertNotIsInstance(obj, cls, msg=None)

Vérifie que obj est (ou n'est pas) une instance de cls (Ce qui peut être une classe ou un tuple de classes, comme utilisée par isinstance()). Pour vérifier le type exact, utilisez assertIs(type(obj), cls).

Nouveau dans la version 3.2.

Il est également possible de vérifier la production des exceptions, des avertissements et des messages de journaux à l'aide des méthodes suivantes :

Méthode	Vérifie que	Disponible en
assertRaises(exc, fun, *args, **kwds)	fun(*args, **kwds) lève bien l'exception exc
assertRaisesRegex(exc, r, fun, *args, **kwds)	fun(*args, **kwds) lève bien l'exception exc et que le message correspond au motif de l'expression régulière r	3.1
assertWarns(warn, fun, *args, **kwds)	fun(*args, **kwds) lève bien l'avertissement warn	3.2
assertWarnsRegex(warn, r, fun, *args, **kwds)	fun(*args, **kwds) lève bien l'avertissement warn et que le message correspond au motif de l'expression régulière r	3.2
assertLogs(logger, level)	Le bloc with écrit dans le logger avec un niveau minimum égal à level	3.4

assertRaises(exception, callable, *args, **kwds)

assertRaises(exception, *, msg=None)

Vérifie qu'une exception est levée lorsque callable est appelé avec n'importe quel argument positionnel ou mot-clé qui est également passé à assertRaises(). Le test réussit si exception est levée, est en erreur si une autre exception est levée, ou en échec si aucune exception n'est levée. Pour capturer une exception d'un groupe d'exceptions, un n-uplet contenant les classes d'exceptions peut être passé à exception.

Si seuls les arguments exception et éventuellement msg sont donnés, renvoie un gestionnaire de contexte pour que le code sous test puisse être écrit en ligne plutôt que comme une fonction :

with self.assertRaises(SomeException):
    do_something()

Lorsqu'il est utilisé comme gestionnaire de contexte, assertRaises() accepte l'argument de mot-clé supplémentaire msg.

Le gestionnaire de contexte enregistre l'exception interceptée dans son attribut exception. Ceci est particulièrement utile si l'intention est d'effectuer des contrôles supplémentaires sur l'exception levée :

with self.assertRaises(SomeException) as cm:
    do_something()

the_exception = cm.exception
self.assertEqual(the_exception.error_code, 3)

Modifié dans la version 3.1: Ajout de la possibilité d'utiliser assertRaises() comme gestionnaire de contexte.

Modifié dans la version 3.2: Ajout de l'attribut exception.

Modifié dans la version 3.3: Ajout de l'argument msg comme mot-clé lorsqu'il est utilisé comme gestionnaire de contexte.

assertRaisesRegex(exception, regex, callable, *args, **kwds)

assertRaisesRegex(exception, regex, *, msg=None)

Comme assertRaises() mais vérifie aussi que regex correspond à la représentation de la chaîne de caractères de l'exception levée. regex peut être un objet d'expression rationnelle ou une chaîne contenant une expression rationnelle appropriée pour être utilisée par re.search(). Exemples :

self.assertRaisesRegex(ValueError, "invalid literal for.*XYZ'$",
                       int, 'XYZ')

ou :

with self.assertRaisesRegex(ValueError, 'literal'):
   int('XYZ')

Nouveau dans la version 3.1: Sous le nom assertRaisesRegexp.

Modifié dans la version 3.2: Renommé en assertRaisesRegex().

Modifié dans la version 3.3: Ajout de l'argument msg comme mot-clé lorsqu'il est utilisé comme gestionnaire de contexte.

assertWarns(warning, callable, *args, **kwds)

assertWarns(warning, *, msg=None)

Test qu'un avertissement est déclenché lorsque callable est appelé avec n'importe quel argument positionnel ou mot-clé qui est également passé à assertWarns(). Le test passe si warning est déclenché et échoue s'il ne l'est pas. Toute exception est une erreur. Pour capturer un avertissement dans un ensemble d'avertissements, un n-uplet contenant les classes d'avertissement peut être passé à warnings.

Si seuls les arguments * warning* et éventuellement msg sont donnés, renvoie un gestionnaire de contexte pour que le code testé puisse être écrit en ligne plutôt que comme une fonction :

with self.assertWarns(SomeWarning):
    do_something()

Lorsqu'il est utilisé comme gestionnaire de contexte, assertWarns() accepte l'argument de mot-clé supplémentaire msg.

Le gestionnaire de contexte stocke l'avertissement capturé dans son attribut warning, et la ligne source qui a déclenché les avertissements dans les attributs filename et lineno. Cette fonction peut être utile si l'intention est d'effectuer des contrôles supplémentaires sur l'avertissement capturé :

with self.assertWarns(SomeWarning) as cm:
    do_something()

self.assertIn('myfile.py', cm.filename)
self.assertEqual(320, cm.lineno)

Cette méthode fonctionne indépendamment des filtres d'avertissement en place lorsqu'elle est appelée.

Nouveau dans la version 3.2.

Modifié dans la version 3.3: Ajout de l'argument msg comme mot-clé lorsqu'il est utilisé comme gestionnaire de contexte.

assertWarnsRegex(warning, regex, callable, *args, **kwds)

assertWarnsRegex(warning, regex, *, msg=None)

Comme assertWarns() mais vérifie aussi qu'une regex corresponde au message de l'avertissement. regex peut être un objet d'expression régulière ou une chaîne contenant une expression régulière appropriée pour être utilisée par re.search(). Exemple :

self.assertWarnsRegex(DeprecationWarning,
                      r'legacy_function\(\) is deprecated',
                      legacy_function, 'XYZ')

ou :

with self.assertWarnsRegex(RuntimeWarning, 'unsafe frobnicating'):
    frobnicate('/etc/passwd')

Nouveau dans la version 3.2.

Modifié dans la version 3.3: Ajout de l'argument msg comme mot-clé lorsqu'il est utilisé comme gestionnaire de contexte.

assertLogs(logger=None, level=None)

Un gestionnaire de contexte pour tester qu'au moins un message est enregistré sur le logger ou un de ses enfants, avec au moins le niveau donné.

Si donné, logger doit être une classe logging.logger objet ou une classe str donnant le nom d'un journal. La valeur par défaut est le journal racine root, qui capture tous les messages qui n'ont pas été arrêtés par un logger ne propageant pas les messages.

S'il est donné, level doit être soit un entier, soit son équivalent sous forme de chaîne (par exemple "ERROR" ou logging.ERROR). La valeur par défaut est logging.INFO.

Le test passe si au moins un message émis à l'intérieur du bloc with correspond aux conditions logger et level, sinon il échoue.

L'objet retourné par le gestionnaire de contexte est une aide à l'enregistrement qui garde la trace des messages de journal correspondants. Il a deux attributs  :

records

Une liste d'objets logging.LogRecord de messages de log correspondants.

output

Une liste d'objets str avec la sortie formatée des messages correspondants.

Exemple :

with self.assertLogs('foo', level='INFO') as cm:
   logging.getLogger('foo').info('first message')
   logging.getLogger('foo.bar').error('second message')
self.assertEqual(cm.output, ['INFO:foo:first message',
                             'ERROR:foo.bar:second message'])

Nouveau dans la version 3.4.

Il existe également d'autres méthodes utilisées pour effectuer des contrôles plus spécifiques, telles que  :

Méthode	Vérifie que	Disponible en
assertAlmostEqual(a, b)	round(a-b, 7) == 0
assertNotAlmostEqual(a, b)	round(a-b, 7) != 0
assertGreater(a, b)	a > b	3.1
assertGreaterEqual(a, b)	a >= b	3.1
assertLess(a, b)	a < b	3.1
assertLessEqual(a, b)	a <= b	3.1
assertRegex(s, r)	r.search(s)	3.1
assertNotRegex(s, r)	not r.search(s)	3.2
assertCountEqual(a, b)	a et b ont les mêmes éléments dans le même nombre, quel que soit leur ordre.	3.2

assertAlmostEqual(first, second, places=7, msg=None, delta=None)

assertNotAlmostEqual(first, second, places=7, msg=None, delta=None)

Vérifie que first et second sont approximativement (ou pas approximativement) égaux en calculant la différence, en arrondissant au nombre donné de décimales places (par défaut 7), et en comparant à zéro. Notez que ces méthodes arrondissent les valeurs au nombre donné de décimales (par exemple comme la fonction round()) et non aux chiffres significatifs.

Si delta est fourni au lieu de places, la différence entre first et second doit être inférieure ou égale (ou supérieure) à delta.

Fournir à la fois delta et places lève une TypeError.

Modifié dans la version 3.2: assertAlmostEqual() considère automatiquement des objets presque égaux qui se comparent égaux. assertNotNotAlmostEqual() échoue automatiquement si les objets qui se comparent sont égaux. Ajout de l'argument mot-clé delta.

assertGreater(first, second, msg=None)

assertGreaterEqual(first, second, msg=None)

assertLess(first, second, msg=None)

assertLessEqual(first, second, msg=None)

Vérifie que first est respectivement >, >=, >=, < ou <= à second selon le nom de la méthode. Sinon, le test échouera :

>>> self.assertGreaterEqual(3, 4)
AssertionError: "3" unexpectedly not greater than or equal to "4"

Nouveau dans la version 3.1.

assertRegex(text, regex, msg=None)

assertNotRegex(text, regex, msg=None)

Vérifie qu'une recherche par motif regex correspond (ou ne correspond pas) à text. En cas d'échec, le message d'erreur inclura le motif et le texte (ou le motif et la partie du texte qui correspond de manière inattendue). regex peut être un objet d'expression régulière ou une chaîne contenant une expression régulière appropriée pour être utilisée par re.search().

Nouveau dans la version 3.1: Ajouté sous le nom assertRegexpMatches.

Modifié dans la version 3.2: La méthode assertRegexpMatches() a été renommé en assertRegex().

Nouveau dans la version 3.2: assertNotRegex().

Nouveau dans la version 3.5: Le nom assertNotRegexpMatches` est un alias obsolète pour assertNotRegex().

assertCountEqual(first, second, msg=None)

Vérifie que la séquence first contient les mêmes éléments que second, quel que soit leur ordre. Si ce n'est pas le cas, un message d'erreur indiquant les différences entre les séquences est généré.

Les éléments en double ne sont pas ignorés lors de la comparaison entre first et second. Il vérifie si chaque élément a le même nombre dans les deux séquences. Équivalent à : assertEqual(Counter(list(first))), Counter(list(second))) mais fonctionne aussi avec des séquences d'objets non hachables.

Nouveau dans la version 3.2.

La méthode assertEqual() envoie le contrôle d'égalité pour les objets du même type à différentes méthodes spécifiques au type. Ces méthodes sont déjà implémentées pour la plupart des types intégrés, mais il est également possible d'enregistrer de nouvelles méthodes en utilisant addTypeEqualityFunc()  :

addTypeEqualityFunc(typeobj, function)

Enregistre une méthode spécifique appelée par assertEqual() pour vérifier si deux objets exactement du même typeobj (et non leurs sous-classes) sont égaux. function doit prendre deux arguments positionnels et un troisième argument mot-clé msg=None tout comme assertEqual() le fait. Il doit lever self.failureException(msg) lorsqu'une inégalité entre les deux premiers paramètres est détectée en fournissant éventuellement des informations utiles et expliquant l'inégalité en détail dans le message d'erreur.

Nouveau dans la version 3.1.

La liste des méthodes spécifiques utilisées automatiquement par assertEqual() est résumée dans le tableau suivant. Notez qu'il n'est généralement pas nécessaire d'invoquer ces méthodes directement.

Méthode	Utilisé pour comparer	Disponible en
assertMultiLineEqual(a, b)	chaînes	3.1
assertSequenceEqual(a, b)	séquences	3.1
assertListEqual(a, b)	listes	3.1
assertTupleEqual(a, b)	n-uplets	3.1
assertSetEqual(a, b)	sets ou frozensets	3.1
assertDictEqual(a, b)	dictionnaires	3.1

assertMultiLineEqual(first, second, msg=None)

Vérifie que la chaîne sur plusieurs lignes first est égale à la chaîne second. Si les deux chaînes de caractères ne sont pas égales, un diff mettant en évidence les différences est inclus dans le message d'erreur. Cette méthode est utilisée par défaut pour comparer les chaînes avec assertEqual().

Nouveau dans la version 3.1.

assertSequenceEqual(first, second, msg=None, seq_type=None)

Vérifie que deux séquences sont égales. Si un seq_type est fourni, first et second doivent tous deux être des instances de seq_type ou un échec est levé. Si les séquences sont différentes, un message d'erreur indiquant la différence entre les deux est généré.

Cette méthode n'est pas appelée directement par assertEqual(), mais sert à implémenter assertListEqual() et assertTupleEqual().

Nouveau dans la version 3.1.

assertListEqual(first, second, msg=None)

assertTupleEqual(first, second, msg=None)

Vérifie que deux listes ou deux n-uplets sont égaux. Si ce n'est pas le cas, un message d'erreur qui ne montre que les différences entre les deux est généré. Une erreur est également signalée si l'un ou l'autre des paramètres n'est pas du bon type. Ces méthodes sont utilisées par défaut pour comparer des listes ou des n-uplets avec assertEqual().

Nouveau dans la version 3.1.

assertSetEqual(first, second, msg=None)

Vérifie que deux ensembles sont égaux. Si ce n'est pas le cas, un message d'erreur s'affiche et indique les différences entre les sets. Cette méthode est utilisée par défaut lors de la comparaison de sets ou de frozensets avec assertEqual().

Échoue si l'un des objets first ou second n'a pas de méthode set.difference().

Nouveau dans la version 3.1.

assertDictEqual(first, second, msg=None)

Vérifie que deux dictionnaires sont égaux. Si ce n'est pas le cas, un message d'erreur qui montre les différences dans les dictionnaires est généré. Cette méthode est utilisée par défaut pour comparer les dictionnaires dans les appels à assertEqual().

Nouveau dans la version 3.1.

Enfin, la classe TestCase fournit les méthodes et attributs suivants :

fail(msg=None)

Indique un échec du test sans condition, avec msg ou None pour le message d'erreur.

failureException

Cet attribut de classe donne l'exception levée par la méthode de test. Si un framework de tests doit utiliser une exception spécialisée, probablement pour enrichir l'exception d'informations additionnels., il doit hériter de cette classe d'exception pour bien fonctionner avec le framework. La valeur initiale de cet attribut est AssertionError.

longMessage

Cet attribut de classe détermine ce qui se passe lorsqu'un message d'échec personnalisé est passé en argument au paramètre msg à un appel assertXYYY qui échoue. True est la valeur par défaut. Dans ce cas, le message personnalisé est ajouté à la fin du message d'erreur standard. Lorsqu'il est réglé sur False, le message personnalisé remplace le message standard.

Le paramétrage de la classe peut être écrasé dans les méthodes de test individuelles en assignant un attribut d'instance, self.longMessage, à True ou False avant d'appeler les méthodes d'assertion.

Le réglage de la classe est réinitialisé avant chaque appel de test.

Nouveau dans la version 3.1.

maxDiff

Cet attribut contrôle la longueur maximale des diffs en sortie des méthodes qui génèrent des diffs en cas d'échec. La valeur par défaut est 80*8 caractères. Les méthodes d'assertions affectées par cet attribut sont assertSequenceEqual() (y compris toutes les méthodes de comparaison de séquences qui lui sont déléguées), assertDictEqual() et assertMultiLineEqual().

Régler maxDiff sur None` signifie qu'il n'y a pas de longueur maximale pour les diffs.

Nouveau dans la version 3.2.

Les frameworks de test peuvent utiliser les méthodes suivantes pour recueillir des informations sur le test :

countTestCases()

Renvoie le nombre de tests représentés par cet objet test. Pour les instances de TestCase, c'est toujours 1.

defaultTestResult()

Retourne une instance de la classe de résultat de test qui doit être utilisée pour cette classe de cas de test (si aucune autre instance de résultat n'est fournie à la méthode run()).

Pour les instances de TestCase, c'est toujours une instance de TestResult ; les sous-classes de TestCase peuvent la remplacer au besoin.

id()

Retourne une chaîne identifiant le cas de test spécifique. Il s'agit généralement du nom complet de la méthode de test, y compris le nom du module et de la classe.

shortDescription()

Renvoie une description du test, ou None si aucune description n'a été fournie. L'implémentation par défaut de cette méthode renvoie la première ligne de la docstring de la méthode de test, si disponible, ou None.

Modifié dans la version 3.1: En 3.1, ceci a été modifié pour ajouter le nom du test à la description courte, même en présence d'une docstring. Cela a causé des problèmes de compatibilité avec les extensions unittest et l'ajout du nom du test a été déplacé dans la classe TextTestResult dans Python 3.2.

addCleanup(function, *args, **kwargs)

Ajout d'une fonction à appeler après tearDown() pour nettoyer les ressources utilisées pendant le test. Les fonctions seront appelées dans l'ordre inverse de l'ordre dans lequel elles ont été ajoutées (LIFO). Elles sont appelées avec tous les arguments et arguments de mots-clés passés à addCleanup() quand elles sont ajoutées.

Si setUp() échoue, cela signifie que tearDown() n'est pas appelé, alors que les fonctions de nettoyage ajoutées seront toujours appelées.

Nouveau dans la version 3.1.

doCleanups()

Cette méthode est appelée sans conditions après tearDown(), ou après setUp() si setUp() lève une exception.

Cette méthode est chargée d'appeler toutes les fonctions de nettoyage ajoutées par addCleanup(). Si vous avez besoin de fonctions de nettoyage à appeler avant l'appel à tearDown() alors vous pouvez appeler doCleanups() vous-même.

doCleanups() extrait les méthodes de la pile des fonctions de nettoyage une à la fois, de sorte qu'elles peuvent être appelées à tout moment.

Nouveau dans la version 3.1.

classmethod addClassCleanup(function, /, *args, **kwargs)

Ajout d'une fonction à appeler après tearDownClass() pour nettoyer les ressources utilisées par la classe test. Les fonctions sont appelées dans l'ordre inverse de l'ordre dans lequel elles ont été ajoutées (LIFO). Elles sont appelées avec tous les arguments et arguments de mots-clés passés à addClassCleanup() quand elles sont ajoutées.

Si setUpClass() échoue, impliquant que tearDownClass() n'est pas appelé, alors les fonctions de nettoyage ajoutées sont quand même appelées.

Nouveau dans la version 3.8.

classmethod doClassCleanups()

Cette méthode est appelée sans conditions après tearDownClass(), ou après setUpClass() si setUpClass() lève une exception.

Cette méthode est chargée d'appeler toutes les fonctions de nettoyage ajoutées par addClassCleanup(). Si vous avez besoin de fonctions de nettoyage à appeler avant l'appel à tearDownClass() alors vous pouvez appeler doClassCleanups() vous-même.

doClassCleanups() extrait les méthodes de la pile des fonctions de nettoyage une à la fois, de sorte qu'elles peuvent être appelées à tout moment.

Nouveau dans la version 3.8.

class unittest.IsolatedAsyncioTestCase(methodName='runTest')

Cette classe fournit une API similaire à TestCase et accepte aussi les coroutines en tant que fonctions de test.

Nouveau dans la version 3.8.

coroutine asyncSetUp()

Méthode appelée pour réaliser la mise en place du test. Celle-ci est exécutée après setUp(). Elle est exécutée immédiatement avant l'appel de la méthode de test ; à l'exception de AssertionError ou SkipTest, toute exception levée par cette méthode est considérée comme une erreur et non pas comme un échec du test. L'implémentation par défaut ne fait rien.

coroutine asyncTearDown()

Méthode appelée immédiatement après l'appel de la méthode de test et l'enregistrement du résultat. Elle est appelée avant tearDown(). Elle est appelée même si la méthode de test a levé une exception. De fait, l'implémentation d'une sous-classe doit être faite avec précaution si vous vérifiez l'état interne de la classe. Toute exception, autre que AssertionError ou SkipTest, levée par cette méthode est considérée comme une erreur supplémentaire plutôt que comme un échec du test (augmentant ainsi le nombre total des erreurs signalées). Cette méthode est appelée uniquement si l'exécution de asyncSetUp() est réussie quel que soit le résultat de la méthode de test. L'implémentation par défaut ne fait rien.

addAsyncCleanup(function, /, *args, **kwargs)

Cette méthode accepte une coroutine qui peut être utilisée comme fonction de nettoyage.

run(result=None)

Configure une nouvelle boucle d'évènements pour exécuter le test, en collectant le résultat dans l'objet TestResult passé comme result. Si result est omis ou vaut None, un objet temporaire de résultat est créé (en appelant la méthode defaultTestResult()) et utilisé. L'objet résultat est renvoyé à l'appelant de run(). À la fin du test, toutes les taches de la boucle d’événements sont annulées.

Exemple illustrant l'ordre :

from unittest import IsolatedAsyncioTestCase

events = []


class Test(IsolatedAsyncioTestCase):


    def setUp(self):
        events.append("setUp")

    async def asyncSetUp(self):
        self._async_connection = await AsyncConnection()
        events.append("asyncSetUp")

    async def test_response(self):
        events.append("test_response")
        response = await self._async_connection.get("https://example.com")
        self.assertEqual(response.status_code, 200)
        self.addAsyncCleanup(self.on_cleanup)

    def tearDown(self):
        events.append("tearDown")

    async def asyncTearDown(self):
        await self._async_connection.close()
        events.append("asyncTearDown")

    async def on_cleanup(self):
        events.append("cleanup")

if __name__ == "__main__":
    unittest.main()

Après avoir lancé les tests, events contiendrait ["setUp", "asyncSetUp", "test_response", "asyncTearDown", "tearDown", "cleanup"].

class unittest.FunctionTestCase(testFunc, setUp=None, tearDown=None, description=None)

Cette classe implémente la partie de l'interface TestCase qui permet au lanceur de test de piloter le scénario de test, mais ne fournit pas les méthodes que le code test peut utiliser pour vérifier et signaler les erreurs. Ceci est utilisé pour créer des scénario de test utilisant du code de test existant afin de faciliter l'intégration dans un framework de test basé sur unittest.

Alias obsolètes

Pour des raisons historiques, certaines méthodes de la classe TestCase avaient un ou plusieurs alias qui sont maintenant obsolètes. Le tableau suivant énumère les noms corrects ainsi que leurs alias obsolètes  :

Nom de méthode	Alias obsolètes	Alias obsolètes
assertEqual()	failUnlessEqual	assertEquals
assertNotEqual()	failIfEqual	assertNotEquals
assertTrue()	failUnless	assert_
assertFalse()	failIf
assertRaises()	failUnlessRaises
assertAlmostEqual()	failUnlessAlmostEqual	assertAlmostEquals
assertNotAlmostEqual()	failIfAlmostEqual	assertNotAlmostEquals
assertRegex()		assertRegexpMatches
assertNotRegex()		assertNotRegexpMatches
assertRaisesRegex()		assertRaisesRegexp

Obsolète depuis la version 3.1: Les alias fail* sont énumérés dans la deuxième colonne.

Obsolète depuis la version 3.2: Les alias assert* sont énumérés dans la troisième colonne.

Obsolète depuis la version 3.2: Les expressions assertRegexpMatches et assertRaisesRegexp ont été renommées en assertRegex() et assertRaisesRegex().

Obsolète depuis la version 3.5: Le nom assertNotRegexpMatches est obsolète en faveur de assertNotRegex().

Regroupement des tests

class unittest.TestSuite(tests=())

Cette classe représente une agrégation de cas de test individuels et de suites de tests. La classe présente l'interface requise par le lanceur de test pour être exécutée comme tout autre cas de test. L'exécution d'une instance de TestSuite est identique à l'itération sur la suite, en exécutant chaque test indépendamment.

Si tests est fourni, il doit s'agir d'un itérable de cas de test individuels ou d'autres suites de test qui seront utilisés pour construire la suite initial. Des méthodes supplémentaires sont fournies pour ajouter ultérieurement des cas de test et des suites à la collection.

Les objets TestSuite se comportent comme les objets TestCase, sauf qu'ils n'implémentent pas réellement un test. Au lieu de cela, ils sont utilisés pour regrouper les tests en groupes de tests qui doivent être exécutés ensemble. Des méthodes supplémentaires sont disponibles pour ajouter des tests aux instances de TestSuite :

addTest(test)

Ajouter un objet TestCase ou TestSuite à la suite de tests.

addTests(tests)

Ajouter tous les tests d'un itérable d'instances de TestCase et de TestSuite à cette suite de tests.

C'est l'équivalent d'une itération sur tests, appelant addTest() pour chaque élément.

TestSuite partage les méthodes suivantes avec TestCase :

run(result)

Exécute les tests associés à cette suite, en collectant le résultat dans l'objet de résultat de test passé par result. Remarquer que contrairement à TestCase.run(), TestSuite.run() nécessite que l'objet résultat soit passé.

debug()

Exécute les tests associés à cette suite sans collecter le résultat. Ceci permet aux exceptions levées par le test d'être propagées à l'appelant et peut être utilisé pour exécuter des tests sous un débogueur.

countTestCases()

Renvoie le nombre de tests représentés par cet objet de test, y compris tous les tests individuels et les sous-suites.

__iter__()

Les tests groupés par une classe TestSuite sont toujours accessibles par itération. Les sous-classes peuvent fournir paresseusement des tests en surchargeant __iter__(). Notez que cette méthode peut être appelée plusieurs fois sur une même suite (par exemple lors du comptage des tests ou de la comparaison pour l'égalité) et que les tests retournés par itérations répétées avant TestSuite.run() doivent être les mêmes pour chaque itération. Après TestSuite.run(), les appelants ne devraient pas se fier aux tests retournés par cette méthode à moins qu'ils n'utilisent une sous-classe qui remplace TestSuite._removeTestAtIndex() pour préserver les références des tests.

Modifié dans la version 3.2: Dans les versions précédentes, la classe TestSuite accédait aux tests directement plutôt que par itération, donc surcharger la méthode __iter__() n'était pas suffisante pour fournir les tests.

Modifié dans la version 3.4: Dans les versions précédentes, la classe TestSuite contenait des références à chaque TestCase après l'appel à TestSuite.run(). Les sous-classes peuvent restaurer ce comportement en surchargeant TestSuite._removeTestAtIndex().

Dans l'utilisation typique de l'objet TestSuite, la méthode run() est invoquée par une classe TestRunner plutôt que par le système de test de l'utilisateur.

Chargement et exécution des tests

class unittest.TestLoader

La classe TestLoader est utilisée pour créer des suites de tests à partir de classes et de modules. Normalement, il n'est pas nécessaire de créer une instance de cette classe ; le module unittest fournit une instance qui peut être partagée comme unittest.defaultTestLoader. L'utilisation d'une sous-classe ou d'une instance permet cependant de personnaliser certaines propriétés configurables.

Les objets de la classe TestLoader ont les attributs suivants :

errors

Une liste des erreurs non fatales rencontrées lors du chargement des tests. Il est impossible de faire une remise à zéro pendant le chargement. Les erreurs fatales sont signalées par la méthode correspondante qui lève une exception à l'appelant. Les erreurs non fatales sont également indiquées par un test synthétique qui lève l'erreur initiale lors de l'exécution.

Nouveau dans la version 3.5.

Les objets de la classe TestLoader ont les attributs suivants :

loadTestsFromTestCase(testCaseClass)

Renvoie une suite de tous les cas de test contenus dans la classe TestCaseClassdérivée de testCase.

Une instance de cas de test est créée pour chaque méthode nommée par getTestCaseNames(). Par défaut, ce sont les noms des méthodes commençant par "test". Si getTestTestCaseNames() ne renvoie aucune méthode, mais que la méthode runTest() est implémentée, un seul cas de test est créé pour cette méthode à la place.

loadTestsFromModule(module, pattern=None)

Renvoie une suite de tous les cas de test contenus dans le module donné. Cette méthode recherche module pour les classes dérivées de TestCase et crée une instance de la classe pour chaque méthode de test définie pour cette classe.

Note

Bien que l'utilisation d'une hiérarchie de classes TestCase (les classes dérivées de TestCase) peut être un moyen pratique de partager des fixtures et des fonctions utilitaires, définir une méthode de test pour des classes de base non destinées à être directement instanciée ne marche pas bien avec cette méthode. Cela peut toutefois s'avérer utile lorsque les fixtures sont différentes et définies dans des sous-classes.

Si un module fournit une fonction load_tests, il est appelé pour charger les tests. Cela permet aux modules de personnaliser le chargement des tests. C'est le protocole load_tests protocol. L'argument pattern est passé comme troisième argument à load_tests.

Modifié dans la version 3.2: Ajout de la prise en charge de load_tests.

Modifié dans la version 3.5: L'argument par défaut non documenté et non officiel use_load_tests est déprécié et ignoré, bien qu'il soit toujours accepté pour la compatibilité descendante. La méthode accepte aussi maintenant un argument pattern qui est passé à load_tests comme troisième argument.

loadTestsFromName(name, module=None)

Renvoie une suite de tous les cas de test en fonction d'un spécificateur de chaîne de caractères.

Le spécificateur name est un "nom pointillé" qui peut être résolu soit par un module, une classe de cas de test, une méthode de test dans une classe de cas de test, une instance de TestSuite, ou un objet appelable qui retourne une instance de classe TestCase ou de classe TestSuite. Ces contrôles sont appliqués dans l'ordre indiqué ici, c'est-à-dire qu'une méthode sur une classe de cas de test possible sera choisie comme "méthode de test dans une classe de cas de test", plutôt que comme "un objet appelable".

Par exemple, si vous avez un module SampleTests contenant une classe TestCase (classe dérivée de la classe SampleTestCase) avec trois méthodes de test (test_one(), test_two() et test_three()), l'élément spécificateur SampleTests.sampleTestCase renvoie une suite qui va exécuter les trois méthodes de tests. L'utilisation du spécificateur SampleTests.SampleTestCase.test_two permettrait de retourner une suite de tests qui ne lancerait que la méthode test test_two(). Le spécificateur peut se référer à des modules et packages qui n'ont pas été importés. Ils seront importés par un effet de bord.

La méthode résout facultativement name relatif au module donné.

Modifié dans la version 3.5: Si une ImportError ou AttributeError se produit pendant la traversée de name, un test synthétique qui enrichie l'erreur produite lors de l'exécution est renvoyé. Ces erreurs sont incluses dans les erreurs accumulées par self.errors.

loadTestsFromNames(names, module=None)

Similaire à loadTestsFromName(), mais prend une séquence de noms plutôt qu'un seul nom. La valeur renvoyée est une suite de tests qui gère tous les tests définis pour chaque nom.

getTestCaseNames(testCaseClass)

Renvoie une séquence triée de noms de méthodes trouvés dans testCaseClass ; ceci doit être une sous-classe de TestCase.

discover(start_dir, pattern='test*.py', top_level_dir=None)

Trouve tous les modules de test en parcourant les sous-répertoires du répertoire de démarrage spécifié, et renvoie un objet TestSuite qui les contient. Seuls les fichiers de test qui correspondent à pattern sont chargés. Seuls les noms de modules qui sont importables (c'est-à-dire qui sont des identifiants Python valides) sont chargés.

Tous les modules de test doivent être importables depuis la racine du projet. Si le répertoire de démarrage n'est pas la racine, le répertoire racine doit être spécifié séparément.

Si l'importation d'un module échoue, par exemple en raison d'une erreur de syntaxe, celle-ci est alors enregistrée comme une erreur unique et la découverte se poursuit. Si l'échec de l'importation est dû au fait que SkipTest est levé, il est enregistré comme un saut plutôt que comme un message d'erreur.

Si un paquet (un répertoire contenant un fichier nommé __init__.py) est trouvé, le paquet est alors vérifié pour une fonction load_tests. Si elle existe, elle s'appellera package.load_tests(loader, tests, pattern). Le mécanisme de découverte de test prend soin de s'assurer qu'un paquet n'est vérifié qu'une seule fois au cours d'une invocation, même si la fonction load_tests appelle elle-même loader.discover.

Si load_tests existe alors la découverte ne poursuit pas la récursion dans le paquet, load_tests a la responsabilité de charger tous les tests dans le paquet.

Le motif n'est délibérément pas stocké en tant qu'attribut du chargeur afin que les paquets puissent continuer à être découverts eux-mêmes. top_level_dir est stocké de sorte que load_tests n'a pas besoin de passer cet argument a loader. discover().

start_dir peut être un nom de module ainsi qu'un répertoire.

Nouveau dans la version 3.2.

Modifié dans la version 3.4: Les modules levant une exception SkipTest au moment de leur importation ne sont pas considérés comme des erreurs, et sont marqués à sauter.

Modifié dans la version 3.4: start_dir peut être un paquet-espace de nommage.

Modifié dans la version 3.4: Les chemins sont classés avant d'être importés afin que l'ordre d'exécution soit toujours le même, même si le système de fichiers sous-jacent ne classe pas les fichiers par leur nom.

Modifié dans la version 3.5: Les paquets trouvés sont maintenant vérifiés pour load_tests indépendamment du fait que leur chemin d'accès corresponde ou non à pattern, car il est impossible pour un nom de paquet de correspondre au motif par défaut.

Les attributs suivants d'une classe TestLoader peuvent être configurés soit par héritage, soit par affectation sur une instance  :

testMethodPrefix

Chaîne donnant le préfixe des noms de méthodes qui seront interprétés comme méthodes de test. La valeur par défaut est 'test'.

Ceci affecte les méthodes getTestCaseNames() et toutes les méthodes loadTestsFrom*().

sortTestMethodsUsing

Fonction à utiliser pour comparer les noms de méthodes lors de leur tri dans les méthodes getTestCaseNames() et toutes les méthodes loadTestsFrom*().

suiteClass

Objet appelable qui construit une suite de tests à partir d'une liste de tests. Aucune méthode sur l'objet résultant n'est nécessaire. La valeur par défaut est la classe TestSuite.

Cela affecte toutes les méthodes loadTestsFrom*().

testNamePatterns

Liste des motifs de noms de test de type joker de style Unix que les méthodes de test doivent valider pour être incluses dans les suites de test (voir l'option -v).

Si cet attribut n'est pas None (par défaut), toutes les méthodes de test à inclure dans les suites de test doivent correspondre à l'un des modèles de cette liste. Remarquez que les correspondances sont toujours effectuées en utilisant fnmatch.fnmatchcase(), donc contrairement aux modèles passés à l'option -v, les motifs de sous-chaînes simples doivent être convertis avec le joker *.

Cela affecte toutes les méthodes loadTestsFrom*().

Nouveau dans la version 3.7.

class unittest.TestResult

Cette classe est utilisée pour compiler des informations sur les tests qui ont réussi et ceux qui ont échoué.

Un objet TestResult stocke les résultats d'un ensemble de tests. Les classes TestCase et TestSuite s'assurent que les résultats sont correctement enregistrés. Les auteurs du test n'ont pas à se soucier de l'enregistrement des résultats des tests.

Les cadriciels de test construits sur unittest peuvent nécessiter l'accès à l'objet TestResult généré en exécutant un ensemble de tests à des fins de génération de comptes-rendu. Une instance de TestResult est alors renvoyée par la méthode TestRunner.run() à cette fin.

Les instance de TestResult ont les attributs suivants qui sont intéressant pour l'inspection des résultats de l'exécution d'un ensemble de tests  :

errors

Une liste contenant des paires d'instances de TestCase et de chaînes de caractères contenant des traces de pile d'appels formatées. Chaque paire représente un test qui a levé une exception inattendue.

failures

Une liste contenant des paires d'instances de TestCase et de chaînes de caractères contenant des traces de pile d'appels formatées. Chaque paire représente un test où un échec a été explicitement signalé en utilisant les méthodes TestCase.assert*().

skipped

Une liste contenant des paires d'instances de TestCase et de chaînes de caractères contenant la raison de l'omission du test.

Nouveau dans la version 3.1.

expectedFailures

Une liste contenant des paires d'instances TestCase et de chaînes de caractères contenant des traces de pile d'appels formatées. Chaque paire représente un échec attendu ou une erreur du scénario de test.

unexpectedSuccesses

Une liste contenant les instances TestCase qui ont été marquées comme des échecs attendus, mais qui ont réussi.

shouldStop

A positionner sur True quand l'exécution des tests doit être arrêter par stop().

testsRun

Le nombre total de tests effectués jusqu'à présent.

buffer

S'il est défini sur true, sys.stdout et sys.stderr sont mis dans un tampon entre les appels de startTest() et stopTest(). La sortie collectée est répercutée sur les sorties sys.stdout et sys.stderr réels uniquement en cas d'échec ou d'erreur du test. Toute sortie est également attachée au message d'erreur.

Nouveau dans la version 3.2.

failfast

Si la valeur est true stop() est appelée lors de la première défaillance ou erreur, ce qui interrompt le test en cours d'exécution.

Nouveau dans la version 3.2.

tb_locals

Si la valeur est true, les variables locales sont affichées dans les traces d'appels.

Nouveau dans la version 3.5.

wasSuccessful()

Renvoie True si tous les tests effectués jusqu'à présent ont réussi, sinon renvoie False.

Modifié dans la version 3.4: Renvoie False s'il y a eu des unexpectedSuccesses dans les tests annotés avec le décorateur expectedFailure().

stop()

Cette méthode peut être appelée pour signaler que l'ensemble des tests en cours d'exécution doit être annulé en définissant l'attribut shouldStop sur True. Les instances de TestRunner doivent respecter ce signal et se terminer sans exécuter de tests supplémentaires.

Par exemple, cette fonctionnalité est utilisée par la classe TextTestRunner pour arrêter le cadriciel de test lorsque l'utilisateur lance une interruption clavier. Les outils interactifs qui fournissent des implémentations de TestRunner peuvent l'utiliser de la même manière.

Les méthodes suivantes de la classe TestResult sont utilisées pour maintenir les structures de données internes, et peuvent être étendues dans des sous-classes pour gérer des exigences supplémentaires en termes de compte-rendu. Cette fonction est particulièrement utile pour créer des outils qui prennent en charge la génération de rapports interactifs pendant l'exécution des tests.

startTest(test)

Appelé lorsque le scénario de test test est sur le point d'être exécuté.

stopTest(test)

Appelé après l'exécution du cas de test test, quel qu'en soit le résultat.

startTestRun()

Appelé une fois avant l'exécution des tests.

Nouveau dans la version 3.1.

stopTestRun()

Appelé une fois après l'exécution des tests.

Nouveau dans la version 3.1.

addError(test, err)

Appelé lorsque le cas de test test soulève une exception inattendue. err est un n-uplet de la même forme que celle renvoyée par sys.exc_info() : (type, valeur, traceback).

L'implémentation par défaut ajoute un n-uplet (test, formatted_err) à l'attribut errors de l'instance, où formatted_err est une trace formatée à partir de err.

addFailure(test, err)

Appelé lorsque le cas de test test soulève une exception inattendue. err est un triplet de la même forme que celui renvoyé par sys.exc_info() : (type, valeur, traceback).

L'implémentation par défaut ajoute un n-uplet (test, formatted_err) à l'attribut errors de l'instance, où formatted_err est une trace formatée à partir de err.

addSuccess(test)

Appelé lorsque le scénario de test test réussit.

L'implémentation par défaut ne fait rien.

addSkip(test, reason)

Appelé lorsque le scénario de test test est ignoré. raison est la raison pour laquelle le test donné à été ignoré.

L'implémentation par défaut ajoute un n-uplet (test, raison) à l'attribut skipped de l'instance.

addExpectedFailure(test, err)

Appelé lorsque le scénario de test test échoue (assertion ou exception), mais qui a été marqué avec le décorateur expectedFailure().

L'implémentation par défaut ajoute un n-uplet (test, formatted_err) à l'attribut errors de l'instance, où formatted_err est une trace formatée à partir de err.

addUnexpectedSuccess(test)

Appelé lorsque le scénario de test test réussit, mais que ce scénario a été marqué avec le décorateur expectedFailure().

L'implémentation par défaut ajoute le test à l'attribut unexpectedSuccesses de l'instance.

addSubTest(test, subtest, outcome)

Appelé à la fin d'un sous-test. test est le cas de test correspondant à la méthode de test. subtest est une instance dérivée de TestCase décrivant le sous-test.

Si outcome est None, le sous-test a réussi. Sinon, il a échoué avec une exception où outcome est un triplet du formulaire renvoyé par sys.exc_info() : (type, valeur, traceback).

L'implémentation par défaut ne fait rien lorsque le résultat est un succès, et enregistre les échecs de sous-test comme des échecs normaux.

Nouveau dans la version 3.4.

class unittest.TextTestResult(stream, descriptions, verbosity)

Une implémentation concrète de TestResult utilisé par la classe TextTestRunner.

Nouveau dans la version 3.2: Cette classe s'appelait auparavant _TextTestResult. L'ancien nom existe toujours en tant qu'alias, mais il est obsolète.

unittest.defaultTestLoader

Instance de la classe TestLoader destinée à être partagée. Si aucune personnalisation de la classe TestLoader n'est nécessaire, cette instance peut être utilisée au lieu de créer plusieurs fois de nouvelles instances.

class unittest.TextTestRunner(stream=None, descriptions=True, verbosity=1, failfast=False, buffer=False, resultclass=None, warnings=None, *, tb_locals=False)

Une implémentation de base d'un lanceur de test qui fournit les résultats dans un flux. Si stream est None, par défaut, sys.stderr est utilisé comme flux de sortie. Cette classe a quelques paramètres configurables, mais est essentiellement très simple. Les applications graphiques qui exécutent des suites de tests doivent fournir des implémentations alternatives. De telles implémentations doivent accepter **kwargs car l'interface pour construire les lanceurs change lorsque des fonctionnalités sont ajoutées à unittest.

Par défaut, ce lanceur affiche DeprecationWarning, PendingDeprecationWarning, ResourceWarning et ImportWarning même si elles sont ignorées par défaut. Les avertissements causés par des méthodes *unittest* dépréciées sont également spéciaux et, lorsque les filtres d'avertissement sont default ou always, ils n'apparaissent qu'une fois par module, afin d'éviter trop de messages d'alerte. Ce comportement peut être annulé en utilisant les options -Wd ou -Wa de Python (voir Gestion des avertissements) et en laissant warnings à None.

Modifié dans la version 3.2: Ajout du paramètre warnings.

Modifié dans la version 3.2: Le flux par défaut est défini sur sys.stderr au moment de l'instanciation plutôt qu'à l'importation.

Modifié dans la version 3.5: Ajout du paramètre tb_locals.

_makeResult()

Cette méthode renvoie l'instance de TestResult utilisée par run(). Il n'est pas destiné à être appelé directement, mais peut être surchargée dans des sous-classes pour fournir un TestResult personnalisé.

_makeResult() instancie la classe ou l'appelable passé dans le constructeur TextTestRunner comme argument resultclass. Il vaut par défaut TextTestResult si aucune resultclass n'est fournie. La classe de résultat est instanciée avec les arguments suivants :

stream, descriptions, verbosity

run(test)

Cette méthode est l'interface publique principale du TextTestRunner. Cette méthode prend une instance TestSuite ou TestCase. Un TestResult est créé en appelant _makeResult() et le ou les tests sont exécutés et les résultats affichés sur la sortie standard.

unittest.main(module='__main__', defaultTest=None, argv=None, testRunner=None, testLoader=unittest.defaultTestLoader, exit=True, verbosity=1, failfast=None, catchbreak=None, buffer=None, warnings=None)

Un programme en ligne de commande qui charge un ensemble de tests à partir du module et les exécute. L'utilisation principale est de rendre les modules de test facilement exécutables. L'utilisation la plus simple pour cette fonction est d'inclure la ligne suivante à la fin d'un script de test :

if __name__ == '__main__':
    unittest.main()

Vous pouvez exécuter des tests avec des informations plus détaillées en utilisant l'option de verbosité :

if __name__ == '__main__':
    unittest.main(verbosity=2)

L'argument defaultTest est soit le nom d'un seul test, soit un itérable de noms de test à exécuter si aucun nom de test n'est spécifié via argv. Si aucun nom de test n'est fourni via argv, tous les tests trouvés dans module sont exécutés.

L'argument argv peut être une liste d'options passées au programme, le premier élément étant le nom du programme. S'il n'est pas spécifié ou vaut None, les valeurs de sys.argv sont utilisées.

L'argument testRunner peut être soit une classe de lanceur de test, soit une instance déjà créée de celle-ci. Par défaut, main appelle sys.exit() avec un code de sortie indiquant le succès ou l'échec des tests exécutés.

L'argument testLoader doit être une instance de TestLoader, et par défaut de defaultTestLoader.

Les main sont utilisés à partir de l'interpréteur interactif en passant dans l'argument exit=False. Ceci affiche le résultat sur la sortie standard sans appeler sys.exit() :

>>> from unittest import main
>>> main(module='test_module', exit=False)

Les paramètres failfast, catchbreak et buffer ont le même effet que la même option en ligne de commande command-line options.

L'argument warnings spécifie l'argument filtre d'avertissement qui doit être utilisé lors de l'exécution des tests. Si elle n'est pas spécifiée, elle reste réglée sur None si une option -W' est passée à python (voir Utilisation des avertissements), sinon elle sera réglée sur 'default'.

L'appel de main renvoie en fait une instance de la classe TestProgram. Le résultat des tests effectués est enregistré sous l'attribut result.

Modifié dans la version 3.1: Ajout du paramètre exit.

Modifié dans la version 3.2: Ajout des paramètres verbosity, failfast, catchbreak, buffer et warnings.

Modifié dans la version 3.4: Le paramètre defaultTest a été modifié pour accepter également un itérable de noms de test.

Protocole de chargement des tests (load_tests Protocol)

Nouveau dans la version 3.2.

Les modules ou paquets peuvent personnaliser la façon dont les tests sont chargés à partir de ceux-ci pendant l'exécution des tests ou pendant la découverte de tests en implémentant une fonction appelée load_tests.

Si un module de test définit load_tests il est appelé par TestLoader.loadTestsFromModule() avec les arguments suivants :

load_tests(loader, standard_tests, pattern)

où pattern est passé directement depuis loadTestsFromModule. La valeur par défaut est None.

Elle doit renvoyer une classe TestSuite.

loader est l'instance de TestLoader qui effectue le chargement. standard_tests sont les tests qui sont chargés par défaut depuis le module. Il est courant que les modules de test veuillent seulement ajouter ou supprimer des tests de l'ensemble standard de tests. Le troisième argument est utilisé lors du chargement de paquets dans le cadre de la découverte de tests.

Une fonction typique de load_tests qui charge les tests d'un ensemble spécifique de classes TestCase peut ressembler à :

test_cases = (TestCase1, TestCase2, TestCase3)

def load_tests(loader, tests, pattern):
    suite = TestSuite()
    for test_class in test_cases:
        tests = loader.loadTestsFromTestCase(test_class)
        suite.addTests(tests)
    return suite

Si la découverte est lancée dans un répertoire contenant un paquet, soit à partir de la ligne de commande, soit en appelant TestLoader.discover(), alors le système recherche dans le fichier du paquet __init__.py la fonction load_tests. Si cette fonction n'existe pas, la découverte se poursuit dans le paquet comme si c'était juste un autre répertoire. Sinon, la découverte des tests du paquet est effectuée par load_tests qui est appelé avec les arguments suivants :

load_tests(loader, standard_tests, pattern)

Doit renvoyer une classe TestSuite représentant tous les tests du paquet. (standard_tests ne contient que les tests collectés dans le fichier __init__.py).

Comme le motif est passé à load_tests, le paquet est libre de continuer (et potentiellement de modifier) la découverte des tests. Une fonction « ne rien faire » load_tests pour un paquet de test ressemblerait à :

def load_tests(loader, standard_tests, pattern):
    # top level directory cached on loader instance
    this_dir = os.path.dirname(__file__)
    package_tests = loader.discover(start_dir=this_dir, pattern=pattern)
    standard_tests.addTests(package_tests)
    return standard_tests

Modifié dans la version 3.5: La découverte de test ne vérifie plus que les noms de paquets correspondent à pattern en raison de l'impossibilité de trouver des noms de paquets correspondant au motif par défaut.

Classes et modules d'aménagements des tests

Les classes et modules d'aménagements des tests sont implémentés dans TestSuite. Lorsque la suite de tests rencontre un test d'une nouvelle classe, alors tearDownClass() de la classe précédente (s'il y en a une) est appelé, suivi de setUpClass() de la nouvelle classe.

De même, si un test provient d'un module différent du test précédent, alors tearDownModule du module précédent est exécuté, suivi par setUpModule du nouveau module.

Après que tous les tests ont été exécutés, les tearDownClass et tearDownModule finaux sont exécutés.

Notez que les aménagements de tests partagés ne fonctionnent pas bien avec de « potentielles » fonctions comme la parallélisation de test et qu'ils brisent l'isolation des tests. Ils doivent être utilisés avec parcimonie.

L'ordre par défaut des tests créés par les chargeurs de tests unitaires est de regrouper tous les tests des mêmes modules et classes. Cela à pour conséquence que setUpClass / setUpModule (etc) sont appelé exactement une fois par classe et module. Si vous rendez l'ordre aléatoire, de sorte que les tests de différents modules et classes soient adjacents les uns aux autres, alors ces fonctions d'aménagements partagées peuvent être appelées plusieurs fois dans un même test.

Les aménagements de tests partagés ne sont pas conçus pour fonctionner avec des suites dont la commande n'est pas standard. Une BaseTestSuite existe toujours pour les cadriciels qui ne veulent pas gérer les aménagements de tests partagés.

S'il y a des exceptions levées pendant l'une des fonctions d'aménagement de tests partagés, le test est signalé comme étant en erreur. Parce qu'il n'y a pas d'instance de test correspondante, un objet _ErrorHolder (qui a la même interface qu'une classe TestCase) est créé pour représenter l'erreur. Si vous n'utilisez que le lanceur de test unitaire standard, ce détail n'a pas d'importance, mais si vous êtes un auteur de cadriciel de test, il peut être pertinent.

Classes de mise en place (setUpClass) et de démantèlement des tests (tearDownClass)

Elles doivent être implémentées en tant que méthodes de classe :

import unittest

class Test(unittest.TestCase):
    @classmethod
    def setUpClass(cls):
        cls._connection = createExpensiveConnectionObject()

    @classmethod
    def tearDownClass(cls):
        cls._connection.destroy()

Si vous voulez que les classes de base setUpClass et tearDownClass soient appelées, vous devez les appeler vous-même. Les implémentations dans TestCase sont vides.

Si une exception est levée pendant l'exécution de setUpClass alors les tests dans la classe ne sont pas exécutés et la classe tearDownClass n'est pas exécutée. Les classes ignorées n'auront pas d'exécution de setUpClass ou tearDownClass. Si l'exception est une exception SkipTest alors la classe est signalée comme ayant été ignorée au lieu d'être en échec.

Module de mise en place (setUpModule) et de démantèlement des tests (tearDownModule)

Elles doivent être implémentées en tant que fonctions :

def setUpModule():
    createConnection()

def tearDownModule():
    closeConnection()

Si une exception est levée pendant l'exécution de la fonction setUpModule alors aucun des tests du module ne sera exécuté et la fonction tearDownModule ne sera pas exécutée. Si l'exception est une exception SkipTest alors le module est signalé comme ayant été ignoré au lieu d'être en échec.

Pour ajouter du code de nettoyage qui doit être exécuté même en cas d'exception, utilisez addModuleCleanup :

unittest.addModuleCleanup(function, /, *args, **kwargs)

Ajout d'une fonction à appeler après tearDownModule() pour nettoyer les ressources utilisées pendant le test. Les fonctions seront appelées dans l'ordre inverse de l'ordre dans lequel elles ont été ajoutées (LIFO). Elles sont appelées avec tous les arguments et arguments par mots-clés passés à addModuleCleanup() quand elles sont ajoutées.

Si setUpModule() échoue, impliquant que tearDownModule() n'est pas appelée, alors les fonctions de nettoyage ajoutées sont quand même toujours appelées.

Nouveau dans la version 3.8.

unittest.doModuleCleanups()

Cette méthode est appelée sans conditions après tearDownModule(), ou après setUpModule() si setUpModule() lève une exception.

Cette méthode est chargée d'appeler toutes les fonctions de nettoyage ajoutées par addCleanupModule(). Si vous avez besoin de fonctions de nettoyage à appeler avant l'appel à tearDownModule() alors vous pouvez appeler doCleanupsModule() vous-même.

doModuleCleanups() extrait les méthodes de la pile des fonctions de nettoyage une à la fois, de sorte qu'elles peuvent être appelées à tout moment.

Nouveau dans la version 3.8.

Traitement des signaux

Nouveau dans la version 3.2.

L'option -c/--catch en ligne de commande pour unittest, ainsi que le paramètre catchbreak vers unittest.main(), permettent une utilisation simplifiée du contrôle-C pendant un test. Avec l'activation de catchbreak, l'utilisation du contrôle-C permet de terminer le test en cours d'exécution, et le test se termine et rapporte tous les résultats obtenus jusqu'à présent. Un deuxième contrôle-C lève une exception classique KeyboardInterrupt.

Le gestionnaire du signal contrôle-C tente de rester compatible avec le code ou les tests qui installent leur propre gestionnaire signal.SIGINT. Si le gestionnaire unittest est appelé mais n'est pas le gestionnaire installé signal.SIGINT, c'est-à-dire qu'il a été remplacé par le système sous test et délégué, alors il appelle le gestionnaire par défaut. C'est normalement le comportement attendu par un code qui remplace un gestionnaire installé et lui délègue. Pour les tests individuels qui ont besoin que le signal contrôle-C "unittest" soit désactivée, le décorateur removeHandler() peut être utilisé.

Il existe quelques fonctions de support pour les auteurs de cadriciel afin d'activer la fonctionnalité de gestion des contrôle-C dans les cadriciels de test.

unittest.installHandler()

Installe le gestionnaire contrôle-c. Quand un signal.SIGINT est reçu (généralement en réponse à l'utilisateur appuyant sur contrôle-c) tous les résultats enregistrés vont appeler la méthode stop().

unittest.registerResult(result)

Enregistre un objet TestResult pour la gestion du contrôle-C. L'enregistrement d'un résultat stocke une référence faible sur celui-ci, de sorte qu'il n'empêche pas que le résultat soit collecté par le ramasse-miette.

L'enregistrement d'un objet TestResult n'a pas d'effets de bord si la gestion du contrôle-c n'est pas activée, donc les cadriciels de test peuvent enregistrer sans condition tous les résultats qu'ils créent indépendamment du fait que la gestion soit activée ou non.

unittest.removeResult(result)

Supprime un résultat enregistré. Une fois qu'un résultat a été supprimé, stop() n'est plus appelé sur cet objet résultat en réponse à un contrôle-c.

unittest.removeHandler(function=None)

Lorsqu'elle est appelée sans arguments, cette fonction supprime le gestionnaire contrôle-c s'il a été installé. Cette fonction peut également être utilisée comme décorateur de test pour supprimer temporairement le gestionnaire pendant l'exécution du test :

@unittest.removeHandler
def test_signal_handling(self):
    ...