Fixed #19472 -- Documented the testing requirements and tools for custom User models.

Thanks to gcc for the report.

docs/topics/auth.txt

@@ -2155,6 +2155,61 @@ Another limitation of custom User models is that you can't use
 :func:`django.contrib.auth.get_user_model()` as the sender or target of a signal
 handler. Instead, you must register the handler with the actual User model.
 
+Custom users and testing/fixtures
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you are writing an application that interacts with the User model, you must
+take some precautions to ensure that your test suite will run regardless of
+the User model that is being used by a project. Any test that instantiates an
+instance of User will fail if the User model has been swapped out. This
+includes any attempt to create an instance of User with a fixture.
+
+To ensure that your test suite will pass in any project configuration,
+``django.contrib.auth.tests.utils`` defines a ``@skipIfCustomUser`` decorator.
+This decorator will cause a test case to be skipped if any User model other
+than the default Django user is in use. This decorator can be applied to a
+single test, or to an entire test class.
+
+Depending on your application, tests may also be needed to be added to ensure
+that the application works with *any* user model, not just the default User
+model. To assist with this, Django provides two substitute user models that
+can be used in test suites:
+
+* :class:`django.contrib.auth.tests.custom_user.CustomUser`, a custom user
+  model that uses an ``email`` field as the username, and has a basic
+  admin-compliant permissions setup
+
+* :class:`django.contrib.auth.tests.custom_user.ExtensionUser`, a custom
+  user model that extends :class:`~django.contrib.auth.models.AbstractUser`,
+  adding a ``date_of_birth`` field.
+
+You can then use the ``@override_settings`` decorator to make that test run
+with the custom User model. For example, here is a skeleton for a test that
+would test three possible User models -- the default, plus the two User
+models provided by ``auth`` app::
+
+    from django.contrib.auth.tests.utils import skipIfCustomUser
+    from django.test import TestCase
+    from django.test.utils import override_settings
+
+
+    class ApplicationTestCase(TestCase):
+        @skipIfCustomUser
+        def test_normal_user(self):
+            "Run tests for the normal user model"
+            self.assertSomething()
+
+        @override_settings(AUTH_USER_MODEL='auth.CustomUser')
+        def test_custom_user(self):
+            "Run tests for a custom user model with email-based authentication"
+            self.assertSomething()
+
+        @override_settings(AUTH_USER_MODEL='auth.ExtensionUser')
+        def test_extension_user(self):
+            "Run tests for a simple extension of the built-in User."
+            self.assertSomething()
+
+
 A full example
 --------------