"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 (*fixture*)* 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
     Third-party unittest framework with a lighter-weight syntax for
     writing tests.  For example, "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.

  Le script "Tools/unittestgui/unittestgui.py" dans la distribution
  source de Python est un outil avec une interface graphique pour
  découvrir et exécuter des tests. Il est principalement conçu pour
  être facile d'emploi pour les débutants en matière de tests
  unitaires. Pour les environnements de production il est recommandé
  que les tests soient pilotés par un système d'intégration continue
  comme Buildbot, Jenkins ou  Hudson.


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: La découverte de tests prend en charge
*les paquets-espaces de nommage*.


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

   Marque le test comme étant un erreur attendue.  Si le test échoue
   il est considéré comme un succès. S'il passe, il est considéré
   comme étant en échec.

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* évaluent (ou n'évaluent 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)

      Test that *member* is (or is not) in *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         | 3.1          |
   |                                                           | l'exception *exc* et que le message    |              |
   |                                                           | correspond au motif de l'expression    |              |
   |                                                           | régulière *r*                          |              |
   +-----------------------------------------------------------+----------------------------------------+--------------+
   | "assertWarns(warn, fun, *args, **kwds)"                   | "fun(*args, **kwds)" lève bien         | 3.2          |
   |                                                           | l'avertissement *warn*                 |              |
   +-----------------------------------------------------------+----------------------------------------+--------------+
   | "assertWarnsRegex(warn, r, fun, *args, **kwds)"           | "fun(*args, **kwds)" lève bien         | 3.2          |
   |                                                           | l'avertissement *warn* et que le       |              |
   |                                                           | message correspond au motif de         |              |
   |                                                           | l'expression régulière *r*             |              |
   +-----------------------------------------------------------+----------------------------------------+--------------+
   | "assertLogs(logger, level)"                               | Le bloc "with" écrit dans le *logger*  | 3.4          |
   |                                                           | avec un niveau minimum égal à *level*  |              |
   +-----------------------------------------------------------+----------------------------------------+--------------+

   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 couple
      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 capturé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 couple 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.

      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         | 3.2            |
   |                                         | éléments dans le même nombre,    |                |
   |                                         | quel que soit leur ordre.        |                |
   +-----------------------------------------+----------------------------------+----------------+

   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 couples 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 (dernier entré, premier sorti)).  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.

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 "TestCaseClass"dé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 qui lèvent "SkipTest"
      lors de l'importation sont enregistrés comme des sauts et non
      des erreurs. Le mécanisme de découverte fonctionne pour les
      *paquets-espaces de nommage*. Les chemins sont triés avant
      d'être importés pour que l'ordre d'exécution soit le même, même
      si l'ordre du système de fichiers sous-jacent ne dépend pas du
      nom du fichier.

      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 un couple d'instances de "TestCase" et une
      chaînes de caractères contenant des traces formatées. Chaque
      couple représente un test qui a levé une exception inattendue.

   failures

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

   skipped

      Une liste contenant un couple d'instances de "TestCase" et une
      chaînes de caractères contenant la raison de l'omission du test.

      Nouveau dans la version 3.1.

   expectedFailures

      Une liste contenant un couple d'instance "TestCase" et une
      chaînes de caractères contenant des traces formatées. Chaque
      coulpe représente un échec attendu 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 couple du formulaire renvoyé par
      "sys.exc_info()" : "(type, valeur, traceback)".

      L'implémentation par défaut ajoute un couple "(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 couple "(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 couple "(test, raison)" à
      l'attribut "skipped" de l'instance.

   addExpectedFailure(test, err)

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

      L'implémentation par défaut ajoute un couple "(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.


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):
          ...
