From 7d8d2b56be12fd573dccba41cbeebfa2cea61534 Mon Sep 17 00:00:00 2001
From: Caio Ariede <caio.ariede@gmail.com>
Date: Wed, 5 Jun 2019 11:35:36 -0300
Subject: [PATCH] [3.0.x] Fixed #28790 -- Doc'd how to avoid running certain
 test classes in parallel.

Backport of dafdfd6a60638c4edcca7c4e65d11c0af654d759 from master
---
 docs/ref/django-admin.txt        |  6 ++++++
 docs/topics/testing/advanced.txt | 34 ++++++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index 1f76879c23..e665cebf8b 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -1418,6 +1418,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 48006d7b73..84df321d0d 100644
--- a/docs/topics/testing/advanced.txt
+++ b/docs/topics/testing/advanced.txt
@@ -299,6 +299,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