diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 74fd813215baa..252b59b181770 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -1421,9 +1421,10 @@ do not support ``nowait``, such as MySQL, will cause a unexpectedly blocking. Evaluating a queryset with ``select_for_update`` in autocommit mode is -an error because the rows are then not locked. If allowed, this would -facilitate data corruption, and could easily be caused by calling, -outside of any transaction, code that expects to be run in one. +a :exc:`~django.db.transaction.TransactionManagementError` error because the +rows are then not locked. If allowed, this would facilitate data corruption, and +could easily be caused by calling, outside of any transaction, code that expects +to be run in one. Using ``select_for_update`` on backends which do not support ``SELECT ... FOR UPDATE`` (such as SQLite) will have no effect. @@ -1433,6 +1434,17 @@ Using ``select_for_update`` on backends which do not support It is now an error to execute a query with ``select_for_update()`` in autocommit mode. With earlier releases in the 1.6 series it was a no-op. +.. warning:: + + Although `select_for_update() normally fails in autocommit mode, since + :class:`~django.test.TestCase` automatically wraps each test in a transaction, + calling `select_for_update()` in a `TestCase` even without an + :func:`~django.db.transaction.atomic()` block will unexpectedly + pass without raising a `TransactionManagementError`. To properly test + `select_for_update()` you should use + :class:`~django.test.TransactionTestCase`. + + raw ~~~ diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt index ecff777263d58..9f671044a892b 100644 --- a/docs/topics/testing/tools.txt +++ b/docs/topics/testing/tools.txt @@ -636,7 +636,10 @@ to test the effects of commit and rollback: 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. + use ``TransactionTestCase`` when testing transactional behavior or any code + that can't normally be excuted in autocommit mode + (:meth:`~django.db.models.query.QuerySet.select_for_update()` is an + example). ``TransactionTestCase`` inherits from :class:`~django.test.SimpleTestCase`.