summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTim Graham <timograham@gmail.com>2016-02-24 10:18:18 -0500
committerTim Graham <timograham@gmail.com>2016-02-25 08:05:14 -0500
commitd7881bfa5ce46def9b82906b63ba7fb69513019b (patch)
tree53e17736af8d40d7ae380f8241e116ff9ddc9ade
parent3e1aa3742248c81756b6fff73ad289f107eeac79 (diff)
downloaddjango-d7881bfa5ce46def9b82906b63ba7fb69513019b.tar.gz
[1.9.x] Refs #26270 -- Reorganized TestCase docs.
Backport of 7a7e403325427642905a5b3e26931c2b8e92d4b1 from master
-rw-r--r--docs/topics/testing/tools.txt81
1 files changed, 35 insertions, 46 deletions
diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt
index a837c516de..51510e4cba 100644
--- a/docs/topics/testing/tools.txt
+++ b/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
-functionality like:
+A subclass of :class:`unittest.TestCase` that adds this functionality:
* 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
-features like:
-
-* 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.
+If your tests make any database queries, use subclasses
+:class:`~django.test.TransactionTestCase` or :class:`~django.test.TestCase`.
.. 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
-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
+``TransactionTestCase`` inherits from :class:`~django.test.SimpleTestCase` to
+add some database-specific features:
+
+* Resetting the database to a known state at the beginning of each test to
+ ease testing and 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.
+
+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
-websites.
-
-Converting a normal :class:`unittest.TestCase` to a Django :class:`TestCase` is
-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:
+This is the most common class to use for writing tests in Django. It inherits
+from :class:`TransactionTestCase` (and by extension :class:`SimpleTestCase`).
+If your Django application doesn't use a database, use :class:`SimpleTestCase`.
-* Automatic loading of fixtures.
+The class:
-* Wraps the tests within two nested ``atomic`` blocks: one for the whole class
- and one for each test.
+* 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`.
-* Creates a TestClient instance.
-
-* Django-specific assertions for testing for things like redirection and form
- errors.
+It also provides an additional method:
.. 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``