25.3. unittest
— Framework de tests unitaires¶
Nouveau dans la version 2.1.
(Si vous êtes déjà familier des concepts de base concernant les tests, vous pouvez souhaiter passer à la liste des méthodes.)
The Python unit testing framework, sometimes referred to as « PyUnit, » is a Python language version of JUnit, by Kent Beck and Erich Gamma. JUnit is, in turn, a Java version of Kent’s Smalltalk testing framework. Each is the de facto standard unit testing framework for its respective language.
unittest
supports test automation, sharing of setup and shutdown code for
tests, aggregation of tests into collections, and independence of the tests from
the reporting framework. The unittest
module provides classes that make
it easy to support these qualities for a set of tests.
To achieve this, unittest
supports some important concepts:
- 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
A test case is the smallest unit of testing. It checks for a specific response to a particular set of inputs.
unittest
provides a base class,TestCase
, which may be used to create new test cases.- 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.
The test case and test fixture concepts are supported through the
TestCase
and FunctionTestCase
classes; the former should be
used when creating new tests, and the latter can be used when integrating
existing test code with a unittest
-driven framework. When building test
fixtures using TestCase
, the setUp()
and
tearDown()
methods can be overridden to provide initialization
and cleanup for the fixture. With FunctionTestCase
, existing functions
can be passed to the constructor for these purposes. When the test is run, the
fixture initialization is run first; if it succeeds, the cleanup method is run
after the test has been executed, regardless of the outcome of the test. Each
instance of the TestCase
will only be used to run a single test method,
so a new fixture is created for each test.
Test suites are implemented by the TestSuite
class. This class allows
individual tests and test suites to be aggregated; when the suite is executed,
all tests added directly to the suite and in « child » test suites are run.
A test runner is an object that provides a single method,
run()
, which accepts a TestCase
or TestSuite
object as a parameter, and returns a result object. The class
TestResult
is provided for use as the result object. unittest
provides the TextTestRunner
as an example test runner which reports
test results on the standard error stream by default. Alternate runners can be
implemented for other environments (such as graphical environments) without any
need to derive from a specific class.
Voir aussi
- Module
doctest
Un autre module de test adoptant une approche très différente.
- unittest2: A backport of new unittest features for Python 2.4-2.6
Many new features were added to unittest in Python 2.7, including test discovery. unittest2 allows you to use these features with earlier versions of Python.
- 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
.- Nose and pytest
Des frameworks tierces de tests unitaires avec une syntaxe allégée pour l’écriture des tests. Par exemple,
assert func(10) == 42
.- The Python Testing Tools Taxonomy
Une liste étendue des outils de test pour Python comprenant des frameworks de tests fonctionnels et des bibliothèques d’objets simulés (mocks).
- Testing in Python Mailing List
un groupe de discussion dédié aux tests, et outils de test, en Python.
25.3.1. 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
Instead of unittest.main()
, there are other ways to run the tests with a
finer level of control, less terse output, and no requirement to be run from the
command line. For example, the last two lines may be replaced with:
suite = unittest.TestLoader().loadTestsFromTestCase(TestStringMethods)
unittest.TextTestRunner(verbosity=2).run(suite)
Running the revised script from the interpreter or another script produces the following output:
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.
25.3.2. 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.
Pour obtenir plus de détails lors de l’exécution utilisez l’option -v (plus de verbosité) :
python -m unittest -v test_module
Pour afficher la liste de toutes les options de la commande utilisez l’option -h :
python -m unittest -h
Modifié dans la version 2.7: 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.
25.3.2.1. 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.
Nouveau dans la version 2.7: Les options de ligne de commande -b
, -c
et -f
ont été ajoutées.
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.
25.3.3. Découverte des tests¶
Nouveau dans la version 2.7.
Unittest supports simple test discovery. In order to be compatible with test discovery, all of the test files must be modules or packages importable from the top-level directory of the project (this means that their filenames must be valid identifiers).
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
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.
25.3.4. Organiser le code de test¶
The basic building blocks of unit testing are test cases — single
scenarios that must be set up and checked for correctness. In unittest
,
test cases are represented by instances of unittest
’s TestCase
class. To make your own test cases you must write subclasses of
TestCase
, or use FunctionTestCase
.
An instance of a TestCase
-derived class is an object that can
completely run a single test method, together with optional set-up and tidy-up
code.
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.
The simplest TestCase
subclass will simply override the
runTest()
method in order to perform specific testing code:
import unittest
class DefaultWidgetSizeTestCase(unittest.TestCase):
def runTest(self):
widget = Widget('The widget')
self.assertEqual(widget.size(), (50, 50), 'incorrect default size')
Note that in order to test something, we use one of the assert*()
methods provided by the TestCase
base class. If the test fails, an
exception will be raised, and unittest
will identify the test case as a
failure. Any other exceptions will be treated as errors. This
helps you identify where the problem is: failures are caused by incorrect
results - a 5 where you expected a 6. Errors are caused by incorrect
code - e.g., a TypeError
caused by an incorrect function call.
The way to run a test case will be described later. For now, note that to construct an instance of such a test case, we call its constructor without arguments:
testCase = DefaultWidgetSizeTestCase()
Now, such test cases can be numerous, and their set-up can be repetitive. In
the above case, constructing a Widget
in each of 100 Widget test case
subclasses would mean unsightly duplication.
Luckily, we can factor out such set-up code by implementing a method called
setUp()
, which the testing framework will automatically call for
us when we run the test:
import unittest
class SimpleWidgetTestCase(unittest.TestCase):
def setUp(self):
self.widget = Widget('The widget')
class DefaultWidgetSizeTestCase(SimpleWidgetTestCase):
def runTest(self):
self.assertEqual(self.widget.size(), (50,50),
'incorrect default size')
class WidgetResizeTestCase(SimpleWidgetTestCase):
def runTest(self):
self.widget.resize(100,150)
self.assertEqual(self.widget.size(), (100,150),
'wrong size after resize')
If the setUp()
method raises an exception while the test is
running, the framework will consider the test to have suffered an error, and the
runTest()
method will not be executed.
Similarly, we can provide a tearDown()
method that tidies up
after the runTest()
method has been run:
import unittest
class SimpleWidgetTestCase(unittest.TestCase):
def setUp(self):
self.widget = Widget('The widget')
def tearDown(self):
self.widget.dispose()
self.widget = None
If setUp()
succeeded, the tearDown()
method will
be run whether runTest()
succeeded or not.
Such a working environment for the testing code is called a fixture.
Often, many small test cases will use the same fixture. In this case, we would
end up subclassing SimpleWidgetTestCase
into many small one-method
classes such as DefaultWidgetSizeTestCase
. This is time-consuming and
discouraging, so in the same vein as JUnit, unittest
provides a simpler
mechanism:
import unittest
class WidgetTestCase(unittest.TestCase):
def setUp(self):
self.widget = Widget('The widget')
def tearDown(self):
self.widget.dispose()
self.widget = None
def test_default_size(self):
self.assertEqual(self.widget.size(), (50,50),
'incorrect default size')
def test_resize(self):
self.widget.resize(100,150)
self.assertEqual(self.widget.size(), (100,150),
'wrong size after resize')
Here we have not provided a runTest()
method, but have instead
provided two different test methods. Class instances will now each run one of
the test_*()
methods, with self.widget
created and destroyed
separately for each instance. When creating an instance we must specify the
test method it is to run. We do this by passing the method name in the
constructor:
defaultSizeTestCase = WidgetTestCase('test_default_size')
resizeTestCase = WidgetTestCase('test_resize')
Test case instances are grouped together according to the features they test.
unittest
provides a mechanism for this: the test suite,
represented by unittest
’s TestSuite
class:
widgetTestSuite = unittest.TestSuite()
widgetTestSuite.addTest(WidgetTestCase('test_default_size'))
widgetTestSuite.addTest(WidgetTestCase('test_resize'))
For the ease of running tests, as we will see later, it is a good idea to provide in each test module a callable object that returns a pre-built test suite:
def suite():
suite = unittest.TestSuite()
suite.addTest(WidgetTestCase('test_default_size'))
suite.addTest(WidgetTestCase('test_resize'))
return suite
or even:
def suite():
tests = ['test_default_size', 'test_resize']
return unittest.TestSuite(map(WidgetTestCase, tests))
Since it is a common pattern to create a TestCase
subclass with many
similarly named test functions, unittest
provides a TestLoader
class that can be used to automate the process of creating a test suite and
populating it with individual tests. For example,
suite = unittest.TestLoader().loadTestsFromTestCase(WidgetTestCase)
will create a test suite that will run WidgetTestCase.test_default_size()
and
WidgetTestCase.test_resize
. TestLoader
uses the 'test'
method
name prefix to identify test methods automatically.
Note that the order in which the various test cases will be run is determined by sorting the test function names with respect to the built-in ordering for strings.
Often it is desirable to group suites of test cases together, so as to run tests
for the whole system at once. This is easy, since TestSuite
instances
can be added to a TestSuite
just as TestCase
instances can be
added to a TestSuite
:
suite1 = module1.TheTestSuite()
suite2 = module2.TheTestSuite()
alltests = unittest.TestSuite([suite1, suite2])
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.
25.3.5. 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
# ...
one can create an equivalent test case instance as follows:
testcase = unittest.FunctionTestCase(testSomething)
If there are additional set-up and tear-down methods that should be called as part of the test case’s operation, they can also be provided like so:
testcase = unittest.FunctionTestCase(testSomething,
setUp=makeSomethingDB,
tearDown=deleteSomethingDB)
To make migrating existing test suites easier, unittest
supports tests
raising AssertionError
to indicate test failure. However, it is
recommended that you use the explicit TestCase.fail*()
and
TestCase.assert*()
methods instead, as future versions of unittest
may treat AssertionError
differently.
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
.
25.3.6. Ignorer des tests et des erreurs prévisibles¶
Nouveau dans la version 2.7.
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 à utiliser le décorateur skip()
ou une de ses variantes conditionnelles.
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
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_windows_support (__main__.MyTestCase) ... skipped 'requires Windows'
----------------------------------------------------------------------
Ran 3 tests in 0.005s
OK (skipped=3)
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 suivants implémentent le système d’omission des tests et les erreurs prévisibles :
-
unittest.
skip
(reason)¶ Ignore sans condition le test décoré. La raison doit décrire la raison pour laquelle le test est omis.
-
unittest.
skipIf
(condition, reason)¶ Ignore le test décoré si la condition est vraie.
-
unittest.
skipUnless
(condition, reason)¶ Ignore le test décoré sauf si la condition est vraie.
-
unittest.
expectedFailure
()¶ Mark the test as an expected failure. If the test fails when run, the test is not counted as a failure.
-
exception
unittest.
SkipTest
(reason)¶ Cette exception est levée pour ignorer un test.
Habituellement, on utilise
TestCase.skipTest()
ou l’un des décorateurs d’omission au lieu de le lever une exception directement.
Skipped tests will not have setUp()
or tearDown()
run around them.
Skipped classes will not have setUpClass()
or tearDownClass()
run.
25.3.7. Classes et fonctions¶
Cette section décrit en détail l’API de unittest
.
25.3.7.1. Scénarios de tests¶
-
class
unittest.
TestCase
(methodName='runTest')¶ Instances of the
TestCase
class represent the smallest testable units in theunittest
universe. This class is intended to be used as a base class, with specific tests being implemented by concrete subclasses. This class implements the interface needed by the test runner to allow it to drive the test, and methods that the test code can use to check for and report various kinds of failure.Each instance of
TestCase
will run a single test method: the method named methodName. If you remember, we had an earlier example that went something like this:def suite(): suite = unittest.TestSuite() suite.addTest(WidgetTestCase('test_default_size')) suite.addTest(WidgetTestCase('test_resize')) return suite
Here, we create two instances of
WidgetTestCase
, each of which runs a single test.methodName defaults to
runTest()
.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
ouSkipTest
, 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
ouSkipTest
, 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 desetUp()
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
()¶ A class method called before tests in an individual class are run.
setUpClass
is called with the class as the only argument and must be decorated as aclassmethod()
:@classmethod def setUpClass(cls): ...
Voir Class and Module Fixtures pour plus de détails.
Nouveau dans la version 2.7.
-
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 uneclassmethod()
:@classmethod def tearDownClass(cls): ...
Voir Class and Module Fixtures pour plus de détails.
Nouveau dans la version 2.7.
-
run
(result=None)¶ Run the test, collecting the result into the test result object passed as result. If result is omitted or
None
, a temporary result object is created (by calling thedefaultTestResult()
method) and used. The result object is not returned torun()
”s caller.Le même effet peut être obtenu en appelant simplement l’instance
TestCase
.
-
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 2.7.
-
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
a == b
a != b
bool(x) is True
bool(x) is False
a is b
2.7
a is not b
2.7
x is None
2.7
x is not None
2.7
a in b
2.7
a not in b
2.7
isinstance(a, b)
2.7
not isinstance(a, b)
2.7
All the assert methods (except
assertRaises()
,assertRaisesRegexp()
) accept a msg argument that, if specified, is used as the error message on failure (see alsolongMessage
).-
assertEqual
(first, second, msg=None)¶ Vérifie que first et second sont égaux. Si les valeurs ne sont pas égales, le test échouera.
In addition, if first and second are the exact same type and one of list, tuple, dict, set, frozenset or unicode or any type that a subclass registers with
addTypeEqualityFunc()
the type-specific equality function will be called in order to generate a more useful default error message (see also the list of type-specific methods).Modifié dans la version 2.7: Ajout de l’appel automatique de la fonction d’égalité spécifique au type.
-
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
(utilisezassertIs(expr, True)
pour cette dernière). Cette méthode doit également être évitée lorsque des méthodes plus spécifiques sont disponibles (par exempleassertEqual(a, b)
au lieu deassertTrue(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 2.7.
-
assertIsNone
(expr, msg=None)¶ -
assertIsNotNone
(expr, msg=None)¶ Vérifie que expr est (ou n’est pas) la valeur
None
.Nouveau dans la version 2.7.
-
assertIn
(first, second, msg=None)¶ -
assertNotIn
(first, second, msg=None)¶ Vérifie que first est (ou n’est pas) dans second.
Nouveau dans la version 2.7.
-
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, utilisezassertIs(type(obj), cls)
.Nouveau dans la version 2.7.
It is also possible to check that exceptions and warnings are raised using the following methods:
Méthode
Vérifie que
Disponible en
fun(*args, **kwds)
lève bien l’exception excfun(*args, **kwds)
lève bien l’exception exc et que le message correspond au motif de l’expression régulière r2.7
-
assertRaises
(exception, callable, *args, **kwds)¶ -
assertRaises
(exception) 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.If only the exception argument is given, returns a context manager so that the code under test can be written inline rather than as a function:
with self.assertRaises(SomeException): do_something()
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 2.7: Ajout de la possibilité d’utiliser
assertRaises()
comme gestionnaire de contexte.
-
assertRaisesRegexp
(exception, regexp, callable, *args, **kwds)¶ -
assertRaisesRegexp
(exception, regexp) Like
assertRaises()
but also tests that regexp matches on the string representation of the raised exception. regexp may be a regular expression object or a string containing a regular expression suitable for use byre.search()
. Examples:self.assertRaisesRegexp(ValueError, "invalid literal for.*XYZ'$", int, 'XYZ')
ou :
with self.assertRaisesRegexp(ValueError, 'literal'): int('XYZ')
Nouveau dans la version 2.7.
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
round(a-b, 7) == 0
round(a-b, 7) != 0
a > b
2.7
a >= b
2.7
a < b
2.7
a <= b
2.7
r.search(s)
2.7
not r.search(s)
2.7
sorted(a) == sorted(b) and works with unhashable objs
2.7
all the key/value pairs in a exist in b
2.7
-
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.
Supplying both delta and places raises a
TypeError
.Modifié dans la version 2.7:
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 2.7.
-
assertRegexpMatches
(text, regexp, msg=None)¶ Test that a regexp search matches text. In case of failure, the error message will include the pattern and the text (or the pattern and the part of text that unexpectedly matched). regexp may be a regular expression object or a string containing a regular expression suitable for use by
re.search()
.Nouveau dans la version 2.7.
-
assertNotRegexpMatches
(text, regexp, msg=None)¶ Verifies that a regexp search does not match text. Fails with an error message including the pattern and the part of text that matches. regexp may be a regular expression object or a string containing a regular expression suitable for use by
re.search()
.Nouveau dans la version 2.7.
-
assertItemsEqual
(actual, expected, msg=None)¶ Test that sequence expected contains the same elements as actual, regardless of their order. When they don’t, an error message listing the differences between the sequences will be generated.
Duplicate elements are not ignored when comparing actual and expected. It verifies if each element has the same count in both sequences. It is the equivalent of
assertEqual(sorted(expected), sorted(actual))
but it works with sequences of unhashable objects as well.In Python 3, this method is named
assertCountEqual
.Nouveau dans la version 2.7.
-
assertDictContainsSubset
(expected, actual, msg=None)¶ Tests whether the key/value pairs in dictionary actual are a superset of those in expected. If not, an error message listing the missing keys and mismatched values is generated.
Nouveau dans la version 2.7.
Obsolète depuis 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 utilisantaddTypeEqualityFunc()
:-
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 commeassertEqual()
le fait. Il doit leverself.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 2.7.
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
chaînes
2.7
séquences
2.7
listes
2.7
n-uplets
2.7
sets ou frozensets
2.7
dictionnaires
2.7
-
assertMultiLineEqual
(first, second, msg=None)¶ Test that the multiline string first is equal to the string second. When not equal a diff of the two strings highlighting the differences will be included in the error message. This method is used by default when comparing Unicode strings with
assertEqual()
.Nouveau dans la version 2.7.
-
assertSequenceEqual
(seq1, seq2, msg=None, seq_type=None)¶ Tests that two sequences are equal. If a seq_type is supplied, both seq1 and seq2 must be instances of seq_type or a failure will be raised. If the sequences are different an error message is constructed that shows the difference between the two.
Cette méthode n’est pas appelée directement par
assertEqual()
, mais sert à implémenterassertListEqual()
etassertTupleEqual()
.Nouveau dans la version 2.7.
-
assertListEqual
(list1, list2, msg=None)¶ -
assertTupleEqual
(tuple1, tuple2, 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 2.7.
-
assertSetEqual
(set1, set2, 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()
.Fails if either of set1 or set2 does not have a
set.difference()
method.Nouveau dans la version 2.7.
-
assertDictEqual
(expected, actual, 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 2.7.
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
¶ If set to
True
then any explicit failure message you pass in to the assert methods will be appended to the end of the normal failure message. The normal messages contain useful information about the objects involved, for example the message from assertEqual shows you the repr of the two unequal objects. Setting this attribute toTrue
allows you to have a custom error message in addition to the normal one.This attribute defaults to
False
, meaning that a custom message passed to an assert method will silence the normal message.The class setting can be overridden in individual tests by assigning an instance attribute to
True
orFalse
before calling the assert methods.Nouveau dans la version 2.7.
-
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()
etassertMultiLineEqual()
.Régler
maxDiff
surNone`
signifie qu’il n’y a pas de longueur maximale pour les diffs.Nouveau dans la version 2.7.
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 toujours1
.
-
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 deTestResult
; les sous-classes deTestCase
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
()¶ Returns a description of the test, or
None
if no description has been provided. The default implementation of this method returns the first line of the test method’s docstring, if available, orNone
.
-
addCleanup
(function, *args, **kwargs)¶ Add a function to be called after
tearDown()
to cleanup resources used during the test. Functions will be called in reverse order to the order they are added (LIFO). They are called with any arguments and keyword arguments passed intoaddCleanup()
when they are added.Si
setUp()
échoue, cela signifie quetearDown()
n’est pas appelé, alors que les fonctions de nettoyage ajoutées seront toujours appelées.Nouveau dans la version 2.7.
-
doCleanups
()¶ Cette méthode est appelée sans conditions après
tearDown()
, ou aprèssetUp()
sisetUp()
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 appelerdoCleanups()
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 2.7.
-
-
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é surunittest
.
25.3.7.1.1. 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
Deprecated alias(es)
failUnlessEqual, assertEquals
failIfEqual
failUnless, assert_
failIf
failUnlessRaises
failUnlessAlmostEqual
failIfAlmostEqual
Obsolète depuis la version 2.7: the aliases listed in the second column
25.3.7.2. Regroupement des tests¶
-
class
unittest.
TestSuite
(tests=())¶ This class represents an aggregation of individual test cases and test suites. The class presents the interface needed by the test runner to allow it to be run as any other test case. Running a
TestSuite
instance is the same as iterating over the suite, running each test individually.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 objetsTestCase
, 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 deTestSuite
:-
addTests
(tests)¶ Ajouter tous les tests d’un itérable d’instances de
TestCase
et deTestSuite
à 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 avecTestCase
:-
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__
()¶ Tests grouped by a
TestSuite
are always accessed by iteration. Subclasses can lazily provide tests by overriding__iter__()
. Note that this method maybe called several times on a single suite (for example when counting tests or comparing for equality) so the tests returned must be the same for repeated iterations.Modifié dans la version 2.7: 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.
Dans l’utilisation typique de l’objet
TestSuite
, la méthoderun()
est invoquée par une classeTestRunner
plutôt que par le système de test de l’utilisateur.-
25.3.7.3. 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 moduleunittest
fournit une instance qui peut être partagée commeunittest.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 :-
loadTestsFromTestCase
(testCaseClass)¶ Return a suite of all test cases contained in the
TestCase
-derivedtestCaseClass
.
-
loadTestsFromModule
(module)¶ Return a suite of all test cases contained in the given module. This method searches module for classes derived from
TestCase
and creates an instance of the class for each test method defined for the class.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.If a module provides a
load_tests
function it will be called to load the tests. This allows modules to customize test loading. This is the load_tests protocol.Modifié dans la version 2.7: Ajout de la prise en charge de
load_tests
.
-
loadTestsFromName
(name, module=None)¶ Return a suite of all test cases given a string specifier.
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 classeTestCase
ou de classeTestSuite
. 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 classeTestCase
(classe dérivée de la classeSampleTestCase
) avec trois méthodes de test (test_one()
,test_two()
ettest_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 testtest_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é.
-
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.
If importing a module fails, for example due to a syntax error, then this will be recorded as a single error and discovery will continue.
If a test package name (directory with
__init__.py
) matches the pattern then the package will be checked for aload_tests
function. If this exists then it will be called with loader, tests, pattern.If load_tests exists then discovery does not recurse into the package,
load_tests
is responsible for loading all tests in the package.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 aloader. discover()
.start_dir peut être un nom de module ainsi qu’un répertoire.
Nouveau dans la version 2.7.
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éthodesloadTestsFrom*()
.
-
sortTestMethodsUsing
¶ Function to be used to compare method names when sorting them in
getTestCaseNames()
and all theloadTestsFrom*()
methods. The default value is the built-incmp()
function; the attribute can also be set toNone
to disable the sort.
-
-
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 classesTestCase
etTestSuite
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’objetTestResult
généré en exécutant un ensemble de tests à des fins de génération de comptes-rendu. Une instance deTestResult
est alors renvoyée par la méthodeTestRunner.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.Modifié dans la version 2.2: Contains formatted tracebacks instead of
sys.exc_info()
results.
-
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éthodesTestCase.assert*()
.Modifié dans la version 2.2: Contains formatted tracebacks instead of
sys.exc_info()
results.
-
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 2.7.
-
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.
-
testsRun
¶ Le nombre total de tests effectués jusqu’à présent.
-
buffer
¶ S’il est défini sur true,
sys.stdout
etsys.stderr
sont mis dans un tampon entre les appels destartTest()
etstopTest()
. La sortie collectée est répercutée sur les sortiessys.stdout
etsys.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 2.7.
-
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 2.7.
-
wasSuccessful
()¶ Renvoie
True
si tous les tests effectués jusqu’à présent ont réussi, sinon renvoieFalse
.
-
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
surTrue
. Les instances deTestRunner
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 deTestRunner
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 2.7.
-
stopTestRun
()¶ Appelé une fois après l’exécution des tests.
Nouveau dans la version 2.7.
-
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’attributerrors
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’attributerrors
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’attributskipped
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’attributerrors
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.
-
-
class
unittest.
TextTestResult
(stream, descriptions, verbosity)¶ Une implémentation concrète de
TestResult
utilisé par la classeTextTestRunner
.Nouveau dans la version 2.7: 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 classeTestLoader
n’est nécessaire, cette instance peut être utilisée au lieu de créer plusieurs fois de nouvelles instances.
-
class
unittest.
TextTestRunner
(stream=sys.stderr, descriptions=True, verbosity=1, failfast=False, buffer=False, resultclass=None)¶ A basic test runner implementation which prints results on standard error. It has a few configurable parameters, but is essentially very simple. Graphical applications which run test suites should provide alternate implementations.
-
_makeResult
()¶ Cette méthode renvoie l’instance de
TestResult
utilisée parrun()
. Il n’est pas destiné à être appelé directement, mais peut être surchargée dans des sous-classes pour fournir unTestResult
personnalisé._makeResult()
instancie la classe ou l’appelable passé dans le constructeurTextTestRunner
comme argumentresultclass
. Il vaut par défautTextTestResult
si aucuneresultclass
n’est fournie. La classe de résultat est instanciée avec les arguments suivants :stream, descriptions, verbosity
-
-
unittest.
main
([module[, defaultTest[, argv[, testRunner[, testLoader[, exit[, verbosity[, failfast[, catchbreak[, buffer]]]]]]]]]])¶ 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)
The defaultTest argument is the name of the test to run if no test names are specified via argv. If not specified or
None
and no test names are provided via argv, all tests found in module are run.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 desys.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
appellesys.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 dedefaultTestLoader
.Les
main
sont utilisés à partir de l’interpréteur interactif en passant dans l’argumentexit=False
. Ceci affiche le résultat sur la sortie standard sans appelersys.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’appel de
main
renvoie en fait une instance de la classeTestProgram
. Le résultat des tests effectués est enregistré sous l’attributresult
.Modifié dans la version 2.7: The exit, verbosity, failfast, catchbreak and buffer parameters were added.
25.3.7.3.1. Protocole de chargement des tests (load_tests Protocol)¶
Nouveau dans la version 2.7.
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, 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
If discovery is started, either from the command line or by calling
TestLoader.discover()
, with a pattern that matches a package
name then the package __init__.py
will be checked for load_tests
.
Note
The default pattern is 'test*.py'
. This matches all Python files
that start with 'test'
but won’t match any test directories.
A pattern like 'test*'
will match test packages as well as
modules.
If the package __init__.py
defines load_tests
then it will be
called and discovery not continued into the package. load_tests
is called with the following arguments:
load_tests(loader, standard_tests, pattern)
Doit retourner 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
25.3.8. 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.
25.3.8.1. 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.
25.3.8.2. 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.
25.3.9. Traitement des signaux¶
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éthodestop()
.Nouveau dans la version 2.7.
-
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.Nouveau dans la version 2.7.
-
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.Nouveau dans la version 2.7.
-
unittest.
removeHandler
(function=None)¶ When called without arguments this function removes the control-c handler if it has been installed. This function can also be used as a test decorator to temporarily remove the handler while the test is being executed:
@unittest.removeHandler def test_signal_handling(self): ...
Nouveau dans la version 2.7.