Fixed #25860 -- Documented a transaction leak possiblity in TestCase.

Thanks Jonas Haag for report and review.

1 files changed, 11 insertions, 2 deletions

diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt
index 6f8c1275c5..1eeb68e7d3 100644
--- a/docs/topics/testing/tools.txt
+++ b/docs/topics/testing/tools.txt
@@ -685,13 +685,22 @@ then you should use :class:`~django.test.TransactionTestCase` or
 
             @classmethod
             def setUpClass(cls):
-                super(MyTestCase, cls).setUpClass()     # Call parent first
+                super(MyTestCase, cls).setUpClass()
                 ...
 
             @classmethod
             def tearDownClass(cls):
                 ...
-                super(MyTestCase, cls).tearDownClass()  # Call parent last
+                super(MyTestCase, cls).tearDownClass()
+
+    Be sure to account for Python's behavior if an exception is raised during
+    ``setUpClass()``. If that happens, neither the tests in the class nor
+    ``tearDownClass()`` are run. In the case of :class:`django.test.TestCase`,
+    this will leak the transaction created in ``super()``  which results in
+    various symptoms including a segmentation fault on some platforms (reported
+    on OS X). If you want to intentionally raise an exception such as
+    :exc:`unittest.SkipTest` in ``setUpClass()``, be sure to do it before
+    calling ``super()`` to avoid this.
 
 TransactionTestCase
 ~~~~~~~~~~~~~~~~~~~