Commits

Antoine Pitrou  committed d1e6a48 Merge

Remove cruft and circumvolutions from the unittest docs.
(I would have preferred to post this for review but the bug tracker is pretty much dead at the moment)

  • Participants
  • Parent commits 97aabff, 0a2e8e1

Comments (0)

Files changed (1)

File Doc/library/unittest.rst

 (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
-facto standard unit testing framework for its respective language.
-
-:mod:`unittest` supports test automation, sharing of setup and shutdown code for
-tests, aggregation of tests into collections, and independence of the tests from
-the reporting framework.  The :mod:`unittest` module provides classes that make
-it easy to support these qualities for a set of tests.
-
-To achieve this, :mod:`unittest` supports some important concepts:
+The :mod:`unittest` unit testing framework was originally inspired by JUnit
+and has a similar flavor as major unit testing frameworks in other
+languages.  It supports test automation, sharing of setup and shutdown code
+for tests, aggregation of tests into collections, and independence of the
+tests from the reporting framework.
+
+To achieve this, :mod:`unittest` supports some important concepts in an
+object-oriented way:
 
 test fixture
    A :dfn:`test fixture` represents the preparation needed to perform one or more
    process.
 
 test case
-   A :dfn:`test case` is the smallest unit of testing.  It checks for a specific
+   A :dfn:`test case` is the individual unit of testing.  It checks for a specific
    response to a particular set of inputs.  :mod:`unittest` provides a base class,
    :class:`TestCase`, which may be used to create new test cases.
 
    a textual interface, or return a special value to indicate the results of
    executing the tests.
 
-The test case and test fixture concepts are supported through the
-:class:`TestCase` and :class:`FunctionTestCase` classes; the former should be
-used when creating new tests, and the latter can be used when integrating
-existing test code with a :mod:`unittest`\ -driven framework. When building test
-fixtures using :class:`TestCase`, the :meth:`~TestCase.setUp` and
-:meth:`~TestCase.tearDown` methods can be overridden to provide initialization
-and cleanup for the fixture.  With :class:`FunctionTestCase`, existing functions
-can be passed to the constructor for these purposes.  When the test is run, the
-fixture initialization is run first; if it succeeds, the cleanup method is run
-after the test has been executed, regardless of the outcome of the test.  Each
-instance of the :class:`TestCase` will only be used to run a single test method,
-so a new fixture is created for each test.
-
-Test suites are implemented by the :class:`TestSuite` class.  This class allows
-individual tests and test suites to be aggregated; when the suite is executed,
-all tests added directly to the suite and in "child" test suites are run.
-
-A test runner is an object that provides a single method,
-:meth:`~TestRunner.run`, which accepts a :class:`TestCase` or :class:`TestSuite`
-object as a parameter, and returns a result object.  The class
-:class:`TestResult` is provided for use as the result object. :mod:`unittest`
-provides the :class:`TextTestRunner` as an example test runner which reports
-test results on the standard error stream by default.  Alternate runners can be
-implemented for other environments (such as graphical environments) without any
-need to derive from a specific class.
-
 
 .. seealso::
 
    Module :mod:`doctest`
       Another test-support module with a very different flavor.
 
-   `unittest2: A backport of new unittest features for Python 2.4-2.6 <http://pypi.python.org/pypi/unittest2>`_
-      Many new features were added to unittest in Python 2.7, including test
-      discovery. unittest2 allows you to use these features with earlier
-      versions of Python.
-
    `Simple Smalltalk Testing: With Patterns <http://www.XProgramming.com/testfram.htm>`_
       Kent Beck's original paper on testing frameworks using the pattern shared
       by :mod:`unittest`.
       Third-party unittest frameworks with a lighter-weight syntax for writing
       tests.  For example, ``assert func(10) == 42``.
 
-   `The Python Testing Tools Taxonomy <http://pycheesecake.org/wiki/PythonTestingToolsTaxonomy>`_
+   `The Python Testing Tools Taxonomy <http://wiki.python.org/moin/PythonTestingToolsTaxonomy>`_
       An extensive list of Python testing tools including functional testing
       frameworks and mock object libraries.
 
 
    OK
 
-Instead of :func:`unittest.main`, there are other ways to run the tests with a
-finer level of control, less terse output, and no requirement to be run from the
-command line.  For example, the last two lines may be replaced with::
-
-   suite = unittest.TestLoader().loadTestsFromTestCase(TestSequenceFunctions)
-   unittest.TextTestRunner(verbosity=2).run(suite)
-
-Running the revised script from the interpreter or another script produces the
-following output::
+Passing the ``-v`` option to your test script will instruct :func:`unittest.main`
+to enable a higher level of verbosity, and produce the following output::
 
    test_choice (__main__.TestSequenceFunctions) ... ok
    test_sample (__main__.TestSequenceFunctions) ... ok
 To make your own test cases you must write subclasses of
 :class:`TestCase` or use :class:`FunctionTestCase`.
 
-An instance of a :class:`TestCase`\ -derived class is an object that can
-completely run a single test method, together with optional set-up and tidy-up
-code.
-
 The testing code of a :class:`TestCase` instance should be entirely self
 contained, such that it can be run either in isolation or in arbitrary
 combination with any number of other test cases.
 
-The simplest :class:`TestCase` subclass will simply override the
-:meth:`~TestCase.runTest` method in order to perform specific testing code::
+The simplest :class:`TestCase` subclass will simply implement a test method
+(i.e. a method whose name starts with ``test``) in order to perform specific
+testing code::
 
    import unittest
 
    class DefaultWidgetSizeTestCase(unittest.TestCase):
-       def runTest(self):
+       def test_default_widget_size(self):
            widget = Widget('The widget')
-           self.assertEqual(widget.size(), (50, 50), 'incorrect default size')
+           self.assertEqual(widget.size(), (50, 50))
 
 Note that in order to test something, we use one of the :meth:`assert\*`
 methods provided by the :class:`TestCase` base class.  If the test fails, an
 exception will be raised, and :mod:`unittest` will identify the test case as a
-:dfn:`failure`.  Any other exceptions will be treated as :dfn:`errors`. This
-helps you identify where the problem is: :dfn:`failures` are caused by incorrect
-results - a 5 where you expected a 6. :dfn:`Errors` are caused by incorrect
-code - e.g., a :exc:`TypeError` caused by an incorrect function call.
-
-The way to run a test case will be described later.  For now, note that to
-construct an instance of such a test case, we call its constructor without
-arguments::
-
-   testCase = DefaultWidgetSizeTestCase()
-
-Now, such test cases can be numerous, and their set-up can be repetitive.  In
-the above case, constructing a :class:`Widget` in each of 100 Widget test case
-subclasses would mean unsightly duplication.
-
-Luckily, we can factor out such set-up code by implementing a method called
-:meth:`~TestCase.setUp`, which the testing framework will automatically call for
-us when we run the test::
+:dfn:`failure`.  Any other exceptions will be treated as :dfn:`errors`.
+
+Tests can be numerous, and their set-up can be repetitive.  Luckily, we
+can factor out set-up code by implementing a method called
+:meth:`~TestCase.setUp`, which the testing framework will automatically
+call for every single test we run::
 
    import unittest
 
        def setUp(self):
            self.widget = Widget('The widget')
 
-   class DefaultWidgetSizeTestCase(SimpleWidgetTestCase):
-       def runTest(self):
+       def test_default_widget_size(self):
            self.assertEqual(self.widget.size(), (50,50),
                             'incorrect default size')
 
-   class WidgetResizeTestCase(SimpleWidgetTestCase):
-       def runTest(self):
+       def test_widget_resize(self):
            self.widget.resize(100,150)
            self.assertEqual(self.widget.size(), (100,150),
                             'wrong size after resize')
 
+.. note::
+   The order in which the various tests will be run is determined
+   by sorting the test method names with respect to the built-in
+   ordering for strings.
+
 If the :meth:`~TestCase.setUp` method raises an exception while the test is
-running, the framework will consider the test to have suffered an error, and the
-:meth:`~TestCase.runTest` method will not be executed.
+running, the framework will consider the test to have suffered an error, and
+the test method will not be executed.
 
 Similarly, we can provide a :meth:`~TestCase.tearDown` method that tidies up
-after the :meth:`~TestCase.runTest` method has been run::
+after the test method has been run::
 
    import unittest
 
 
        def tearDown(self):
            self.widget.dispose()
-           self.widget = None
-
-If :meth:`~TestCase.setUp` succeeded, the :meth:`~TestCase.tearDown` method will
-be run whether :meth:`~TestCase.runTest` succeeded or not.
+
+If :meth:`~TestCase.setUp` succeeded, :meth:`~TestCase.tearDown` will be
+run whether the test method succeeded or not.
 
 Such a working environment for the testing code is called a :dfn:`fixture`.
 
-Often, many small test cases will use the same fixture.  In this case, we would
-end up subclassing :class:`SimpleWidgetTestCase` into many small one-method
-classes such as :class:`DefaultWidgetSizeTestCase`.  This is time-consuming and
-discouraging, so in the same vein as JUnit, :mod:`unittest` provides a simpler
-mechanism::
-
-   import unittest
-
-   class WidgetTestCase(unittest.TestCase):
-       def setUp(self):
-           self.widget = Widget('The widget')
-
-       def tearDown(self):
-           self.widget.dispose()
-           self.widget = None
-
-       def test_default_size(self):
-           self.assertEqual(self.widget.size(), (50,50),
-                            'incorrect default size')
-
-       def test_resize(self):
-           self.widget.resize(100,150)
-           self.assertEqual(self.widget.size(), (100,150),
-                            'wrong size after resize')
-
-Here we have not provided a :meth:`~TestCase.runTest` method, but have instead
-provided two different test methods.  Class instances will now each run one of
-the :meth:`test_\*` methods, with ``self.widget`` created and destroyed
-separately for each instance.  When creating an instance we must specify the
-test method it is to run.  We do this by passing the method name in the
-constructor::
-
-   defaultSizeTestCase = WidgetTestCase('test_default_size')
-   resizeTestCase = WidgetTestCase('test_resize')
-
 Test case instances are grouped together according to the features they test.
 :mod:`unittest` provides a mechanism for this: the :dfn:`test suite`,
-represented by :mod:`unittest`'s :class:`TestSuite` class::
-
-   widgetTestSuite = unittest.TestSuite()
-   widgetTestSuite.addTest(WidgetTestCase('test_default_size'))
-   widgetTestSuite.addTest(WidgetTestCase('test_resize'))
-
-For the ease of running tests, as we will see later, it is a good idea to
-provide in each test module a callable object that returns a pre-built test
-suite::
+represented by :mod:`unittest`'s :class:`TestSuite` class.  In most cases,
+calling :func:`unittest.main` will do the right thing and collect all the
+module's test cases for you, and then execute them.
+
+However, should you want to customize the building of your test suite,
+you can do it yourself::
 
    def suite():
        suite = unittest.TestSuite()
        suite.addTest(WidgetTestCase('test_resize'))
        return suite
 
-or even::
-
-   def suite():
-       tests = ['test_default_size', 'test_resize']
-
-       return unittest.TestSuite(map(WidgetTestCase, tests))
-
-Since it is a common pattern to create a :class:`TestCase` subclass with many
-similarly named test functions, :mod:`unittest` provides a :class:`TestLoader`
-class that can be used to automate the process of creating a test suite and
-populating it with individual tests. For example, ::
-
-   suite = unittest.TestLoader().loadTestsFromTestCase(WidgetTestCase)
-
-will create a test suite that will run ``WidgetTestCase.test_default_size()`` and
-``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 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
-can be added to a :class:`TestSuite` just as :class:`TestCase` instances can be
-added to a :class:`TestSuite`::
-
-   suite1 = module1.TheTestSuite()
-   suite2 = module2.TheTestSuite()
-   alltests = unittest.TestSuite([suite1, suite2])
-
 You can place the definitions of test cases and test suites in the same modules
 as the code they are to test (such as :file:`widget.py`), but there are several
 advantages to placing the test code in a separate module, such as
        assert something.name is not None
        # ...
 
-one can create an equivalent test case instance as follows::
-
-   testcase = unittest.FunctionTestCase(testSomething)
-
-If there are additional set-up and tear-down methods that should be called as
-part of the test case's operation, they can also be provided like so::
+one can create an equivalent test case instance as follows, with optional
+set-up and tear-down methods::
 
    testcase = unittest.FunctionTestCase(testSomething,
                                         setUp=makeSomethingDB,
                                         tearDown=deleteSomethingDB)
 
-To make migrating existing test suites easier, :mod:`unittest` supports tests
-raising :exc:`AssertionError` to indicate test failure. However, it is
-recommended that you use the explicit :meth:`TestCase.fail\*` and
-:meth:`TestCase.assert\*` methods instead, as future versions of :mod:`unittest`
-may treat :exc:`AssertionError` differently.
-
 .. note::
 
    Even though :class:`FunctionTestCase` can be used to quickly convert an
 
 .. class:: TestCase(methodName='runTest')
 
-   Instances of the :class:`TestCase` class represent the smallest testable units
+   Instances of the :class:`TestCase` class represent the logical test units
    in the :mod:`unittest` universe.  This class is intended to be used as a base
    class, with specific tests being implemented by concrete subclasses.  This class
    implements the interface needed by the test runner to allow it to drive the
-   test, and methods that the test code can use to check for and report various
+   tests, and methods that the test code can use to check for and report various
    kinds of failure.
 
-   Each instance of :class:`TestCase` will run a single test method: the method
-   named *methodName*.  If you remember, we had an earlier example that went
-   something like this::
-
-      def suite():
-          suite = unittest.TestSuite()
-          suite.addTest(WidgetTestCase('test_default_size'))
-          suite.addTest(WidgetTestCase('test_resize'))
-          return suite
-
-   Here, we create two instances of :class:`WidgetTestCase`, each of which runs a
-   single test.
+   Each instance of :class:`TestCase` will run a single base method: the method
+   named *methodName*.  However, the standard implementation of the default
+   *methodName*, ``runTest()``, will run every method starting with ``test``
+   as an individual test, and count successes and failures accordingly.
+   Therefore, in most uses of :class:`TestCase`, you will neither change
+   the *methodName* nor reimplement the default ``runTest()`` method.
 
    .. versionchanged:: 3.2
-      :class:`TestCase` can be instantiated successfully without providing a method
-      name. This makes it easier to experiment with :class:`TestCase` from the
-      interactive interpreter.
-
-   *methodName* defaults to :meth:`runTest`.
+      :class:`TestCase` can be instantiated successfully without providing a
+      *methodName*. This makes it easier to experiment with :class:`TestCase`
+      from the interactive interpreter.
 
    :class:`TestCase` instances provide three groups of methods: one group used
    to run the test, another used by the test implementation to check conditions
 
    Methods in the first group (running the test) are:
 
-
    .. method:: setUp()
 
       Method called to prepare the test fixture.  This is called immediately
 
    .. method:: run(result=None)
 
-      Run the test, collecting the result into the test result object passed as
-      *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 returned to :meth:`run`'s caller.
+      Run the test, collecting the result into the :class:`TestResult` object
+      passed as *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 returned to :meth:`run`'s
+      caller.
 
       The same effect may be had by simply calling the :class:`TestCase`
       instance.