[1.9.x] Refs #26270 -- Reorganized TestCase docs.

Backport of 7a7e403325427642905a5b3e26931c2b8e92d4b1 from master

docs/topics/testing/tools.txt

@@ -626,13 +626,18 @@ Normal Python unit test classes extend a base class of
 
    Hierarchy of Django unit testing classes
 
+Converting a normal :class:`unittest.TestCase` to any of the subclasses is
+easy: change the base class of your test from ``unittest.TestCase`` to the
+subclass. All of the standard Python unit test functionality will be available,
+and it will be augmented with some useful additions as described in each
+section below.
+
 ``SimpleTestCase``
 ------------------
 
 .. class:: SimpleTestCase()
 
-A thin subclass of :class:`unittest.TestCase`, it extends it with some basic
+A subclass of :class:`unittest.TestCase` that adds this functionality:
-functionality like:
 
 * Some useful assertions like:
 
@@ -657,17 +662,8 @@ functionality like:
 * Using the :attr:`~SimpleTestCase.client` :class:`~django.test.Client`.
 * Custom test-time :attr:`URL maps <SimpleTestCase.urls>`.
 
-If you need any of the other more complex and heavyweight Django-specific
+If your tests make any database queries, use subclasses
-features like:
+:class:`~django.test.TransactionTestCase` or :class:`~django.test.TestCase`.
-
-* Testing or using the ORM.
-* Database :attr:`~TransactionTestCase.fixtures`.
-* Test :ref:`skipping based on database backend features <skipping-tests>`.
-* The remaining specialized :meth:`assert*
-  <TransactionTestCase.assertQuerysetEqual>` methods.
-
-then you should use :class:`~django.test.TransactionTestCase` or
-:class:`~django.test.TestCase` instead.
 
 .. attribute:: SimpleTestCase.allow_database_queries
 
@@ -680,8 +676,6 @@ then you should use :class:`~django.test.TransactionTestCase` or
     setting the ``allow_database_queries`` class attribute to ``True`` on
     your test class.
 
-``SimpleTestCase`` inherits from ``unittest.TestCase``.
-
 .. warning::
 
     ``SimpleTestCase`` and its subclasses (e.g. ``TestCase``, ...) rely on
@@ -715,12 +709,23 @@ then you should use :class:`~django.test.TransactionTestCase` or
 
 .. class:: TransactionTestCase()
 
-Django's ``TestCase`` class (described below) makes use of database transaction
+``TransactionTestCase`` inherits from :class:`~django.test.SimpleTestCase` to
-facilities to speed up the process of resetting the database to a known state
+add some database-specific features:
-at the beginning of each test. A consequence of this, however, is that some
+
-database behaviors cannot be tested within a Django ``TestCase`` class. For
+* Resetting the database to a known state at the beginning of each test to
-instance, you cannot test that a block of code is executing within a
+  ease testing and using the ORM.
-transaction, as is required when using
+* Database :attr:`~TransactionTestCase.fixtures`.
+* Test :ref:`skipping based on database backend features <skipping-tests>`.
+* The remaining specialized :meth:`assert*
+  <TransactionTestCase.assertQuerysetEqual>` methods.
+
+Django's :class:`TestCase` class is a more commonly used subclass of
+``TransactionTestCase`` that makes use of database transaction facilities
+to speed up the process of resetting the database to a known state at the
+beginning of each test. A consequence of this, however, is that some database
+behaviors cannot be tested within a Django ``TestCase`` class. For instance,
+you cannot test that a block of code is executing within a transaction, as is
+required when using
 :meth:`~django.db.models.query.QuerySet.select_for_update()`. In those cases,
 you should use ``TransactionTestCase``.
 
@@ -757,31 +762,23 @@ to test the effects of commit and rollback:
   this) you can set ``serialized_rollback = True`` inside the
   ``TestCase`` body.
 
-``TransactionTestCase`` inherits from :class:`~django.test.SimpleTestCase`.
-
 ``TestCase``
 ------------
 
 .. class:: TestCase()
 
-This class provides some additional capabilities that can be useful for testing
+This is the most common class to use for writing tests in Django. It inherits
-websites.
+from :class:`TransactionTestCase` (and by extension :class:`SimpleTestCase`).
+If your Django application doesn't use a database, use :class:`SimpleTestCase`.
 
-Converting a normal :class:`unittest.TestCase` to a Django :class:`TestCase` is
+The class:
-easy: Just change the base class of your test from ``'unittest.TestCase'`` to
-``'django.test.TestCase'``. All of the standard Python unit test functionality
-will continue to be available, but it will be augmented with some useful
-additions, including:
 
-* Automatic loading of fixtures.
+* Wraps the tests within two nested :func:`~django.db.transaction.atomic`
+  blocks: one for the whole class and one for each test. Therefore, if you want
+  to test some specific database transaction behavior, use
+  :class:`TransactionTestCase`.
 
-* Wraps the tests within two nested ``atomic`` blocks: one for the whole class
+It also provides an additional method:
-  and one for each test.
-
-* Creates a TestClient instance.
-
-* Django-specific assertions for testing for things like redirection and form
-  errors.
 
 .. classmethod:: TestCase.setUpTestData()
 
@@ -820,14 +817,6 @@ additions, including:
     modify them, you could reload them in the ``setUp()`` method with
     :meth:`~django.db.models.Model.refresh_from_db`, for example.
 
-.. warning::
-
-    If you want to test some specific database transaction behavior, you should
-    use ``TransactionTestCase``, as ``TestCase`` wraps test execution within an
-    :func:`~django.db.transaction.atomic()` block.
-
-``TestCase`` inherits from :class:`~django.test.TransactionTestCase`.
-
 .. _live-test-server:
 
 ``LiveServerTestCase``