From 7a7e403325427642905a5b3e26931c2b8e92d4b1 Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Wed, 24 Feb 2016 10:18:18 -0500 Subject: [PATCH] Refs #26270 -- Reorganized TestCase docs. --- docs/topics/testing/tools.txt | 83 +++++++++++++++-------------------- 1 file changed, 36 insertions(+), 47 deletions(-) diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt index 289b84fdfc4..8cd847f066c 100644 --- a/docs/topics/testing/tools.txt +++ b/docs/topics/testing/tools.txt @@ -617,13 +617,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: @@ -647,17 +652,8 @@ functionality like: * The ability to run tests with :ref:`modified settings `. * Using the :attr:`~SimpleTestCase.client` :class:`~django.test.Client`. -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 `. -* The remaining specialized :meth:`assert* - ` 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 @@ -670,8 +666,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 @@ -705,12 +699,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 `. +* The remaining specialized :meth:`assert* + ` 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``. @@ -739,39 +744,31 @@ 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. +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`. -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: +The class: -* Automatic loading of fixtures. - -* 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`. * Checks deferrable database constraints at the end of each test. -* Creates a TestClient instance. - -* Django-specific assertions for testing for things like redirection and form - errors. - .. versionchanged:: 1.10 The check for deferrable database constraints at the end of each test was added. +It also provides an additional method: + .. classmethod:: TestCase.setUpTestData() The class-level ``atomic`` block described above allows the creation of @@ -807,14 +804,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``