diff options
author | Tim Graham <timograham@gmail.com> | 2016-02-24 10:18:18 -0500 |
---|---|---|
committer | Tim Graham <timograham@gmail.com> | 2016-02-25 08:05:14 -0500 |
commit | d7881bfa5ce46def9b82906b63ba7fb69513019b (patch) | |
tree | 53e17736af8d40d7ae380f8241e116ff9ddc9ade | |
parent | 3e1aa3742248c81756b6fff73ad289f107eeac79 (diff) | |
download | django-d7881bfa5ce46def9b82906b63ba7fb69513019b.tar.gz |
[1.9.x] Refs #26270 -- Reorganized TestCase docs.
Backport of 7a7e403325427642905a5b3e26931c2b8e92d4b1 from master
-rw-r--r-- | docs/topics/testing/tools.txt | 81 |
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`` |