rest25/library/unittest.rst => rest262/library/unittest.rst
75
76   Module :mod:`doctest`
77      Another test-support module with a very different flavor.
78
79   `Simple Smalltalk Testing: With Patterns <http://www.XProgramming.com/testfram.htm>`_
80      Kent Beck's original paper on testing frameworks using the pattern shared by
81      :mod:`unittest`.
82
n83+   `Nose <http://code.google.com/p/python-nose/>`_ and `py.test <http://pytest.org>`_
84+      Third-party unittest frameworks with a lighter-weight syntax
85+      for writing tests.  For example, ``assert func(10) == 42``.
83
n87+   `python-mock <http://python-mock.sourceforge.net/>`_ and `minimock <http://blog.ianbicking.org/minimock.html>`_
88+      Tools for creating mock test objects (objects simulating external resources).
89+ 
84-.. _minimal-example:
90+.. _unittest-minimal-example:
85
86Basic example
87-------------
88
89The :mod:`unittest` module provides a rich set of tools for constructing and
90running tests.  This section demonstrates that a small subset of the tools
91suffice to meet the needs of most users.
92
482
483.. class:: TextTestRunner([stream[, descriptions[, verbosity]]])
484
485   A basic test runner implementation which prints results on standard error.  It
486   has a few configurable parameters, but is essentially very simple.  Graphical
487   applications which run test suites should provide alternate implementations.
488
489
n490-.. function:: main([module[, defaultTest[, argv[, testRunner[, testRunner]]]]])
n496+.. function:: main([module[, defaultTest[, argv[, testRunner[, testLoader]]]]])
491
492   A command-line program that runs a set of tests; this is primarily for making
493   test modules conveniently executable.  The simplest use for this function is to
494   include the following line at the end of a test script::
495
496      if __name__ == '__main__':
497          unittest.main()
n504+ 
505+   The *testRunner* argument can either be a test runner class or an already
506+   created instance of it.
498
499In some cases, the existing tests may have been written using the :mod:`doctest`
500module.  If so, that module provides a  :class:`DocTestSuite` class that can
501automatically build :class:`unittest.TestSuite` instances from the existing
502:mod:`doctest`\ -based tests.
503
504.. versionadded:: 2.3
505
556   the test to be propagated to the caller, and can be used to support running
557   tests under a debugger.
558
559The test code can use any of the following methods to check for and report
560failures.
561
562
563.. method:: TestCase.assert_(expr[, msg])
n564-            XXX Class.failUnless(expr[, msg])
n573+            TestCase.failUnless(expr[, msg])
574+            TestCase.assertTrue(expr[, msg])
565
566   Signal a test failure if *expr* is false; the explanation for the error will be
567   *msg* if given, otherwise it will be :const:`None`.
568
569
570.. method:: TestCase.assertEqual(first, second[, msg])
n571-            XXX Class.failUnlessEqual(first, second[, msg])
n581+            TestCase.failUnlessEqual(first, second[, msg])
572
573   Test that *first* and *second* are equal.  If the values do not compare equal,
574   the test will fail with the explanation given by *msg*, or :const:`None`.  Note
575   that using :meth:`failUnlessEqual` improves upon doing the comparison as the
576   first parameter to :meth:`failUnless`:  the default value for *msg* can be
577   computed to include representations of both *first* and *second*.
578
579
580.. method:: TestCase.assertNotEqual(first, second[, msg])
n581-            XXX Class.failIfEqual(first, second[, msg])
n591+            TestCase.failIfEqual(first, second[, msg])
582
583   Test that *first* and *second* are not equal.  If the values do compare equal,
584   the test will fail with the explanation given by *msg*, or :const:`None`.  Note
585   that using :meth:`failIfEqual` improves upon doing the comparison as the first
586   parameter to :meth:`failUnless` is that the default value for *msg* can be
587   computed to include representations of both *first* and *second*.
588
589
590.. method:: TestCase.assertAlmostEqual(first, second[, places[, msg]])
n591-            XXX Class.failUnlessAlmostEqual(first, second[, places[, msg]])
n601+            TestCase.failUnlessAlmostEqual(first, second[, places[, msg]])
592
593   Test that *first* and *second* are approximately equal by computing the
n594-   difference, rounding to the given number of *places*, and comparing to zero.
n604+   difference, rounding to the given number of decimal *places* (default 7),
605+   and comparing to zero.
595   Note that comparing a given number of decimal places is not the same as
596   comparing a given number of significant digits. If the values do not compare
597   equal, the test will fail with the explanation given by *msg*, or :const:`None`.
598
599
600.. method:: TestCase.assertNotAlmostEqual(first, second[, places[, msg]])
n601-            XXX Class.failIfAlmostEqual(first, second[, places[, msg]])
n612+            TestCase.failIfAlmostEqual(first, second[, places[, msg]])
602
603   Test that *first* and *second* are not approximately equal by computing the
n604-   difference, rounding to the given number of *places*, and comparing to zero.
n615+   difference, rounding to the given number of decimal *places* (default 7),
616+   and comparing to zero.
605   Note that comparing a given number of decimal places is not the same as
606   comparing a given number of significant digits. If the values do not compare
607   equal, the test will fail with the explanation given by *msg*, or :const:`None`.
608
609
610.. method:: TestCase.assertRaises(exception, callable, ...)
n611-            XXX Class.failUnlessRaises(exception, callable, ...)
n623+            TestCase.failUnlessRaises(exception, callable, ...)
612
613   Test that an exception is raised when *callable* is called with any positional
614   or keyword arguments that are also passed to :meth:`assertRaises`.  The test
615   passes if *exception* is raised, is an error if another exception is raised, or
616   fails if no exception is raised.  To catch any of a group of exceptions, a tuple
617   containing the exception classes may be passed as *exception*.
618
619
620.. method:: TestCase.failIf(expr[, msg])
n633+            TestCase.assertFalse(expr[, msg])
621
622   The inverse of the :meth:`failUnless` method is the :meth:`failIf` method.  This
623   signals a test failure if *expr* is true, with *msg* or :const:`None` for the
624   error message.
625
626
627.. method:: TestCase.fail([msg])
628
805   The default implementation does nothing.
806
807
808.. method:: TestResult.addError(test, err)
809
810   Called when the test case *test* raises an unexpected exception *err* is a tuple
811   of the form returned by :func:`sys.exc_info`: ``(type, value, traceback)``.
812
n813-   The default implementation appends ``(test, err)`` to the instance's ``errors``
n826+   The default implementation appends a tuple ``(test, formatted_err)`` to the
814-   attribute.
827+   instance's ``errors`` attribute, where *formatted_err* is a formatted
828+   traceback derived from *err*.
815
816
817.. method:: TestResult.addFailure(test, err)
818
819   Called when the test case *test* signals a failure. *err* is a tuple of the form
820   returned by :func:`sys.exc_info`:  ``(type, value, traceback)``.
821
t822-   The default implementation appends ``(test, err)`` to the instance's
t836+   The default implementation appends a tuple ``(test, formatted_err)`` to the
823-   ``failures`` attribute.
837+   instance's ``failures`` attribute, where *formatted_err* is a formatted
838+   traceback derived from *err*.
824
825
826.. method:: TestResult.addSuccess(test)
827
828   Called when the test case *test* succeeds.
829
830   The default implementation does nothing.
831
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op