Ticket #13628: 13628.diff

File 13628.diff, 11.0 KB (added by timo, 4 years ago)

reorg of testing.txt as per Luke's recommendation

  • docs/topics/testing.txt

    diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt
    index 09640b7..8bea474 100644
    a b There are two primary ways to write tests with Django, corresponding to the 
    3535two test frameworks that ship in the Python standard library. The two
    3636frameworks are:
    3737
     38    * **Unit tests** -- tests that are expressed as methods on a Python class
     39      that subclasses ``unittest.TestCase``. For example::
     40
     41          import unittest
     42
     43          class MyFuncTestCase(unittest.TestCase):
     44              def testBasic(self):
     45                  a = ['larry', 'curly', 'moe']
     46                  self.assertEqual(my_func(a, 0), 'larry')
     47                  self.assertEqual(my_func(a, 1), 'curly')
     48
    3849    * **Doctests** -- tests that are embedded in your functions' docstrings and
    3950      are written in a way that emulates a session of the Python interactive
    4051      interpreter. For example::
    frameworks are: 
    4960              """
    5061              return a_list[idx]
    5162
    52     * **Unit tests** -- tests that are expressed as methods on a Python class
    53       that subclasses ``unittest.TestCase``. For example::
     63We'll discuss choosing the appropriate test framework later, however, most
     64experienced developers prefer unittest. You can also use any *other* Python
     65test frameworks, as we'll explain in a bit.
    5466
    55           import unittest
     67Writing unit tests
     68------------------
    5669
    57           class MyFuncTestCase(unittest.TestCase):
    58               def testBasic(self):
    59                   a = ['larry', 'curly', 'moe']
    60                   self.assertEqual(my_func(a, 0), 'larry')
    61                   self.assertEqual(my_func(a, 1), 'curly')
     70Django's unit tests use a Python standard library module: unittest_. This
     71module defines tests in class-based approach.
    6272
    63 You can choose the test framework you like, depending on which syntax you
    64 prefer, or you can mix and match, using one framework for some of your code and
    65 the other framework for other code. You can also use any *other* Python test
    66 frameworks, as we'll explain in a bit.
     73.. admonition:: unittest2
     74
     75    .. versionchanged:: 1.3
     76
     77    Python 2.7 introduced some major changes to the unittest library,
     78    adding some extremely useful features. To ensure that every Django
     79    project can benefit from these new features, Django ships with a
     80    copy of unittest2_, a copy of the Python 2.7 unittest library,
     81    backported for Python 2.4 compatibility.
     82
     83    To access this library, Django provides the
     84    ``django.utils.unittest`` module alias. If you are using Python
     85    2.7, or you have installed unittest2 locally, Django will map the
     86    alias to the installed version of the unittest library. Otherwise,
     87    Django will use it's own bundled version of unittest2.
     88
     89    To use this alias, simply use::
     90
     91        from django.utils import unittest
     92
     93    wherever you would have historically used::
     94
     95        import unittest
     96
     97    If you want to continue to use the base unittest libary, you can --
     98    you just won't get any of the nice new unittest2 features.
     99
     100.. _unittest2: http://pypi.python.org/pypi/unittest2
     101
     102For a given Django application, the test runner looks for unit tests in two
     103places:
     104
     105    * The ``models.py`` file. The test runner looks for any subclass of
     106      ``unittest.TestCase`` in this module.
     107
     108    * A file called ``tests.py`` in the application directory -- i.e., the
     109      directory that holds ``models.py``. Again, the test runner looks for any
     110      subclass of ``unittest.TestCase`` in this module.
     111
     112Here is an example ``unittest.TestCase`` subclass::
     113
     114    from django.utils import unittest
     115    from myapp.models import Animal
     116
     117    class AnimalTestCase(unittest.TestCase):
     118        def setUp(self):
     119            self.lion = Animal.objects.create(name="lion", sound="roar")
     120            self.cat = Animal.objects.create(name="cat", sound="meow")
     121
     122        def testSpeaking(self):
     123            self.assertEqual(self.lion.speak(), 'The lion says "roar"')
     124            self.assertEqual(self.cat.speak(), 'The cat says "meow"')
     125
     126When you :ref:`run your tests <running-tests>`, the default behavior of the
     127test utility is to find all the test cases (that is, subclasses of
     128``unittest.TestCase``) in ``models.py`` and ``tests.py``, automatically build a
     129test suite out of those test cases, and run that suite.
     130
     131There is a second way to define the test suite for a module: if you define a
     132function called ``suite()`` in either ``models.py`` or ``tests.py``, the
     133Django test runner will use that function to construct the test suite for that
     134module. This follows the `suggested organization`_ for unit tests. See the
     135Python documentation for more details on how to construct a complex test
     136suite.
     137
     138For more details about ``unittest``, see the `standard library unittest
     139documentation`_.
     140
     141.. _unittest: http://docs.python.org/library/unittest.html
     142.. _standard library unittest documentation: unittest_
     143.. _suggested organization: http://docs.python.org/library/unittest.html#organizing-tests
    67144
    68145Writing doctests
    69146----------------
    read Python's official documentation for the details. 
    91168    Because tests often make great documentation, putting tests directly in
    92169    your docstrings is an effective way to document *and* test your code.
    93170
    94 For a given Django application, the test runner looks for doctests in two
    95 places:
     171As with unit tests, for a given Django application, the test runner looks for
     172doctests in two places:
    96173
    97174    * The ``models.py`` file. You can define module-level doctests and/or a
    98175      doctest for individual models. It's common practice to put
    places: 
    103180      directory that holds ``models.py``. This file is a hook for any and all
    104181      doctests you want to write that aren't necessarily related to models.
    105182
    106 Here is an example model doctest::
     183This example doctest is equivalent to the example given in the unittest section
     184above::
    107185
    108186    # models.py
    109187
    documentation for doctest`_. 
    148226.. _doctest: http://docs.python.org/library/doctest.html
    149227.. _standard library documentation for doctest: doctest_
    150228
    151 Writing unit tests
    152 ------------------
    153 
    154 Like doctests, Django's unit tests use a Python standard library
    155 module: unittest_. This module uses a different way of defining tests,
    156 taking a class-based approach.
    157 
    158 .. admonition:: unittest2
    159 
    160     .. versionchanged:: 1.3
    161 
    162     Python 2.7 introduced some major changes to the unittest library,
    163     adding some extremely useful features. To ensure that every Django
    164     project can benefit from these new features, Django ships with a
    165     copy of unittest2_, a copy of the Python 2.7 unittest library,
    166     backported for Python 2.4 compatibility.
    167 
    168     To access this library, Django provides the
    169     ``django.utils.unittest`` module alias. If you are using Python
    170     2.7, or you have installed unittest2 locally, Django will map the
    171     alias to the installed version of the unittest library. Otherwise,
    172     Django will use it's own bundled version of unittest2.
    173 
    174     To use this alias, simply use::
    175 
    176         from django.utils import unittest
    177 
    178     wherever you would have historically used::
    179 
    180         import unittest
    181 
    182     If you want to continue to use the base unittest libary, you can --
    183     you just won't get any of the nice new unittest2 features.
    184 
    185 .. _unittest2: http://pypi.python.org/pypi/unittest2
    186 
    187 As with doctests, for a given Django application, the test runner looks for
    188 unit tests in two places:
    189 
    190     * The ``models.py`` file. The test runner looks for any subclass of
    191       ``unittest.TestCase`` in this module.
    192 
    193     * A file called ``tests.py`` in the application directory -- i.e., the
    194       directory that holds ``models.py``. Again, the test runner looks for any
    195       subclass of ``unittest.TestCase`` in this module.
    196 
    197 This example ``unittest.TestCase`` subclass is equivalent to the example given
    198 in the doctest section above::
    199 
    200     from django.utils import unittest
    201     from myapp.models import Animal
    202 
    203     class AnimalTestCase(unittest.TestCase):
    204         def setUp(self):
    205             self.lion = Animal.objects.create(name="lion", sound="roar")
    206             self.cat = Animal.objects.create(name="cat", sound="meow")
    207 
    208         def testSpeaking(self):
    209             self.assertEqual(self.lion.speak(), 'The lion says "roar"')
    210             self.assertEqual(self.cat.speak(), 'The cat says "meow"')
    211 
    212 When you :ref:`run your tests <running-tests>`, the default behavior of the
    213 test utility is to find all the test cases (that is, subclasses of
    214 ``unittest.TestCase``) in ``models.py`` and ``tests.py``, automatically build a
    215 test suite out of those test cases, and run that suite.
    216 
    217 There is a second way to define the test suite for a module: if you define a
    218 function called ``suite()`` in either ``models.py`` or ``tests.py``, the
    219 Django test runner will use that function to construct the test suite for that
    220 module. This follows the `suggested organization`_ for unit tests. See the
    221 Python documentation for more details on how to construct a complex test
    222 suite.
    223 
    224 For more details about ``unittest``, see the `standard library unittest
    225 documentation`_.
    226 
    227 .. _unittest: http://docs.python.org/library/unittest.html
    228 .. _standard library unittest documentation: unittest_
    229 .. _suggested organization: http://docs.python.org/library/unittest.html#organizing-tests
    230 
    231229
    232230Which should I use?
    233231-------------------
    you: 
    244242      more "pythonic". It's designed to make writing tests as easy as possible,
    245243      so it requires no overhead of writing classes or methods. You simply put
    246244      tests in docstrings. This has the added advantage of serving as
    247       documentation (and correct documentation, at that!).
    248 
    249       If you're just getting started with testing, using doctests will probably
    250       get you started faster.
     245      documentation (and correct documentation, at that!).  However, while
     246      doctests are good for some simple example code, they are not very good if
     247      you want to produce either high quality, comprehensive tests or high
     248      quality documentation. Test failures are often more difficult to debug
     249      with doctests than with unittests.
    251250
    252251    * The ``unittest`` framework will probably feel very familiar to developers
    253252      coming from Java. ``unittest`` is inspired by Java's JUnit, so you'll
    arguments at time of construction: 
    710709            ...       HTTP_X_REQUESTED_WITH='XMLHttpRequest')
    711710
    712711        ...will send the HTTP header ``HTTP_X_REQUESTED_WITH`` to the
    713         details view, which is a good way to test code paths that use the
     712        details view, which is a good way to test code paths that use the
    714713        :meth:`django.http.HttpRequest.is_ajax()` method.
    715714
    716715        If you already have the GET arguments in URL-encoded form, you can
    set up, execute and tear down the test suite. 
    17151714.. method:: DjangoTestSuiteRunner.suite_result(suite, result, **kwargs)
    17161715
    17171716    Computes and returns a return code based on a test suite, and the result
    1718         from that test suite.
     1717    from that test suite.
    17191718
    17201719
    17211720Testing utilities
Back to Top