[Python-checkins] (2.7): Backport from 3.x several improvements and fixes for unittest.rst. (original) (raw)

Thu Mar 10 22:01:25 CET 2011

          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`.
          failUnlessEqual(first, second[, msg])
 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`.
          failIfEqual(first, second[, msg])
 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`.
          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`.
          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`.
          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.
          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.
          assertIsNot(first, second, msg=None)
 Test that *first* and *second* evaluate (or don't evaluate) to the same object.

 .. versionadded:: 2.7
 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
 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
 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`.
          assertIsNotNone(expr, msg=None)
 Test that *expr* is (or is not) None.

 .. versionadded:: 2.7
 If specified, *msg* will be used as the error message on failure.
 Test that *first* is (or is not) in *second*.

 .. versionadded:: 2.7
 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.
          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
 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
 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
 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
          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
 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
          failUnlessRaises(exception[, callable, ...])
          assertRaises(exception)

 Test that an exception is raised when *callable* is called with any
 positional or keyword arguments that are also passed to
          assertRaisesRegexp(exception, regexp)

 Like :meth:`assertRaises` but also tests that *regexp* matches
 on the string representation of the raised exception.  *regexp* may be
 This signals a test failure if *expr* is not 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.
          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
 The inverse of the :meth:`assertIsNone` method.
 This signals a test failure if *expr* is 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
 This signals a test failure if *expr1* and *expr2* don't evaluate to the same
 object.
 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
 The inverse of the :meth:`assertIs` method.
 This signals a test failure if *expr1* and *expr2* evaluate to the same
 object.
 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
 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`).
 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
 The inverse of the :meth:`assertIsInstance` method.  This signals a test
 failure if *obj* is an instance of *cls*.
 .. deprecated:: 3.2
 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
          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`.
 Signals a test failure unconditionally, with *msg* or :const:`None` for
 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
 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
          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
 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
 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
 Signals a test failure unconditionally, with *msg* or ``None`` for
 the error message.
 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
 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
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
    the aliases listed in the second column
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
.. 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``.
 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.
A basic test runner implementation which prints results on standard error.  It
has a few configurable parameters, but is essentially very simple.  Graphical

[Python-checkins] (2.7): Backport from 3.x several improvements and fixes for unittest.rst. (original) (raw)

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>

@@ -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.

@@ -1074,68 +961,241 @@ .. versionadded:: 2.7 - .. method:: assertIsNone(expr[, msg])