2 files changed, 40 insertions, 0 deletions
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index 66e92bae6d..f2029e9b19 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -1397,6 +1397,12 @@ Each process gets its own database. You must ensure that different test cases
 don't access the same resources. For instance, test cases that touch the
 filesystem should create a temporary directory for their own use.
 
+.. note::
+
+    If you have test classes that cannot be run in parallel, you can use
+    ``SerializeMixin`` to run them sequentially. See :ref:`Enforce running test
+    classes sequentially <topics-testing-enforce-run-sequentially>`.
+
 This option requires the third-party ``tblib`` package to display tracebacks
 correctly:
 
diff --git a/docs/topics/testing/advanced.txt b/docs/topics/testing/advanced.txt
index 0a228fc4ef..e9f64f1941 100644
--- a/docs/topics/testing/advanced.txt
+++ b/docs/topics/testing/advanced.txt
@@ -300,6 +300,40 @@ Advanced features of ``TransactionTestCase``
     Using ``reset_sequences = True`` will slow down the test, since the primary
     key reset is a relatively expensive database operation.
 
+.. _topics-testing-enforce-run-sequentially:
+
+Enforce running test classes sequentially
+=========================================
+
+If you have test classes that cannot be run in parallel (e.g. because they
+share a common resource), you can use ``django.test.testcases.SerializeMixin``
+to run them sequentially. This mixin uses a filesystem ``lockfile``.
+
+For example, you can use ``__file__`` to determine that all test classes in the
+same file that inherit from ``SerializeMixin`` will run sequentially::
+
+    import os
+
+    from django.test import TestCase
+    from django.test.testcases import SerializeMixin
+
+    class ImageTestCaseMixin(SerializeMixin):
+        lockfile = __file__
+
+        def setUp(self):
+            self.filename = os.path.join(temp_storage_dir, 'my_file.png')
+            self.file = create_file(self.filename)
+
+    class RemoveImageTests(ImageTestCaseMixin, TestCase):
+        def test_remove_image(self):
+            os.remove(self.filename)
+            self.assertFalse(os.path.exists(self.filename))
+
+    class ResizeImageTests(ImageTestCaseMixin, TestCase):
+        def test_resize_image(self):
+            resize_image(self.file, (48, 48))
+            self.assertEqual(get_image_size(self.file), (48, 48))
+
 .. _testing-reusable-applications:
 
 Using the Django test runner to test reusable applications