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

   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:

* 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

    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

.. 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``.

  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()

    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``