From dffdca1109a2111f104f2419d081c0f971537fec Mon Sep 17 00:00:00 2001
From: Tim Graham <timograham@gmail.com>
Date: Thu, 23 May 2013 10:57:44 -0400
Subject: [PATCH] Fixed #20316 - Clarified transaction behavior of TestCase.
Thanks uberj@ for the report and lolek09 for the patch.
---
docs/topics/testing/overview.txt | 15 ++++++++++++---
1 file changed, 12 insertions(+), 3 deletions(-)
diff --git a/docs/topics/testing/overview.txt b/docs/topics/testing/overview.txt
index d543099ae6..3669bff8bf 100644
--- a/docs/topics/testing/overview.txt
+++ b/docs/topics/testing/overview.txt
@@ -925,14 +925,23 @@ 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. It also prevents the code under test from
- issuing any commit or rollback operations on the database, to ensure that the
- rollback at the end of the test restores the database to its initial state.
+ back at the end of the test. Both explicit commits like
+ ``transaction.commit()`` and implicit ones that may be caused by
+ ``Model.save()`` are replaced with a ``nop`` operation. This guarantees that
+ the rollback at the end of the test restores the database to its initial
+ state.
When running on a database that does not support rollback (e.g. MySQL with the
MyISAM storage engine), ``TestCase`` falls back to initializing the database
by truncating tables and reloading initial data.
+.. 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 ``TransactionalTestCase`` when testing transactional behavior.
+
.. note::
.. versionchanged:: 1.5