Skip to content

C
cpython
Kaydet (Commit) 2d1e88a4 authored tarafından Ezio Melotti's avatar Ezio Melotti
Dosyalara gözat
Seçenekler

Backport from 3.2 several improvements and fixes for unittest.rst.

üst 7983d33f
Hide whitespace changes
Inline Side-by-side
Showing with 351 additions and 259 deletions
Doc/library/unittest.rst
Dosyayı görüntüle @ 2d1e88a4
...@@ -8,9 +8,8 @@ ...@@ -8,9 +8,8 @@
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
.. sectionauthor:: Raymond Hettinger <python@rcn.com> .. sectionauthor:: Raymond Hettinger <python@rcn.com>
(If you are already familiar with the basic concepts of testing, you might want
.. versionchanged:: 3.1 to skip to :ref:`the list of assert methods <assert-methods>`.)
Added test :ref:`skipping and expected failures <unittest-skipping>`.
The Python unit testing framework, sometimes referred to as "PyUnit," is a 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 Python language version of JUnit, by Kent Beck and Erich Gamma. JUnit is, in
...@@ -77,16 +76,26 @@ need to derive from a specific class. ...@@ -77,16 +76,26 @@ need to derive from a specific class.
Module :mod:`doctest` Module :mod:`doctest`
Another test-support module with a very different flavor. Another test-support module with a very different flavor.
`unittest2: A backport of new unittest features for Python 2.4-2.6 <http://pypi.python.org/pypi/unittest2>`_
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 <http://www.XProgramming.com/testfram.htm>`_ `Simple Smalltalk Testing: With Patterns <http://www.XProgramming.com/testfram.htm>`_
Kent Beck's original paper on testing frameworks using the pattern shared by Kent Beck's original paper on testing frameworks using the pattern shared
:mod:`unittest`. by :mod:`unittest`.
`Nose <http://code.google.com/p/python-nose/>`_ and `py.test <http://pytest.org>`_ `Nose <http://code.google.com/p/python-nose/>`_ and `py.test <http://pytest.org>`_
Third-party unittest frameworks with a lighter-weight syntax Third-party unittest frameworks with a lighter-weight syntax for writing
for writing tests. For example, ``assert func(10) == 42``. tests. For example, ``assert func(10) == 42``.
`The Python Testing Tools Taxonomy <http://pycheesecake.org/wiki/PythonTestingToolsTaxonomy>`_
An extensive list of Python testing tools including functional testing
frameworks and mock object libraries.
`python-mock <http://python-mock.sourceforge.net/>`_ and `minimock <http://blog.ianbicking.org/minimock.html>`_ `Testing in Python Mailing List <http://lists.idyll.org/listinfo/testing-in-python>`_
Tools for creating mock test objects (objects simulating external resources). A special-interest-group for discussion of testing, and testing tools,
in Python.
.. _unittest-minimal-example: .. _unittest-minimal-example:
...@@ -113,12 +122,16 @@ Here is a short script to test three functions from the :mod:`random` module:: ...@@ -113,12 +122,16 @@ Here is a short script to test three functions from the :mod:`random` module::
self.seq.sort() self.seq.sort()
self.assertEqual(self.seq, list(range(10))) self.assertEqual(self.seq, list(range(10)))
# should raise an exception for an immutable sequence
self.assertRaises(TypeError, random.shuffle, (1,2,3))
def test_choice(self): def test_choice(self):
element = random.choice(self.seq) element = random.choice(self.seq)
self.assertIn(element, self.seq) self.assertIn(element, self.seq)
def test_sample(self): def test_sample(self):
self.assertRaises(ValueError, random.sample, self.seq, 20) with self.assertRaises(ValueError):
random.sample(self.seq, 20)
for element in random.sample(self.seq, 5): for element in random.sample(self.seq, 5):
self.assertIn(element, self.seq) self.assertIn(element, self.seq)
...@@ -131,7 +144,7 @@ individual tests are defined with methods whose names start with the letters ...@@ -131,7 +144,7 @@ individual tests are defined with methods whose names start with the letters
represent tests. represent tests.
The crux of each test is a call to :meth:`~TestCase.assertEqual` to check for an The crux of each test is a call to :meth:`~TestCase.assertEqual` to check for an
expected result; :meth:`~TestCase.assert_` to verify a condition; or expected result; :meth:`~TestCase.assertTrue` to verify a condition; or
:meth:`~TestCase.assertRaises` to verify that an expected exception gets raised. :meth:`~TestCase.assertRaises` to verify that an expected exception gets raised.
These methods are used instead of the :keyword:`assert` statement so the test These methods are used instead of the :keyword:`assert` statement so the test
runner can accumulate all test results and produce a report. runner can accumulate all test results and produce a report.
...@@ -178,7 +191,7 @@ documentation explores the full feature set from first principles. ...@@ -178,7 +191,7 @@ documentation explores the full feature set from first principles.
.. _unittest-command-line-interface: .. _unittest-command-line-interface:
Command-Line Interface Command Line Interface
---------------------- ----------------------
The unittest module can be used from the command line to run tests from The unittest module can be used from the command line to run tests from
...@@ -230,13 +243,12 @@ The simplest :class:`TestCase` subclass will simply override the ...@@ -230,13 +243,12 @@ The simplest :class:`TestCase` subclass will simply override the
self.assertEqual(widget.size(), (50, 50), 'incorrect default size') self.assertEqual(widget.size(), (50, 50), 'incorrect default size')
Note that in order to test something, we use the one of the :meth:`assert\*` Note that in order to test something, we use the one of the :meth:`assert\*`
methods provided by the :class:`TestCase` base class. If the methods provided by the :class:`TestCase` base class. If the test fails, an
test fails, an exception will be raised, and :mod:`unittest` will identify the exception will be raised, and :mod:`unittest` will identify the test case as a
test case as a :dfn:`failure`. Any other exceptions will be treated as :dfn:`failure`. Any other exceptions will be treated as :dfn:`errors`. This
:dfn:`errors`. This helps you identify where the problem is: :dfn:`failures` are helps you identify where the problem is: :dfn:`failures` are caused by incorrect
caused by incorrect results - a 5 where you expected a 6. :dfn:`Errors` are results - a 5 where you expected a 6. :dfn:`Errors` are caused by incorrect
caused by incorrect code - e.g., a :exc:`TypeError` caused by an incorrect code - e.g., a :exc:`TypeError` caused by an incorrect function call.
function call.
The way to run a test case will be described later. For now, note that to 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 construct an instance of such a test case, we call its constructor without
...@@ -436,10 +448,10 @@ may treat :exc:`AssertionError` differently. ...@@ -436,10 +448,10 @@ may treat :exc:`AssertionError` differently.
.. note:: .. note::
Even though :class:`FunctionTestCase` can be used to quickly convert an existing Even though :class:`FunctionTestCase` can be used to quickly convert an
test base over to a :mod:`unittest`\ -based system, this approach is not existing test base over to a :mod:`unittest`\ -based system, this approach is
recommended. Taking the time to set up proper :class:`TestCase` subclasses will not recommended. Taking the time to set up proper :class:`TestCase`
make future test refactorings infinitely easier. subclasses will make future test refactorings infinitely easier.
In some cases, the existing tests may have been written using the :mod:`doctest` In some cases, the existing tests may have been written using the :mod:`doctest`
module. If so, :mod:`doctest` provides a :class:`DocTestSuite` class that can module. If so, :mod:`doctest` provides a :class:`DocTestSuite` class that can
...@@ -452,6 +464,8 @@ automatically build :class:`unittest.TestSuite` instances from the existing ...@@ -452,6 +464,8 @@ automatically build :class:`unittest.TestSuite` instances from the existing
Skipping tests and expected failures Skipping tests and expected failures
------------------------------------ ------------------------------------
.. versionadded:: 3.1
Unittest supports skipping individual test methods and even whole classes of Unittest supports skipping individual test methods and even whole classes of
tests. In addition, it supports marking a test as a "expected failure," a test tests. In addition, it supports marking a test as a "expected failure," a test
that is broken and will fail, but shouldn't be counted as a failure on a that is broken and will fail, but shouldn't be counted as a failure on a
...@@ -468,7 +482,8 @@ Basic skipping looks like this: :: ...@@ -468,7 +482,8 @@ Basic skipping looks like this: ::
def test_nothing(self): def test_nothing(self):
self.fail("shouldn't happen") self.fail("shouldn't happen")
@unittest.skipIf(mylib.__version__ < (1, 3), "not supported in this library version") @unittest.skipIf(mylib.__version__ < (1, 3),
"not supported in this library version")
def test_format(self): def test_format(self):
# Tests that work for only a certain version of the library. # Tests that work for only a certain version of the library.
pass pass
...@@ -603,7 +618,7 @@ Test cases ...@@ -603,7 +618,7 @@ Test cases
.. method:: run(result=None) .. method:: run(result=None)
Run the test, collecting the result into the test result object passed as Run the test, collecting the result into the test result object passed as
*result*. If *result* is omitted or :const:`None`, a temporary result *result*. If *result* is omitted or ``None``, a temporary result
object is created (by calling the :meth:`defaultTestResult` method) and object is created (by calling the :meth:`defaultTestResult` method) and
used. The result object is not returned to :meth:`run`'s caller. used. The result object is not returned to :meth:`run`'s caller.
...@@ -625,172 +640,230 @@ Test cases ...@@ -625,172 +640,230 @@ Test cases
by the test to be propagated to the caller, and can be used to support by the test to be propagated to the caller, and can be used to support
running tests under a debugger. running tests under a debugger.
The test code can use any of the following methods to check for and report .. _assert-methods:
failures.
The :class:`TestCase` class provides a number of methods to check for and
report failures, such as:
.. method:: assertTrue(expr, msg=None)
assert_(expr, msg=None) +-----------------------------------------+-----------------------------+---------------+
failUnless(expr, msg=None) | Method | Checks that | New in |
+=========================================+=============================+===============+
Signal a test failure if *expr* is false; the explanation for the failure | :meth:`assertEqual(a, b) | ``a == b`` | |
will be *msg* if given, otherwise it will be :const:`None`. | <TestCase.assertEqual>` | | |
+-----------------------------------------+-----------------------------+---------------+
.. deprecated:: 3.1 | :meth:`assertNotEqual(a, b) | ``a != b`` | |
:meth:`failUnless`. | <TestCase.assertNotEqual>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertTrue(x) | ``bool(x) is True`` | |
| <TestCase.assertTrue>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertFalse(x) | ``bool(x) is False`` | |
| <TestCase.assertFalse>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertIs(a, b) | ``a is b`` | 3.1 |
| <TestCase.assertIs>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertIsNot(a, b) | ``a is not b`` | 3.1 |
| <TestCase.assertIsNot>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertIsNone(x) | ``x is None`` | 3.1 |
| <TestCase.assertIsNone>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertIsNotNone(x) | ``x is not None`` | 3.1 |
| <TestCase.assertIsNotNone>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertIn(a, b) | ``a in b`` | 3.1 |
| <TestCase.assertIn>` | | |
+-----------------------------------------+-----------------------------+---------------+
| :meth:`assertNotIn(a, b) | ``a not in b`` | 3.1 |
| <TestCase.assertNotIn>` | | |
+-----------------------------------------+-----------------------------+---------------+
All the assert methods (except :meth:`assertRaises`,
:meth:`assertRaisesRegexp`, :meth:`assertWarns`, :meth:`assertWarnsRegexp`)
accept a *msg* argument that, if specified, is used as the error message on
failure (see also :data:`longMessage`).
.. method:: assertEqual(first, second, msg=None) .. method:: assertEqual(first, second, msg=None)
failUnlessEqual(first, second, msg=None)
Test that *first* and *second* are equal. If the values do not compare Test that *first* and *second* are equal. If the values do not compare
equal, the test will fail with the explanation given by *msg*, or equal, the test will fail.
:const:`None`. Note that using :meth:`assertEqual` improves upon
doing the comparison as the first parameter to :meth:`assertTrue`: the
default value for *msg* include representations of both *first* and
*second*.
In addition, if *first* and *second* are the exact same type and one of In addition, if *first* and *second* are the exact same type and one of
list, tuple, dict, set, or frozenset or any type that a subclass list, tuple, dict, set, frozenset or str or any type that a subclass
registers :meth:`addTypeEqualityFunc` the type specific equality function registers with :meth:`addTypeEqualityFunc` the type specific equality
will be called in order to generate a more useful default error message. function will be called in order to generate a more useful default
error message (see also the :ref:`list of type-specific methods
<type-specific-methods>`).
.. versionchanged:: 3.1 .. versionchanged:: 3.1
Added the automatic calling of type specific equality function. Added the automatic calling of type specific equality function.
.. deprecated:: 3.1
:meth:`failUnlessEqual`.
.. method:: assertNotEqual(first, second, msg=None) .. method:: assertNotEqual(first, second, msg=None)
failIfEqual(first, second, msg=None)
Test that *first* and *second* are not equal. If the values do compare Test that *first* and *second* are not equal. If the values do compare
equal, the test will fail with the explanation given by *msg*, or equal, the test will fail.
:const:`None`. Note that using :meth:`assertNotEqual` improves upon doing
the comparison as the first parameter to :meth:`assertTrue` is that the
default value for *msg* can be computed to include representations of both
*first* and *second*.
.. deprecated:: 3.1 .. method:: assertTrue(expr, msg=None)
:meth:`failIfEqual`. assertFalse(expr, msg=None)
Test that *expr* is true (or false).
.. method:: assertAlmostEqual(first, second, places=7, msg=None) Note that this is equivalent to ``bool(expr) is True`` and not to ``expr
failUnlessAlmostEqual(first, second, places=7, msg=None) is True`` (use ``assertIs(expr, True)`` for the latter). This method
should also be avoided when more specific methods are available (e.g.
``assertEqual(a, b)`` instead of ``assertTrue(a == b)``), because they
provide a better error message in case of failure.
Test that *first* and *second* are approximately equal by computing the
difference, rounding to the given number of decimal *places* (default 7),
and comparing to zero.
Note that comparing a given number of decimal places is not the same as .. method:: assertIs(first, second, msg=None)
comparing a given number of significant digits. If the values do not assertIsNot(first, second, msg=None)
compare equal, the test will fail with the explanation given by *msg*, or
:const:`None`.
.. deprecated:: 3.1 Test that *first* and *second* evaluate (or don't evaluate) to the same object.
:meth:`failUnlessAlmostEqual`.
.. versionadded:: 3.1
.. method:: assertNotAlmostEqual(first, second, places=7, msg=None)
failIfAlmostEqual(first, second, places=7, msg=None)
Test that *first* and *second* are not approximately equal by computing .. method:: assertIsNone(expr, msg=None)
the difference, rounding to the given number of decimal *places* (default assertIsNotNone(expr, msg=None)
7), and comparing to zero.
Note that comparing a given number of decimal places is not the same as Test that *expr* is (or is not) None.
comparing a given number of significant digits. If the values do not
compare equal, the test will fail with the explanation given by *msg*, or
:const:`None`.
.. deprecated:: 3.1 .. versionadded:: 3.1
:meth:`failIfAlmostEqual`.
.. method:: assertGreater(first, second, msg=None) .. method:: assertIn(first, second, msg=None)
assertGreaterEqual(first, second, msg=None) assertNotIn(first, second, msg=None)
assertLess(first, second, msg=None)
assertLessEqual(first, second, msg=None)
Test that *first* is respectively >, >=, < or <= than *second* depending
on the method name. If not, the test will fail with an explanation
or with the explanation given by *msg*::
>>> self.assertGreaterEqual(3, 4) Test that *first* is (or is not) in *second*.
AssertionError: "3" unexpectedly not greater than or equal to "4"
.. versionadded:: 3.1 .. versionadded:: 3.1
.. method:: assertMultiLineEqual(self, first, second, msg=None)
Test that the multiline string *first* is equal to the string *second*. It is also possible to check that exceptions and warnings are raised using
When not equal a diff of the two strings highlighting the differences the following methods:
will be included in the error message.
If specified *msg* will be used as the error message on failure. +---------------------------------------------------------+--------------------------------------+------------+
| Method | Checks that | New in |
+=========================================================+======================================+============+
| :meth:`assertRaises(exc, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises `exc` | |
| <TestCase.assertRaises>` | | |
+---------------------------------------------------------+--------------------------------------+------------+
| :meth:`assertRaisesRegexp(exc, re, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises `exc` | 3.1 |
| <TestCase.assertRaisesRegexp>` | and the message matches `re` | |
+---------------------------------------------------------+--------------------------------------+------------+
.. versionadded:: 3.1 .. method:: assertRaises(exception, callable, *args, **kwds)
assertRaises(exception)
.. method:: assertRegexpMatches(text, regexp, msg=None):
Verifies that a *regexp* search matches *text*. Fails with an error Test that an exception is raised when *callable* is called with any
message including the pattern and the *text*. *regexp* may be positional or keyword arguments that are also passed to
a regular expression object or a string containing a regular expression :meth:`assertRaises`. The test passes if *exception* is raised, is an
suitable for use by :func:`re.search`. error if another exception is raised, or fails if no exception is raised.
To catch any of a group of exceptions, a tuple containing the exception
classes may be passed as *exception*.
.. versionadded:: 3.1 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()
.. method:: assertIn(first, second, msg=None) .. versionchanged:: 3.1
assertNotIn(first, second, msg=None) Added the ability to use :meth:`assertRaises` as a context manager.
Tests that *first* is or is not in *second* with an explanatory error
message as appropriate.
If specified *msg* will be used as the error message on failure. .. method:: assertRaisesRegexp(exception, regexp, callable, *args, **kwds)
assertRaisesRegexp(exception, regexp)
.. versionadded:: 3.1 Like :meth:`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 by :func:`re.search`. Examples::
self.assertRaisesRegexp(ValueError, 'invalid literal for.*XYZ$',
int, 'XYZ')
.. method:: assertSameElements(actual, expected, msg=None) or::
Test that sequence *expected* contains the same elements as *actual*, with self.assertRaisesRegexp(ValueError, 'literal'):
regardless of their order. When they don't, an error message listing int('XYZ')
the differences between the sequences will be generated.
Duplicate elements are ignored when comparing *actual* and *expected*. .. versionadded:: 3.1
It is the equivalent of ``assertEqual(set(expected), set(actual))``
but it works with sequences of unhashable objects as well.
If specified *msg* will be used as the error message on failure.
.. versionadded:: 3.1
There are also other methods used to perform more specific checks, such as:
+---------------------------------------+--------------------------------+--------------+
| Method | Checks that | New in |
+=======================================+================================+==============+
| :meth:`assertAlmostEqual(a, b) | ``round(a-b, 7) == 0`` | |
| <TestCase.assertAlmostEqual>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertNotAlmostEqual(a, b) | ``round(a-b, 7) != 0`` | |
| <TestCase.assertNotAlmostEqual>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertGreater(a, b) | ``a > b`` | 3.1 |
| <TestCase.assertGreater>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertGreaterEqual(a, b) | ``a >= b`` | 3.1 |
| <TestCase.assertGreaterEqual>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertLess(a, b) | ``a < b`` | 3.1 |
| <TestCase.assertLess>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertLessEqual(a, b) | ``a <= b`` | 3.1 |
| <TestCase.assertLessEqual>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertRegexpMatches(s, re) | ``regex.search(s)`` | 3.1 |
| <TestCase.assertRegexpMatches>` | | |
+---------------------------------------+--------------------------------+--------------+
| :meth:`assertDictContainsSubset(a, b) | all the key/value pairs | 3.1 |
| <TestCase.assertDictContainsSubset>` | in `a` exist in `b` | |
+---------------------------------------+--------------------------------+--------------+
.. method:: assertAlmostEqual(first, second, places=7, msg=None, delta=None)
assertNotAlmostEqual(first, second, places=7, msg=None, delta=None)
Test that *first* and *second* are approximately (or not approximately)
equal by computing the difference, rounding to the given number of
decimal *places* (default 7), and comparing to zero. Note that these
methods round the values to the given number of *decimal places* (i.e.
like the :func:`round` function) and not *significant digits*.
If *delta* is supplied instead of *places* then the difference
between *first* and *second* must be less (or more) than *delta*.
Supplying both *delta* and *places* raises a ``TypeError``.
.. method:: assertSetEqual(set1, set2, msg=None)
Tests that two sets are equal. If not, an error message is constructed .. method:: assertGreater(first, second, msg=None)
that lists the differences between the sets. assertGreaterEqual(first, second, msg=None)
assertLess(first, second, msg=None)
assertLessEqual(first, second, msg=None)
Fails if either of *set1* or *set2* does not have a :meth:`set.difference` Test that *first* is respectively >, >=, < or <= than *second* depending
method. on the method name. If not, the test will fail::
If specified *msg* will be used as the error message on failure. >>> self.assertGreaterEqual(3, 4)
AssertionError: "3" unexpectedly not greater than or equal to "4"
.. versionadded:: 3.1 .. versionadded:: 3.1
.. method:: assertDictEqual(expected, actual, msg=None) .. method:: assertRegexpMatches(text, regexp, msg=None)
Test that two dictionaries are equal. If not, an error message is
constructed that shows the differences in the dictionaries.
If specified *msg* will be used as the error message on failure. 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 :func:`re.search`.
.. versionadded:: 3.1 .. versionadded:: 3.1 :meth:`~TestCase.assertRegexpMatches`
.. method:: assertDictContainsSubset(expected, actual, msg=None) .. method:: assertDictContainsSubset(expected, actual, msg=None)
...@@ -799,127 +872,141 @@ Test cases ...@@ -799,127 +872,141 @@ Test cases
superset of those in *expected*. If not, an error message listing superset of those in *expected*. If not, an error message listing
the missing keys and mismatched values is generated. the missing keys and mismatched values is generated.
If specified *msg* will be used as the error message on failure.
.. versionadded:: 3.1 .. versionadded:: 3.1
.. deprecated:: 3.2
.. method:: assertListEqual(list1, list2, msg=None) .. method:: assertSameElements(actual, expected, msg=None)
assertTupleEqual(tuple1, tuple2, msg=None)
Tests that two lists or tuples are equal. If not an error message is Test that sequence *expected* contains the same elements as *actual*,
constructed that shows only the differences between the two. An error regardless of their order. When they don't, an error message listing
is also raised if either of the parameters are of the wrong type. the differences between the sequences will be generated.
If specified *msg* will be used as the error message on failure. Duplicate elements are ignored when comparing *actual* and *expected*.
It is the equivalent of ``assertEqual(set(expected), set(actual))``
but it works with sequences of unhashable objects as well. Because
duplicates are ignored, this method has been deprecated in favour of
:meth:`assertItemsEqual`.
.. versionadded:: 3.1 .. versionadded:: 3.1
.. deprecated:: 3.2
.. method:: assertSequenceEqual(seq1, seq2, msg=None, seq_type=None) .. _type-specific-methods:
Tests that two sequences are equal. If a *seq_type* is supplied, both The :meth:`assertEqual` method dispatches the equality check for objects of
*seq1* and *seq2* must be instances of *seq_type* or a failure will the same type to different type-specific methods. These methods are already
be raised. If the sequences are different an error message is implemented for most of the built-in types, but it's also possible to
constructed that shows the difference between the two. register new methods using :meth:`addTypeEqualityFunc`:
If specified *msg* will be used as the error message on failure. .. method:: addTypeEqualityFunc(typeobj, function)
This method is used to implement :meth:`assertListEqual` and Registers a type-specific method called by :meth:`assertEqual` to check
:meth:`assertTupleEqual`. if two objects of exactly the same *typeobj* (not subclasses) compare
equal. *function* must take two positional arguments and a third msg=None
keyword argument just as :meth:`assertEqual` does. It must raise
:data:`self.failureException(msg) <failureException>` when inequality
between the first two parameters is detected -- possibly providing useful
information and explaining the inequalities in details in the error
message.
.. versionadded:: 3.1 .. versionadded:: 3.1
The list of type-specific methods automatically used by
:meth:`~TestCase.assertEqual` are summarized in the following table. Note
that it's usually not necessary to invoke these methods directly.
+-----------------------------------------+-----------------------------+--------------+
| Method | Used to compare | New in |
+=========================================+=============================+==============+
| :meth:`assertMultiLineEqual(a, b) | strings | 3.1 |
| <TestCase.assertMultiLineEqual>` | | |
+-----------------------------------------+-----------------------------+--------------+
| :meth:`assertSequenceEqual(a, b) | sequences | 3.1 |
| <TestCase.assertSequenceEqual>` | | |
+-----------------------------------------+-----------------------------+--------------+
| :meth:`assertListEqual(a, b) | lists | 3.1 |
| <TestCase.assertListEqual>` | | |
+-----------------------------------------+-----------------------------+--------------+
| :meth:`assertTupleEqual(a, b) | tuples | 3.1 |
| <TestCase.assertTupleEqual>` | | |
+-----------------------------------------+-----------------------------+--------------+
| :meth:`assertSetEqual(a, b) | sets or frozensets | 3.1 |
| <TestCase.assertSetEqual>` | | |
+-----------------------------------------+-----------------------------+--------------+
| :meth:`assertDictEqual(a, b) | dicts | 3.1 |
| <TestCase.assertDictEqual>` | | |
+-----------------------------------------+-----------------------------+--------------+
.. method:: assertMultiLineEqual(first, second, msg=None)
.. method:: assertRaises(exception, callable, *args, **kwds) Test that the multiline string *first* is equal to the string *second*.
failUnlessRaises(exception, callable, *args, **kwds) When not equal a diff of the two strings highlighting the differences
assertRaises(exception) will be included in the error message. This method is used by default
failUnlessRaises(exception) when comparing strings with :meth:`assertEqual`.
Test that an exception is raised when *callable* is called with any
positional or keyword arguments that are also passed to
:meth:`assertRaises`. The test passes if *exception* is raised, is an
error if another exception is raised, or fails if no exception is raised.
To catch any of a group of exceptions, a tuple containing the exception
classes may be passed as *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()
.. versionchanged:: 3.1
Added the ability to use :meth:`assertRaises` as a context manager.
.. deprecated:: 3.1
:meth:`failUnlessRaises`.
.. method:: assertRaisesRegexp(exception, regexp[, callable, ...]) .. versionadded:: 3.1
Like :meth:`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 by :func:`re.search`. Examples::
self.assertRaisesRegexp(ValueError, 'invalid literal for.*XYZ$', .. method:: assertSequenceEqual(seq1, seq2, msg=None, seq_type=None)
int, 'XYZ')
or:: 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.
with self.assertRaisesRegexp(ValueError, 'literal'): This method is not called directly by :meth:`assertEqual`, but
int('XYZ') it's used to implement :meth:`assertListEqual` and
:meth:`assertTupleEqual`.
.. versionadded:: 3.1 .. versionadded:: 3.1
.. method:: assertIsNone(expr, msg=None) .. method:: assertListEqual(list1, list2, msg=None)
assertTupleEqual(tuple1, tuple2, msg=None)
This signals a test failure if *expr* is not None. Tests that two lists or tuples are equal. If not an error message is
constructed that shows only the differences between the two. An error
is also raised if either of the parameters are of the wrong type.
These methods are used by default when comparing lists or tuples with
:meth:`assertEqual`.
.. versionadded:: 3.1 .. versionadded:: 3.1
.. method:: assertIsNotNone(expr, msg=None) .. method:: assertSetEqual(set1, set2, msg=None)
The inverse of the :meth:`assertIsNone` method.
This signals a test failure if *expr* is None.
.. versionadded:: 3.1
.. method:: assertIs(expr1, expr2, msg=None) Tests that two sets are equal. If not, an error message is constructed
that lists the differences between the sets. This method is used by
default when comparing sets or frozensets with :meth:`assertEqual`.
This signals a test failure if *expr1* and *expr2* don't evaluate to the same Fails if either of *set1* or *set2* does not have a :meth:`set.difference`
object. method.
.. versionadded:: 3.1 .. versionadded:: 3.1
.. method:: assertIsNot(expr1, expr2, msg=None) .. method:: assertDictEqual(expected, actual, msg=None)
The inverse of the :meth:`assertIs` method. Test that two dictionaries are equal. If not, an error message is
This signals a test failure if *expr1* and *expr2* evaluate to the same constructed that shows the differences in the dictionaries. This
object. method will be used by default to compare dictionaries in
calls to :meth:`assertEqual`.
.. versionadded:: 3.1 .. versionadded:: 3.1
.. method:: assertFalse(expr, msg=None)
failIf(expr, msg=None)
The inverse of the :meth:`assertTrue` method is the :meth:`assertFalse` method. .. _other-methods-and-attrs:
This signals a test failure if *expr* is true, with *msg* or :const:`None`
for the error message.
.. deprecated:: 3.1 Finally the :class:`TestCase` provides the following methods and attributes:
:meth:`failIf`.
.. method:: fail(msg=None) .. method:: fail(msg=None)
Signals a test failure unconditionally, with *msg* or :const:`None` for Signals a test failure unconditionally, with *msg* or ``None`` for
the error message. the error message.
...@@ -934,18 +1021,19 @@ Test cases ...@@ -934,18 +1021,19 @@ Test cases
.. attribute:: longMessage .. attribute:: longMessage
If set to True then any explicit failure message you pass in to the 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. :ref:`assert methods <assert-methods>` will be appended to the end of the
The normal messages contain useful information about the objects involved, normal failure message. The normal messages contain useful information
for example the message from assertEqual shows you the repr of the two about the objects involved, for example the message from assertEqual
unequal objects. Setting this attribute to True allows you to have a shows you the repr of the two unequal objects. Setting this attribute
custom error message in addition to the normal one. to ``True`` 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 This attribute defaults to ``False``, meaning that a custom message passed
to an assert method will silence the normal message. to an assert method will silence the normal message.
The class setting can be overridden in individual tests by assigning an The class setting can be overridden in individual tests by assigning an
instance attribute to True or False before calling the assert methods. instance attribute to ``True`` or ``False`` before calling the assert methods.
.. versionadded:: 3.1 .. versionadded:: 3.1
...@@ -979,7 +1067,7 @@ Test cases ...@@ -979,7 +1067,7 @@ Test cases
.. method:: shortDescription() .. method:: shortDescription()
Returns a description of the test, or :const:`None` if no description Returns a description of the test, or ``None`` if no description
has been provided. The default implementation of this method has been provided. The default implementation of this method
returns the first line of the test method's docstring, if available, returns the first line of the test method's docstring, if available,
along with the method name. along with the method name.
...@@ -991,23 +1079,6 @@ Test cases ...@@ -991,23 +1079,6 @@ Test cases
thoughtful enough to write a docstring. thoughtful enough to write a docstring.
.. method:: addTypeEqualityFunc(typeobj, function)
Registers a type specific :meth:`assertEqual` equality checking
function to be called by :meth:`assertEqual` when both objects it has
been asked to compare are exactly *typeobj* (not subclasses).
*function* must take two positional arguments and a third msg=None
keyword argument just as :meth:`assertEqual` does. It must raise
``self.failureException`` when inequality between the first two
parameters is detected.
One good use of custom equality checking functions for a type
is to raise ``self.failureException`` with an error message useful
for debugging the problem by explaining the inequalities in detail.
.. versionadded:: 3.1
.. method:: addCleanup(function, *args, **kwargs) .. method:: addCleanup(function, *args, **kwargs)
Add a function to be called after :meth:`tearDown` to cleanup resources Add a function to be called after :meth:`tearDown` to cleanup resources
...@@ -1019,7 +1090,7 @@ Test cases ...@@ -1019,7 +1090,7 @@ Test cases
If :meth:`setUp` fails, meaning that :meth:`tearDown` is not called, If :meth:`setUp` fails, meaning that :meth:`tearDown` is not called,
then any cleanup functions added will still be called. then any cleanup functions added will still be called.
.. versionadded:: 3.2 .. versionadded:: 3.1
.. method:: doCleanups() .. method:: doCleanups()
...@@ -1035,16 +1106,40 @@ Test cases ...@@ -1035,16 +1106,40 @@ Test cases
:meth:`doCleanups` pops methods off the stack of cleanup :meth:`doCleanups` pops methods off the stack of cleanup
functions one at a time, so it can be called at any time. functions one at a time, so it can be called at any time.
.. versionadded:: 3.2 .. versionadded:: 3.1
.. class:: FunctionTestCase(testFunc, setUp=None, tearDown=None, description=None) .. class:: FunctionTestCase(testFunc, setUp=None, tearDown=None, description=None)
This class implements the portion of the :class:`TestCase` interface which This class implements the portion of the :class:`TestCase` interface which
allows the test runner to drive the test, but does not provide the methods which allows the test runner to drive the test, but does not provide the methods
test code can use to check and report errors. This is used to create test cases which test code can use to check and report errors. This is used to create
using legacy test code, allowing it to be integrated into a :mod:`unittest`\ test cases using legacy test code, allowing it to be integrated into a
-based test framework. :mod:`unittest`-based test framework.
Deprecated aliases
##################
For historical reasons, some of the :class:`TestCase` methods had one or more
aliases that are now deprecated. The following table lists the correct names
along with their deprecated aliases:
============================== ===============================
Method Name Deprecated alias(es)
============================== ===============================
:meth:`.assertEqual` failUnlessEqual, assertEquals
:meth:`.assertNotEqual` failIfEqual
:meth:`.assertTrue` failUnless, assert\_
:meth:`.assertFalse` failIf
:meth:`.assertRaises` failUnlessRaises
:meth:`.assertAlmostEqual` failUnlessAlmostEqual
:meth:`.assertNotAlmostEqual` failIfAlmostEqual
============================== ===============================
.. deprecated:: 3.1
the aliases listed in the second column
.. _testsuite-objects: .. _testsuite-objects:
...@@ -1079,8 +1174,8 @@ Grouping tests ...@@ -1079,8 +1174,8 @@ Grouping tests
Add all the tests from an iterable of :class:`TestCase` and :class:`TestSuite` Add all the tests from an iterable of :class:`TestCase` and :class:`TestSuite`
instances to this test suite. instances to this test suite.
This is equivalent to iterating over *tests*, calling :meth:`addTest` for each This is equivalent to iterating over *tests*, calling :meth:`addTest` for
element. each element.
:class:`TestSuite` shares the following methods with :class:`TestCase`: :class:`TestSuite` shares the following methods with :class:`TestCase`:
...@@ -1114,11 +1209,6 @@ Grouping tests ...@@ -1114,11 +1209,6 @@ Grouping tests
(for example when counting tests or comparing for equality) (for example when counting tests or comparing for equality)
so the tests returned must be the same for repeated iterations. so the tests returned must be the same for repeated iterations.
.. versionchanged:: 3.2
In earlier versions the :class:`TestSuite` accessed tests directly rather
than through iteration, so overriding :meth:`__iter__` wasn't sufficient
for providing tests.
In the typical usage of a :class:`TestSuite` object, the :meth:`run` method In the typical usage of a :class:`TestSuite` object, the :meth:`run` method
is invoked by a :class:`TestRunner` rather than by the end-user test harness. is invoked by a :class:`TestRunner` rather than by the end-user test harness.
...@@ -1174,12 +1264,12 @@ Loading and running tests ...@@ -1174,12 +1264,12 @@ Loading and running tests
For example, if you have a module :mod:`SampleTests` containing a For example, if you have a module :mod:`SampleTests` containing a
:class:`TestCase`\ -derived class :class:`SampleTestCase` with three test :class:`TestCase`\ -derived class :class:`SampleTestCase` with three test
methods (:meth:`test_one`, :meth:`test_two`, and :meth:`test_three`), the methods (:meth:`test_one`, :meth:`test_two`, and :meth:`test_three`), the
specifier ``'SampleTests.SampleTestCase'`` would cause this method to return a specifier ``'SampleTests.SampleTestCase'`` would cause this method to
suite which will run all three test methods. Using the specifier return a suite which will run all three test methods. Using the specifier
``'SampleTests.SampleTestCase.test_two'`` would cause it to return a test suite ``'SampleTests.SampleTestCase.test_two'`` would cause it to return a test
which will run only the :meth:`test_two` test method. The specifier can refer suite which will run only the :meth:`test_two` test method. The specifier
to modules and packages which have not been imported; they will be imported as a can refer to modules and packages which have not been imported; they will
side-effect. be imported as a side-effect.
The method optionally resolves *name* relative to the given *module*. The method optionally resolves *name* relative to the given *module*.
...@@ -1196,6 +1286,7 @@ Loading and running tests ...@@ -1196,6 +1286,7 @@ Loading and running tests
Return a sorted sequence of method names found within *testCaseClass*; Return a sorted sequence of method names found within *testCaseClass*;
this should be a subclass of :class:`TestCase`. this should be a subclass of :class:`TestCase`.
The following attributes of a :class:`TestLoader` can be configured either by The following attributes of a :class:`TestLoader` can be configured either by
subclassing or assignment on an instance: subclassing or assignment on an instance:
...@@ -1286,14 +1377,14 @@ Loading and running tests ...@@ -1286,14 +1377,14 @@ Loading and running tests
.. method:: wasSuccessful() .. method:: wasSuccessful()
Return :const:`True` if all tests run so far have passed, otherwise returns Return ``True`` if all tests run so far have passed, otherwise returns
:const:`False`. ``False``.
.. method:: stop() .. method:: stop()
This method can be called to signal that the set of tests being run should This method can be called to signal that the set of tests being run should
be aborted by setting the :attr:`shouldStop` attribute to :const:`True`. be aborted by setting the :attr:`shouldStop` attribute to ``True``.
:class:`TestRunner` objects should respect this flag and return without :class:`TestRunner` objects should respect this flag and return without
running any additional tests. running any additional tests.
...@@ -1328,14 +1419,14 @@ Loading and running tests ...@@ -1328,14 +1419,14 @@ Loading and running tests
Called once before any tests are executed. Called once before any tests are executed.
.. versionadded:: 3.2 .. versionadded:: 3.1
.. method:: stopTestRun(test) .. method:: stopTestRun(test)
Called once before any tests are executed. Called once after all tests are executed.
.. versionadded:: 3.2 .. versionadded:: 3.1
.. method:: addError(test, err) .. method:: addError(test, err)
...@@ -1351,8 +1442,8 @@ Loading and running tests ...@@ -1351,8 +1442,8 @@ Loading and running tests
.. method:: addFailure(test, err) .. method:: addFailure(test, err)
Called when the test case *test* signals a failure. *err* is a tuple of the form Called when the test case *test* signals a failure. *err* is a tuple of
returned by :func:`sys.exc_info`: ``(type, value, traceback)``. the form returned by :func:`sys.exc_info`: ``(type, value, traceback)``.
The default implementation appends a tuple ``(test, formatted_err)`` to The default implementation appends a tuple ``(test, formatted_err)`` to
the instance's :attr:`failures` attribute, where *formatted_err* is a the instance's :attr:`failures` attribute, where *formatted_err* is a
...@@ -1423,6 +1514,7 @@ Loading and running tests ...@@ -1423,6 +1514,7 @@ Loading and running tests
if __name__ == '__main__': if __name__ == '__main__':
unittest.main() unittest.main()
The *testRunner* argument can either be a test runner class or an already The *testRunner* argument can either be a test runner class or an already
created instance of it. By default ``main`` calls :func:`sys.exit` with created instance of it. By default ``main`` calls :func:`sys.exit` with
an exit code indicating success or failure of the tests run. an exit code indicating success or failure of the tests run.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment