Fixed #21164 -- Added documentation for issue with test users.

The package renaming restores the older package names (which were also the
documented package names). This doesn't affect test discovery because the
module in question doesn't contain any tests.

Thanks to Carl for the design discussion.

docs/releases/1.6.txt

@@ -442,6 +442,29 @@ but will not be removed from Django until version 1.8.
 
 .. _recommendations in the Python documentation: http://docs.python.org/2/library/doctest.html#unittest-api
 
+Custom User models in tests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The introduction of the new test runner has also slightly changed the way that
+test models are imported. As a result, any test that overrides ``AUTH_USER_MODEL``
+to test behavior with one of Django's test user models (
+:class:`~django.contrib.auth.tests.custom_user.CustomUser` and
+:class:`~django.contrib.auth.tests.custom_user.ExtensionUser`) must now
+explicitly import the User model in your test module::
+
+    from django.contrib.auth.tests.custom_user import CustomUser
+
+    @override_settings(AUTH_USER_MODEL='auth.CustomUser')
+    class CustomUserFeatureTests(TestCase):
+        def test_something(self):
+            # Test code here ...
+
+This import forces the custom user model to be registered. Without this import,
+the test will be unable to swap in the custom user model, and you will get an
+error reporting::
+
+    ImproperlyConfigured: AUTH_USER_MODEL refers to model 'auth.CustomUser' that has not been installed
+
 Time zone-aware ``day``, ``month``, and ``week_day`` lookups
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/topics/auth/customizing.txt

@@ -855,12 +855,14 @@ 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:
 
-* ``django.contrib.auth.tests.custom_user.CustomUser``, a custom user
-  model that uses an ``email`` field as the username, and has a basic
+.. class:: tests.custom_user.CustomUser
+
+  A custom user model that uses an ``email`` field as the username, and has a basic
   admin-compliant permissions setup
 
-* ``django.contrib.auth.tests.custom_user.ExtensionUser``, a custom
-  user model that extends ``django.contrib.auth.models.AbstractUser``,
+.. class:: tests.custom_user.ExtensionUser
+
+  A custom user model that extends ``django.contrib.auth.models.AbstractUser``,
   adding a ``date_of_birth`` field.
 
 You can then use the ``@override_settings`` decorator to make that test run
@@ -869,6 +871,7 @@ 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.contrib.auth.tests.custom_user import CustomUser, ExtensionUser
     from django.test import TestCase, override_settings
 
 
@@ -888,6 +891,9 @@ models provided by ``auth`` app::
             "Run tests for a simple extension of the built-in User."
             self.assertSomething()
 
+.. versionchanged:: 1.6
+
+    In Django 1.5, it wasn't necessary to explicitly import the test User models.
 
 A full example
 --------------