[Python-checkins] (2.7): Backport from 3.x several improvements and fixes for unittest.rst.
ezio.melotti
python-checkins at python.org
Thu Mar 10 22:01:25 CET 2011
http://hg.python.org/cpython/rev/6e5b5d1b6714
changeset: 68355:6e5b5d1b6714
branch: 2.7
user: Ezio Melotti <ezio.melotti at gmail.com>
date: Thu Mar 10 23:00:48 2011 +0200
summary:
Backport from 3.x several improvements and fixes for unittest.rst.
files:
Doc/library/unittest.rst
diff --git a/Doc/library/unittest.rst b/Doc/library/unittest.rst
--- a/Doc/library/unittest.rst
+++ b/Doc/library/unittest.rst
@@ -8,9 +8,11 @@
.. sectionauthor:: Fred L. Drake, Jr. <fdrake at acm.org>
.. sectionauthor:: Raymond Hettinger <python at rcn.com>
-
.. versionadded:: 2.1
+(If you are already familiar with the basic concepts of testing, you might want
+to skip to :ref:`the list of assert methods <assert-methods>`.)
+
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
@@ -128,13 +130,13 @@
def test_choice(self):
element = random.choice(self.seq)
- self.assertTrue(element in self.seq)
+ self.assertIn(element, self.seq)
def test_sample(self):
with self.assertRaises(ValueError):
random.sample(self.seq, 20)
for element in random.sample(self.seq, 5):
- self.assertTrue(element in self.seq)
+ self.assertIn(element, self.seq)
if __name__ == '__main__':
unittest.main()
@@ -192,7 +194,7 @@
.. _unittest-command-line-interface:
-Command-Line Interface
+Command Line Interface
----------------------
The unittest module can be used from the command line to run tests from
@@ -482,8 +484,9 @@
``WidgetTestCase.test_resize``. :class:`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 the built-in :func:`cmp` function.
+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 :class:`TestSuite` instances
@@ -674,7 +677,7 @@
Test cases
~~~~~~~~~~
-.. class:: TestCase([methodName])
+.. class:: TestCase(methodName='runTest')
Instances of the :class:`TestCase` class represent the smallest testable units
in the :mod:`unittest` universe. This class is intended to be used as a base
@@ -755,10 +758,10 @@
.. versionadded:: 2.7
- .. method:: run([result])
+ .. method:: run(result=None)
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
used. The result object is not returned to :meth:`run`'s caller.
@@ -780,151 +783,101 @@
by the test to be propagated to the caller, and can be used to support
running tests under a debugger.
- The test code can use any of the following methods to check for and report
- failures.
-
-
- .. method:: assertTrue(expr[, msg])
- assert_(expr[, msg])
- failUnless(expr[, msg])
-
- Signal a test failure if *expr* is false; the explanation for the failure
- will be *msg* if given, otherwise it will be :const:`None`.
-
- .. deprecated:: 2.7
- :meth:`failUnless` and :meth:`assert_`; use :meth:`assertTrue`.
-
-
- .. method:: assertEqual(first, second[, msg])
- failUnlessEqual(first, second[, msg])
+ .. _assert-methods:
+
+ The :class:`TestCase` class provides a number of methods to check for and
+ report failures, such as:
+
+ +-----------------------------------------+-----------------------------+---------------+
+ | Method | Checks that | New in |
+ +=========================================+=============================+===============+
+ | :meth:`assertEqual(a, b) | ``a == b`` | |
+ | <TestCase.assertEqual>` | | |
+ +-----------------------------------------+-----------------------------+---------------+
+ | :meth:`assertNotEqual(a, b) | ``a != b`` | |
+ | <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`` | 2.7 |
+ | <TestCase.assertIs>` | | |
+ +-----------------------------------------+-----------------------------+---------------+
+ | :meth:`assertIsNot(a, b) | ``a is not b`` | 2.7 |
+ | <TestCase.assertIsNot>` | | |
+ +-----------------------------------------+-----------------------------+---------------+
+ | :meth:`assertIsNone(x) | ``x is None`` | 2.7 |
+ | <TestCase.assertIsNone>` | | |
+ +-----------------------------------------+-----------------------------+---------------+
+ | :meth:`assertIsNotNone(x) | ``x is not None`` | 2.7 |
+ | <TestCase.assertIsNotNone>` | | |
+ +-----------------------------------------+-----------------------------+---------------+
+ | :meth:`assertIn(a, b) | ``a in b`` | 2.7 |
+ | <TestCase.assertIn>` | | |
+ +-----------------------------------------+-----------------------------+---------------+
+ | :meth:`assertNotIn(a, b) | ``a not in b`` | 2.7 |
+ | <TestCase.assertNotIn>` | | |
+ +-----------------------------------------+-----------------------------+---------------+
+ | :meth:`assertIsInstance(a, b) | ``isinstance(a, b)`` | 2.7 |
+ | <TestCase.assertIsInstance>` | | |
+ +-----------------------------------------+-----------------------------+---------------+
+ | :meth:`assertNotIsInstance(a, b) | ``not isinstance(a, b)`` | 2.7 |
+ | <TestCase.assertNotIsInstance>` | | |
+ +-----------------------------------------+-----------------------------+---------------+
+
+ All the assert methods (except :meth:`assertRaises`,
+ :meth:`assertRaisesRegexp`)
+ 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)
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
- :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*.
+ equal, the test will fail.
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 :meth:`addTypeEqualityFunc` the type specific equality
- function 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:: 2.7
Added the automatic calling of type specific equality function.
- .. deprecated:: 2.7
- :meth:`failUnlessEqual`; use :meth:`assertEqual`.
-
-
- .. method:: assertNotEqual(first, second[, msg])
- failIfEqual(first, second[, msg])
+
+ .. method:: assertNotEqual(first, second, msg=None)
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
- :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:: 2.7
- :meth:`failIfEqual`; use :meth:`assertNotEqual`.
-
-
- .. method:: assertAlmostEqual(first, second[, places[, msg[, delta]]])
- failUnlessAlmostEqual(first, second[, places[, msg[, delta]]])
-
- 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
- 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`.
-
- If *delta* is supplied instead of *places* then the difference
- between *first* and *second* must be less than *delta*.
-
- Supplying both *delta* and *places* raises a ``TypeError``.
-
- .. versionchanged:: 2.7
- Objects that compare equal are automatically almost equal.
- Added the ``delta`` keyword argument.
-
- .. deprecated:: 2.7
- :meth:`failUnlessAlmostEqual`; use :meth:`assertAlmostEqual`.
-
-
- .. method:: assertNotAlmostEqual(first, second[, places[, msg[, delta]]])
- failIfAlmostEqual(first, second[, places[, msg[, delta]]])
-
- Test that *first* and *second* are not 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
- 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`.
-
- If *delta* is supplied instead of *places* then the difference
- between *first* and *second* must be more than *delta*.
-
- Supplying both *delta* and *places* raises a ``TypeError``.
-
- .. versionchanged:: 2.7
- Objects that compare equal automatically fail.
- Added the ``delta`` keyword argument.
-
- .. deprecated:: 2.7
- :meth:`failIfAlmostEqual`; use :meth:`assertNotAlmostEqual`.
-
-
- .. method:: assertGreater(first, second, msg=None)
- assertGreaterEqual(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)
- AssertionError: "3" unexpectedly not greater than or equal to "4"
+ equal, the test will fail.
+
+ .. method:: assertTrue(expr, msg=None)
+ assertFalse(expr, msg=None)
+
+ Test that *expr* is true (or false).
+
+ Note that this is equivalent to ``bool(expr) is True`` and not to ``expr
+ 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.
+
+
+ .. method:: assertIs(first, second, msg=None)
+ assertIsNot(first, second, msg=None)
+
+ Test that *first* and *second* evaluate (or don't evaluate) to the same object.
.. versionadded:: 2.7
- .. method:: assertMultiLineEqual(self, 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 :meth:`assertEqual`.
-
- If specified, *msg* will be used as the error message on failure.
-
- .. versionadded:: 2.7
-
-
- .. method:: assertRegexpMatches(text, regexp, msg=None)
-
- Verifies that a *regexp* search matches *text*. Fails with an error
- message including the pattern and the *text*. *regexp* may be
- a regular expression object or a string containing a regular expression
- suitable for use by :func:`re.search`.
-
- .. versionadded:: 2.7
-
-
- .. method:: 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 :func:`re.search`.
+ .. method:: assertIsNone(expr, msg=None)
+ assertIsNotNone(expr, msg=None)
+
+ Test that *expr* is (or is not) None.
.. versionadded:: 2.7
@@ -932,99 +885,35 @@
.. method:: assertIn(first, second, msg=None)
assertNotIn(first, second, msg=None)
- 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.
+ Test that *first* is (or is not) in *second*.
.. versionadded:: 2.7
- .. method:: 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.
-
- If specified, *msg* will be used as the error message on failure.
+ .. method:: assertIsInstance(obj, cls, msg=None)
+ assertNotIsInstance(obj, cls, msg=None)
+
+ Test that *obj* is (or is not) an instance of *cls* (which can be a
+ class or a tuple of classes, as supported by :func:`isinstance`).
.. versionadded:: 2.7
- .. method:: assertSetEqual(set1, set2, 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`.
-
- Fails if either of *set1* or *set2* does not have a :meth:`set.difference`
- method.
-
- If specified, *msg* will be used as the error message on failure.
-
- .. versionadded:: 2.7
-
-
- .. method:: assertDictEqual(expected, actual, msg=None)
-
- Test that two dictionaries are equal. If not, an error message is
- constructed that shows the differences in the dictionaries. This
- method will be used by default to compare dictionaries in
- calls to :meth:`assertEqual`.
-
- If specified, *msg* will be used as the error message on failure.
-
- .. versionadded:: 2.7
-
-
- .. method:: 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.
-
- If specified, *msg* will be used as the error message on failure.
-
- .. versionadded:: 2.7
-
-
- .. method:: assertListEqual(list1, list2, msg=None)
- assertTupleEqual(tuple1, tuple2, msg=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`.
-
- If specified, *msg* will be used as the error message on failure.
-
- .. versionadded:: 2.7
-
-
- .. method:: 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.
-
- If specified, *msg* will be used as the error message on failure.
-
- This method is used to implement :meth:`assertListEqual` and
- :meth:`assertTupleEqual`.
-
- .. versionadded:: 2.7
-
-
- .. method:: assertRaises(exception[, callable, ...])
- failUnlessRaises(exception[, callable, ...])
+ It is also possible to check that exceptions and warnings are raised using
+ the following methods:
+
+ +---------------------------------------------------------+--------------------------------------+------------+
+ | 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` | 2.7 |
+ | <TestCase.assertRaisesRegexp>` | and the message matches `re` | |
+ +---------------------------------------------------------+--------------------------------------+------------+
+
+ .. method:: assertRaises(exception, callable, *args, **kwds)
+ assertRaises(exception)
Test that an exception is raised when *callable* is called with any
positional or keyword arguments that are also passed to
@@ -1033,8 +922,8 @@
To catch any of a group of exceptions, a tuple containing the exception
classes may be passed as *exception*.
- If *callable* is omitted or None, returns a context manager so that the
- code under test can be written inline rather than as a function::
+ 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()
@@ -1052,11 +941,9 @@
.. versionchanged:: 2.7
Added the ability to use :meth:`assertRaises` as a context manager.
- .. deprecated:: 2.7
- :meth:`failUnlessRaises`; use :meth:`assertRaises`.
-
-
- .. method:: assertRaisesRegexp(exception, regexp[, callable, ...])
+
+ .. method:: assertRaisesRegexp(exception, regexp, callable, *args, **kwds)
+ assertRaisesRegexp(exception, regexp)
Like :meth:`assertRaises` but also tests that *regexp* matches
on the string representation of the raised exception. *regexp* may be
@@ -1074,68 +961,241 @@
.. versionadded:: 2.7
- .. method:: assertIsNone(expr[, msg])
-
- This signals a test failure if *expr* is not None.
+
+ 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`` | 2.7 |
+ | <TestCase.assertGreater>` | | |
+ +---------------------------------------+--------------------------------+--------------+
+ | :meth:`assertGreaterEqual(a, b) | ``a >= b`` | 2.7 |
+ | <TestCase.assertGreaterEqual>` | | |
+ +---------------------------------------+--------------------------------+--------------+
+ | :meth:`assertLess(a, b) | ``a < b`` | 2.7 |
+ | <TestCase.assertLess>` | | |
+ +---------------------------------------+--------------------------------+--------------+
+ | :meth:`assertLessEqual(a, b) | ``a <= b`` | 2.7 |
+ | <TestCase.assertLessEqual>` | | |
+ +---------------------------------------+--------------------------------+--------------+
+ | :meth:`assertRegexpMatches(s, re) | ``regex.search(s)`` | 2.7 |
+ | <TestCase.assertRegexpMatches>` | | |
+ +---------------------------------------+--------------------------------+--------------+
+ | :meth:`assertNotRegexpMatches(s, re) | ``not regex.search(s)`` | 2.7 |
+ | <TestCase.assertNotRegexpMatches>` | | |
+ +---------------------------------------+--------------------------------+--------------+
+ | :meth:`assertItemsEqual(a, b) | sorted(a) == sorted(b) and | 2.7 |
+ | <TestCase.assertItemsEqual>` | works with unhashable objs | |
+ +---------------------------------------+--------------------------------+--------------+
+ | :meth:`assertDictContainsSubset(a, b) | all the key/value pairs | 2.7 |
+ | <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``.
+
+ .. versionchanged:: 2.7
+ :meth:`assertAlmostEqual` automatically considers almost equal objects
+ that compare equal. :meth:`assertNotAlmostEqual` automatically fails
+ if the objects compare equal. Added the *delta* keyword argument.
+
+
+
+ .. method:: assertGreater(first, second, msg=None)
+ assertGreaterEqual(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::
+
+ >>> self.assertGreaterEqual(3, 4)
+ AssertionError: "3" unexpectedly not greater than or equal to "4"
.. versionadded:: 2.7
- .. method:: assertIsNotNone(expr[, msg])
-
- The inverse of the :meth:`assertIsNone` method.
- This signals a test failure if *expr* is None.
+ .. method:: 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 :func:`re.search`.
.. versionadded:: 2.7
- .. method:: assertIs(expr1, expr2[, msg])
-
- This signals a test failure if *expr1* and *expr2* don't evaluate to the same
- object.
+ .. method:: 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 :func:`re.search`.
.. versionadded:: 2.7
- .. method:: assertIsNot(expr1, expr2[, msg])
-
- The inverse of the :meth:`assertIs` method.
- This signals a test failure if *expr1* and *expr2* evaluate to the same
- object.
+ .. method:: 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.
.. versionadded:: 2.7
- .. method:: assertIsInstance(obj, cls[, msg])
-
- This signals a test failure if *obj* is not an instance of *cls* (which
- can be a class or a tuple of classes, as supported by :func:`isinstance`).
+ .. method:: 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.
.. versionadded:: 2.7
-
-
- .. method:: assertNotIsInstance(obj, cls[, msg])
-
- The inverse of the :meth:`assertIsInstance` method. This signals a test
- failure if *obj* is an instance of *cls*.
+ .. deprecated:: 3.2
+
+
+
+ .. _type-specific-methods:
+
+ The :meth:`assertEqual` method dispatches the equality check for objects of
+ the same type to different type-specific methods. These methods are already
+ implemented for most of the built-in types, but it's also possible to
+ register new methods using :meth:`addTypeEqualityFunc`:
+
+ .. method:: addTypeEqualityFunc(typeobj, function)
+
+ Registers a type-specific method called by :meth:`assertEqual` to check
+ 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:: 2.7
-
- .. method:: assertFalse(expr[, msg])
- failIf(expr[, msg])
-
- The inverse of the :meth:`assertTrue` method is the :meth:`assertFalse` method.
- This signals a test failure if *expr* is true, with *msg* or :const:`None`
- for the error message.
-
- .. deprecated:: 2.7
- :meth:`failIf`; use :meth:`assertFalse`.
-
-
- .. method:: fail([msg])
-
- Signals a test failure unconditionally, with *msg* or :const:`None` for
+ 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 | 2.7 |
+ | <TestCase.assertMultiLineEqual>` | | |
+ +-----------------------------------------+-----------------------------+--------------+
+ | :meth:`assertSequenceEqual(a, b) | sequences | 2.7 |
+ | <TestCase.assertSequenceEqual>` | | |
+ +-----------------------------------------+-----------------------------+--------------+
+ | :meth:`assertListEqual(a, b) | lists | 2.7 |
+ | <TestCase.assertListEqual>` | | |
+ +-----------------------------------------+-----------------------------+--------------+
+ | :meth:`assertTupleEqual(a, b) | tuples | 2.7 |
+ | <TestCase.assertTupleEqual>` | | |
+ +-----------------------------------------+-----------------------------+--------------+
+ | :meth:`assertSetEqual(a, b) | sets or frozensets | 2.7 |
+ | <TestCase.assertSetEqual>` | | |
+ +-----------------------------------------+-----------------------------+--------------+
+ | :meth:`assertDictEqual(a, b) | dicts | 2.7 |
+ | <TestCase.assertDictEqual>` | | |
+ +-----------------------------------------+-----------------------------+--------------+
+
+
+
+ .. method:: 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 strings with :meth:`assertEqual`.
+
+ .. versionadded:: 2.7
+
+
+ .. method:: 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.
+
+ This method is not called directly by :meth:`assertEqual`, but
+ it's used to implement :meth:`assertListEqual` and
+ :meth:`assertTupleEqual`.
+
+ .. versionadded:: 2.7
+
+
+ .. method:: assertListEqual(list1, list2, msg=None)
+ assertTupleEqual(tuple1, tuple2, msg=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:: 2.7
+
+
+ .. method:: assertSetEqual(set1, set2, 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`.
+
+ Fails if either of *set1* or *set2* does not have a :meth:`set.difference`
+ method.
+
+ .. versionadded:: 2.7
+
+
+ .. method:: assertDictEqual(expected, actual, msg=None)
+
+ Test that two dictionaries are equal. If not, an error message is
+ constructed that shows the differences in the dictionaries. This
+ method will be used by default to compare dictionaries in
+ calls to :meth:`assertEqual`.
+
+ .. versionadded:: 2.7
+
+
+
+ .. _other-methods-and-attrs:
+
+ Finally the :class:`TestCase` provides the following methods and attributes:
+
+
+ .. method:: fail(msg=None)
+
+ Signals a test failure unconditionally, with *msg* or ``None`` for
the error message.
@@ -1150,18 +1210,19 @@
.. attribute:: 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 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
+ If set to ``True`` then any explicit failure message you pass in to the
+ :ref:`assert methods <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
+ 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
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 or False before calling the assert methods.
+ instance attribute to ``True`` or ``False`` before calling the assert methods.
.. versionadded:: 2.7
@@ -1210,30 +1271,14 @@
.. 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
returns the first line of the test method's docstring, if available,
or :const:`None`.
- .. 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:: 2.7
-
-
- .. method:: addCleanup(function[, *args[, **kwargs]])
+
+ .. method:: addCleanup(function, *args, **kwargs)
Add a function to be called after :meth:`tearDown` to cleanup resources
used during the test. Functions will be called in reverse order to the
@@ -1263,7 +1308,7 @@
.. versionadded:: 2.7
-.. class:: FunctionTestCase(testFunc[, setUp[, tearDown[, description]]])
+.. class:: FunctionTestCase(testFunc, setUp=None, tearDown=None, description=None)
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
@@ -1272,12 +1317,36 @@
: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:: 2.7
+ the aliases listed in the second column
+
+
+
.. _testsuite-objects:
Grouping tests
~~~~~~~~~~~~~~
-.. class:: TestSuite([tests])
+.. class:: TestSuite(tests=())
This class represents an aggregation of individual tests cases and test suites.
The class presents the interface needed by the test runner to allow it to be run
@@ -1391,7 +1460,7 @@
Support for ``load_tests`` added.
- .. method:: loadTestsFromName(name[, module])
+ .. method:: loadTestsFromName(name, module=None)
Return a suite of all tests cases given a string specifier.
@@ -1416,7 +1485,7 @@
The method optionally resolves *name* relative to the given *module*.
- .. method:: loadTestsFromNames(names[, module])
+ .. method:: loadTestsFromNames(names, module=None)
Similar to :meth:`loadTestsFromName`, but takes a sequence of names rather
than a single name. The return value is a test suite which supports all
@@ -1578,14 +1647,14 @@
.. method:: wasSuccessful()
- Return :const:`True` if all tests run so far have passed, otherwise returns
- :const:`False`.
+ Return ``True`` if all tests run so far have passed, otherwise returns
+ ``False``.
.. method:: stop()
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
running any additional tests.
@@ -1694,7 +1763,7 @@
instead of repeatedly creating new instances.
-.. class:: TextTestRunner([stream[, descriptions[, verbosity], [resultclass]]])
+.. class:: TextTestRunner(stream=sys.stderr, descriptions=True, verbosity=1)
A basic test runner implementation which prints results on standard error. It
has a few configurable parameters, but is essentially very simple. Graphical
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list