Index: Doc/library/unittest.rst =================================================================== --- Doc/library/unittest.rst (revision 85983) +++ Doc/library/unittest.rst (working copy) @@ -762,21 +762,52 @@ 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=None) - assert_(expr, msg=None) - failUnless(expr, msg=None) + The :class:`TestCase` class provides a number of methods to check for and + report failures, such as: - Signal a test failure if *expr* is false; the explanation for the failure - will be *msg* if given, otherwise it will be :const:`None`. + +-----------------------------------------+-----------------------------+---------------+ + | Method | Checks that | New in | + +=========================================+=============================+===============+ + | :meth:`assertEqual(a, b) | ``a == b`` | | + | ` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertNotEqual(a, b) | ``a != b`` | | + | ` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertTrue(x) | ``bool(x) is True`` | | + | ` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertFalse(x) | ``bool(x) is False`` | | + | ` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertIs(a, b) | ``a is b`` | 3.1 | + | ` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertIsNot(a, b) | ``a is not b`` | 3.1 | + | ` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertIsNone(x) | ``x is None`` | 3.1 | + | ` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertIsNotNone(x) | ``x is not None`` | 3.1 | + | ` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertIn(a, b) | ``a in b`` | 3.1 | + | ` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertNotIn(a, b) | ``a not in b`` | 3.1 | + | ` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertIsInstance(a, b) | ``isinstance(a, b)`` | 3.2 | + | ` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertNotIsInstance(a, b) | ``not isinstance(a, b)`` | 3.2 | + | ` | | | + +-----------------------------------------+-----------------------------+---------------+ - .. deprecated:: 3.1 - :meth:`failUnless` and :meth:`assert_`; use :meth:`assertTrue`. - .. method:: assertEqual(first, second, msg=None) failUnlessEqual(first, second, msg=None) @@ -818,101 +849,58 @@ :meth:`failIfEqual`; use :meth:`assertNotEqual`. - .. method:: assertAlmostEqual(first, second, *, places=7, msg=None, delta=None) - failUnlessAlmostEqual(first, second, *, places=7, msg=None, delta=None) + .. method:: assertTrue(expr, msg=None) + assert_(expr, msg=None) + failUnless(expr, msg=None) - 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. + Signal a test failure if *expr* is false; the explanation for the failure + will be *msg* if given, otherwise it will be :const:`None`. - 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:: 3.2 - Objects that compare equal are automatically almost equal. - Added the ``delta`` keyword argument. - .. deprecated:: 3.1 - :meth:`failUnlessAlmostEqual`; use :meth:`assertAlmostEqual`. + :meth:`failUnless` and :meth:`assert_`; use :meth:`assertTrue`. - .. method:: assertNotAlmostEqual(first, second, *, places=7, msg=None, delta=None) - failIfAlmostEqual(first, second, *, places=7, msg=None, delta=None) + .. method:: assertFalse(expr, msg=None) + failIf(expr, msg=None) - 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. + 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. - 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:: 3.2 - Objects that compare equal automatically fail. Added the ``delta`` - keyword argument. - .. deprecated:: 3.1 - :meth:`failIfAlmostEqual`; use :meth:`assertNotAlmostEqual`. + :meth:`failIf`; use :meth:`assertFalse`. - .. method:: assertGreater(first, second, msg=None) - assertGreaterEqual(first, second, msg=None) - assertLess(first, second, msg=None) - assertLessEqual(first, second, msg=None) + .. method:: assertIs(expr1, expr2, 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*:: + This signals a test failure if *expr1* and *expr2* don't evaluate to the same + object. - >>> self.assertGreaterEqual(3, 4) - AssertionError: "3" unexpectedly not greater than or equal to "4" - .. versionadded:: 3.1 - .. method:: assertMultiLineEqual(self, first, second, msg=None) + .. method:: assertIsNot(expr1, expr2, 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`. + The inverse of the :meth:`assertIs` method. + This signals a test failure if *expr1* and *expr2* evaluate to the same + object. - If specified, *msg* will be used as the error message on failure. - .. versionadded:: 3.1 - .. method:: assertRegexpMatches(text, regexp, msg=None) + .. method:: assertIsNone(expr, 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`. + This signals a test failure if *expr* is not None. .. versionadded:: 3.1 - .. method:: assertNotRegexpMatches(text, regexp, msg=None) + .. method:: assertIsNotNone(expr, 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`. + The inverse of the :meth:`assertIsNone` method. + This signals a test failure if *expr* is None. - .. versionadded:: 3.2 + .. versionadded:: 3.1 .. method:: assertIn(first, second, msg=None) @@ -926,107 +914,43 @@ .. versionadded:: 3.1 - .. method:: assertSameElements(actual, expected, msg=None) + .. method:: assertIsInstance(obj, cls[, msg]) - 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. + 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`). - 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.2 - If specified, *msg* will be used as the error message on failure. - .. versionadded:: 3.1 - .. deprecated:: 3.2 + .. method:: assertNotIsInstance(obj, cls[, msg]) + The inverse of the :meth:`assertIsInstance` method. This signals a test + failure if *obj* is an instance of *cls*. - .. 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. - .. versionadded:: 3.2 - .. 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`. + It is also possible to check that exceptions and warnings are raised using + the following methods: - 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. + +---------------------------------------------------------+--------------------------------------+------------+ + | Method | Checks that | New in | + +=========================================================+======================================+============+ + | :meth:`assertRaises(exc, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises `exc` | | + | ` | | | + +---------------------------------------------------------+--------------------------------------+------------+ + | :meth:`assertRaisesRegexp(exc, re, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises `exc` | 3.1 | + | ` | and the message matches `re` | | + +---------------------------------------------------------+--------------------------------------+------------+ + | :meth:`assertWarns(warn, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises `warn` | 3.2 | + | ` | | | + +---------------------------------------------------------+--------------------------------------+------------+ + | :meth:`assertWarnsRegexp(warn, re, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises `warn` | 3.2 | + | ` | and the message matches `re` | | + +---------------------------------------------------------+--------------------------------------+------------+ - .. versionadded:: 3.1 - - - .. 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:: 3.1 - - - .. 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:: 3.1 - - - .. 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:: 3.1 - - - .. 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:: 3.1 - - .. method:: assertRaises(exception, callable, *args, **kwds) failUnlessRaises(exception, callable, *args, **kwds) assertRaises(exception) @@ -1136,65 +1060,275 @@ .. versionadded:: 3.2 - .. method:: assertIsNone(expr, msg=None) - This signals a test failure if *expr* is not None. + There are also other methods used to perform more specific checks, such as: - .. versionadded:: 3.1 + +---------------------------------------+--------------------------------+--------------+ + | Method | Checks that | New in | + +=======================================+================================+==============+ + | :meth:`assertAlmostEqual(a, b) | ``round(a-b, 7) == 0`` | | + | ` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertNotAlmostEqual(a, b) | ``round(a-b, 7) != 0`` | | + | ` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertGreater(a, b) | ``a > b`` | 3.1 | + | ` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertGreaterEqual(a, b) | ``a >= b`` | 3.1 | + | ` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertLess(a, b) | ``a < b`` | 3.1 | + | ` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertLessEqual(a, b) | ``a <= b`` | 3.1 | + | ` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertRegexpMatches(s, re) | ``regex.search(s)`` | 3.1 | + | ` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertNotRegexpMatches(s, re) | ``not regex.search(s)`` | 3.2 | + | ` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertDictContainsSubset(a, b) | all the key/value pairs | 3.1 | + | ` | in `a` exist in `b` | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertItemsEqual(a, b) | `a` and `b` have the same | 3.2 | + | ` | elements in the same number, | | + | | regardless of their order | | + +---------------------------------------+--------------------------------+--------------+ - .. method:: assertIsNotNone(expr, msg=None) + .. method:: assertAlmostEqual(first, second, *, places=7, msg=None, delta=None) + failUnlessAlmostEqual(first, second, *, places=7, msg=None, delta=None) - The inverse of the :meth:`assertIsNone` method. - This signals a test failure if *expr* is None. + 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. - .. versionadded:: 3.1 + 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*. - .. method:: assertIs(expr1, expr2, msg=None) + Supplying both *delta* and *places* raises a ``TypeError``. - This signals a test failure if *expr1* and *expr2* don't evaluate to the same - object. + .. versionchanged:: 3.2 + Objects that compare equal are automatically almost equal. + Added the ``delta`` keyword argument. + .. deprecated:: 3.1 + :meth:`failUnlessAlmostEqual`; use :meth:`assertAlmostEqual`. + + + .. method:: assertNotAlmostEqual(first, second, *, places=7, msg=None, delta=None) + failIfAlmostEqual(first, second, *, places=7, msg=None, delta=None) + + 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:: 3.2 + Objects that compare equal automatically fail. Added the ``delta`` + keyword argument. + + .. deprecated:: 3.1 + :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" + .. versionadded:: 3.1 - .. method:: assertIsNot(expr1, expr2, msg=None) + .. method:: assertRegexpMatches(text, regexp, msg=None) - The inverse of the :meth:`assertIs` method. - This signals a test failure if *expr1* and *expr2* evaluate to the same - object. + 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:: 3.1 - .. method:: assertIsInstance(obj, cls[, msg]) + .. method:: assertNotRegexpMatches(text, regexp, msg=None) - 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`). + 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:: 3.2 - .. method:: assertNotIsInstance(obj, cls[, msg]) + .. method:: assertDictContainsSubset(expected, actual, msg=None) - The inverse of the :meth:`assertIsInstance` method. This signals a test - failure if *obj* is an instance of *cls*. + 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:: 3.1 + + + .. 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. + .. versionadded:: 3.2 - .. method:: assertFalse(expr, msg=None) - failIf(expr, msg=None) + .. method:: assertSameElements(actual, expected, msg=None) - 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. + 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. - .. deprecated:: 3.1 - :meth:`failIf`; use :meth:`assertFalse`. + 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`. + If specified, *msg* will be used as the error message on failure. + .. versionadded:: 3.1 + .. deprecated:: 3.2 + + + + The following methods are used automatically by :meth:`~TestCase.assertEqual` + and usually is not necessary to invoke them directly: + + +-----------------------------------------+-----------------------------+--------------+ + | Method | Used to compare | New in | + +=========================================+=============================+==============+ + | :meth:`assertMultiLineEqual(a, b) | strings | 3.1 | + | ` | | | + +-----------------------------------------+-----------------------------+--------------+ + | :meth:`assertSequenceEqual(a, b) | sequences | 3.1 | + | ` | | | + +-----------------------------------------+-----------------------------+--------------+ + | :meth:`assertListEqual(a, b) | lists | 3.1 | + | ` | | | + +-----------------------------------------+-----------------------------+--------------+ + | :meth:`assertTupleEqual(a, b) | tuples | 3.1 | + | ` | | | + +-----------------------------------------+-----------------------------+--------------+ + | :meth:`assertSetEqual(a, b) | sets or frozensets | 3.1 | + | ` | | | + +-----------------------------------------+-----------------------------+--------------+ + | :meth:`assertDictEqual(a, b) | dicts | 3.1 | + | ` | | | + +-----------------------------------------+-----------------------------+--------------+ + + + + .. 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 strings with :meth:`assertEqual`. + + If specified, *msg* will be used as the error message on failure. + + .. versionadded:: 3.1 + + + .. 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:: 3.1 + + + .. 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:: 3.1 + + + .. 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:: 3.1 + + + .. 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:: 3.1 + + + + Finally the :class:`TestCase` provides the following methods and attributes: + + .. method:: fail(msg=None) Signals a test failure unconditionally, with *msg* or :const:`None` for