[issue2578] additional unittest type equality methods

Doc/library/unittest.rst

 
 :mod:`unittest` --- Unit testing framework
 ==========================================
 
 .. module:: unittest
    :synopsis: Unit testing framework for Python.
 .. moduleauthor:: Steve Purcell <stephen_purcell@yahoo.com>
 .. sectionauthor:: Steve Purcell <stephen_purcell@yahoo.com>
 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
 .. sectionauthor:: Raymond Hettinger <python@rcn.com>
@@ skipping 590 matching lines @@
       Run the test without collecting the result.  This allows exceptions raised
       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:: assert_(expr[, msg])
                failUnless(expr[, msg])
                assertTrue(expr[, msg])

[GvR, 2009/03/31 15:01:06]

Make assertTrue the first/preferred/recommended spelling.

[gregory.p.smith, 2009/03/31 16:37:02]

On 2009/03/31 15:01:06, GvR wrote:
> Make assertTrue the first/preferred/recommended spelling.

Done.

 
       Signal a test failure if *expr* is false; the explanation for the error
       will be *msg* if given, otherwise it will be :const:`None`.
 
 
    .. method:: assertEqual(first, second[, msg])
+               assertEquals(first, second[, msg])
                failUnlessEqual(first, second[, msg])
 
       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:`failUnlessEqual` improves upon

[GvR, 2009/03/31 15:01:06]

failUnlessEqal -> assertEqual

[gregory.p.smith, 2009/03/31 16:37:02]

On 2009/03/31 15:01:06, GvR wrote:
> failUnlessEqal -> assertEqual

Done.

       doing the comparison as the first parameter to :meth:`failUnless`: the

[GvR, 2009/03/31 15:01:06]

failUnless -> assertTrue

(This kind of change may have to be done throughout.)

[gregory.p.smith, 2009/03/31 16:37:02]

On 2009/03/31 15:01:06, GvR wrote:
> failUnless -> assertTrue
> 
> (This kind of change may have to be done throughout.)

Done.

-      default value for *msg* can be computed to include representations of both
-      *first* and *second*.
+      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
+      list, tuple, dict, set, or frozenset or any type that a subclass
+      registers :meth:`addTypeEqualityFunc` the type specific equality function
+      will be called in order to generate a more useful default error message.
+
+      .. versionchanged:: 2.7
+         Added the automatic calling of type specific equality function.
 
 
    .. method:: assertNotEqual(first, second[, msg])
                failIfEqual(first, second[, msg])
 
       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:`failIfEqual` improves upon doing
       the comparison as the first parameter to :meth:`failUnless` is that the
       default value for *msg* can be computed to include representations of both
@@ skipping 17 matching lines @@
                failIfAlmostEqual(first, second[, places[, msg]])
 
       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`.
+
+
+   .. 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 the nice explanation
+      or with the explanation given by *msg*::
+
+         >>> self.assertGreaterEqual(3, 4)
+         AssertionError: "3" unexpectedly not greater than or equal to "4"
+
+      .. versionadded:: 2.7
+
+
+   .. method:: assertMultiLineEquals(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.
+
+      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:: assertIn(first, second, msg=None)
+               assertNotIn(first, second, msg=None)
+
+      Tests that *first* is or is not in *second* with a nice explanitory error
+      message as appropriate.
+
+      If specified *msg* will be used as the error message on failure.
+
+      .. versionadded:: 2.7
+
+
+   .. method:: assertSameElements(expected, actual, msg=None)
+
+      Test that sequence *expected* contains the same elements as *actual*.
+      When they don't an error message listing the differences between the
+      sequences will be generated.
+
+      If specified *msg* will be used as the error message on failure.
+
+      .. versionadded:: 2.7
+
+
+   .. method:: assertSetEquals(set1, set2, msg=None)
+
+      Tests that two sets are equal.  If not, an error message is constructed
+      that lists the differences between the sets.
+
+      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:: assertDictEquals(expected, actual, 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.
+
+      .. 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:: assertListEquals(list1, list2, msg=None)
+               assertTupleEquals(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.
+
+      If specified *msg* will be used as the error message on failure.
+
+      .. versionadded:: 2.7
+
+
+   .. method:: assertSequenceEquals(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:`assertListEquals` and
+      :meth:`assertTupleEquals`.
+
+      .. versionadded:: 2.7
 
 
    .. method:: assertRaises(exception[, callable, ...])
                failUnlessRaises(exception[, callable, ...])
 
       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 *callable* is omitted or None, returns a context manager so that the
       code under test can be written inline rather than as a function::
 
          with self.failUnlessRaises(some_error_class):
              do_something()
 
       .. versionchanged:: 2.7
          Added the ability to use :meth:`assertRaises` as a context manager.
+
+
+   .. method:: assertRaisesRegexp(exception, regexp[, callable, ...])
+
+      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')
+      
+      or::
+
+         with self.assertRaisesRegexp(ValueError, 'literal'):
+            int('XYZ')
+
+      .. versionadded:: 2.7
+
+
+   .. method:: assertIsNone(expr[, msg])
+
+      This signals a test failure if *expr* is not None.
+
+      .. versionadded:: 2.7
+
+
+   .. method:: assertIsNotNone(expr[, msg])
+
+      The inverse of the :meth:`assertIsNone` method.
+      This signals a test failure if *expr* is None.
+
+      .. versionadded:: 2.7
 
 
    .. method:: failIf(expr[, msg])
                assertFalse(expr[, msg])
 
       The inverse of the :meth:`failUnless` method is the :meth:`failIf` method.
       This signals a test failure if *expr* is true, with *msg* or :const:`None`
       for the error message.
 
 
@@ skipping 33 matching lines @@
 
 
    .. method:: id()
 
       Return a string identifying the specific test case.  This is usually the
       full name of the test method, including the module and class name.
 
 
    .. method:: shortDescription()
 
-      Returns a one-line description of the test, or :const:`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`.
+      Returns a description of the test, or :const:`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,
+      along with the method name.
+
+      .. versionchanged:: 2.7
+
+         In earlier versions this only returned the first line of the test
+         method's docstring, if available or the :const:`None`.  That led to
+         undesirable behavior of not printing the test name when someone was
+         thoughtful enough to write a docstring.
+
+
+   .. method:: addTypeEqualityFunc(typeobj, function)
+
+      Registers a type specific :meth:`assertEquals` equality checking
+      function to be called by :meth:`assertEquals` 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:`assertEquals` 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 by explaining the inequalities in detail.
+
+      .. versionadded:: 2.7
 
 
 .. class:: FunctionTestCase(testFunc[, setUp[, tearDown[, description]]])
 
    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
    test code can use to check and report errors. This is used to create test cases
    using legacy test code, allowing it to be integrated into a :mod:`unittest`\
    -based test framework.
 
@@ skipping 361 matching lines @@
 
    A command-line program that runs a set of tests; this is primarily for making
    test modules conveniently executable.  The simplest use for this function is to
    include the following line at the end of a test script::
 
       if __name__ == '__main__':
           unittest.main()
 
    The *testRunner* argument can either be a test runner class or an already
    created instance of it.