Updated testing documentation following 498ae3a36069e2d

- commit/rollback are no longer replaced by nop
- the warning about not using TestCase when testing transactional
  behavior belongs to TestCase section, not TransactionTestCase

1 files changed, 22 insertions, 19 deletions

diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt
index 628fab06c5..1d6d09c881 100644
--- a/docs/topics/testing/tools.txt
+++ b/docs/topics/testing/tools.txt
@@ -633,10 +633,20 @@ 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 the
-effects of transaction commit and rollback cannot be tested by a Django
-``TestCase`` class. If your test requires testing of such transactional
-behavior, you should use a Django ``TransactionTestCase``.
+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``.
+
+.. versionchanged:: 1.8
+
+    In older versions of Django, the effects of transaction commit and rollback
+    could not be tested within a ``TestCase``.  With the completion of the
+    deprecation cycle of the old-style transaction management in Django 1.8,
+    transaction management commands (e.g. ``transaction.commit()``) are no
+    longer disabled within ``TestCase``.
 
 ``TransactionTestCase`` and ``TestCase`` are identical except for the manner
 in which the database is reset to a known state and the ability for test code
@@ -648,11 +658,8 @@ to test the effects of commit and rollback:
 
 * A ``TestCase``, on the other hand, does not truncate tables after a test.
   Instead, it encloses the test code in a database transaction that is rolled
-  back at the end of the test. Both explicit commits like
-  ``transaction.commit()`` and implicit ones that may be caused by
-  ``transaction.atomic()`` are replaced with a ``nop`` operation. This
-  guarantees that the rollback at the end of the test restores the database to
-  its initial state.
+  back at the end of the test. This guarantees that the rollback at the end of
+  the test restores the database to its initial state.
 
 .. warning::
 
@@ -666,16 +673,6 @@ to test the effects of commit and rollback:
   this) you can set ``serialized_rollback = True`` inside the
   ``TestCase`` body.
 
-.. warning::
-
-    While ``commit`` and ``rollback`` operations still *appear* to work when
-    used in ``TestCase``, no actual commit or rollback will be performed by the
-    database. This can cause your tests to pass or fail unexpectedly. Always
-    use ``TransactionTestCase`` when testing transactional behavior or any code
-    that can't normally be executed in autocommit mode
-    (:meth:`~django.db.models.query.QuerySet.select_for_update()` is an
-    example).
-
 ``TransactionTestCase`` inherits from :class:`~django.test.SimpleTestCase`.
 
 TestCase
@@ -701,6 +698,12 @@ additions, including:
 * Django-specific assertions for testing for things like redirection and form
   errors.
 
+.. 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: