7 files changed, 37 insertions, 8 deletions
diff --git a/django/contrib/auth/tests/test_custom_user.py b/django/contrib/auth/tests/custom_user.py
index 394baa3204..394baa3204 100644
--- a/django/contrib/auth/tests/test_custom_user.py
+++ b/django/contrib/auth/tests/custom_user.py
diff --git a/django/contrib/auth/tests/test_auth_backends.py b/django/contrib/auth/tests/test_auth_backends.py
index 4afe7c026c..280d760afb 100644
--- a/django/contrib/auth/tests/test_auth_backends.py
+++ b/django/contrib/auth/tests/test_auth_backends.py
@@ -5,7 +5,7 @@ from django.conf import settings
 from django.contrib.auth.backends import ModelBackend
 from django.contrib.auth.models import User, Group, Permission, AnonymousUser
 from django.contrib.auth.tests.utils import skipIfCustomUser
-from django.contrib.auth.tests.test_custom_user import ExtensionUser, CustomPermissionsUser, CustomUser
+from django.contrib.auth.tests.custom_user import ExtensionUser, CustomPermissionsUser, CustomUser
 from django.contrib.contenttypes.models import ContentType
 from django.core.exceptions import ImproperlyConfigured, PermissionDenied
 from django.contrib.auth import authenticate, get_user
diff --git a/django/contrib/auth/tests/test_basic.py b/django/contrib/auth/tests/test_basic.py
index 8dc9af5d85..57790830b0 100644
--- a/django/contrib/auth/tests/test_basic.py
+++ b/django/contrib/auth/tests/test_basic.py
@@ -6,7 +6,7 @@ import locale
 from django.contrib.auth import get_user_model
 from django.contrib.auth.management.commands import createsuperuser
 from django.contrib.auth.models import User, AnonymousUser
-from django.contrib.auth.tests.test_custom_user import CustomUser
+from django.contrib.auth.tests.custom_user import CustomUser
 from django.contrib.auth.tests.utils import skipIfCustomUser
 from django.core.exceptions import ImproperlyConfigured
 from django.core.management import call_command
diff --git a/django/contrib/auth/tests/test_handlers.py b/django/contrib/auth/tests/test_handlers.py
index b3737172a3..b86775fc28 100644
--- a/django/contrib/auth/tests/test_handlers.py
+++ b/django/contrib/auth/tests/test_handlers.py
@@ -2,7 +2,7 @@ from __future__ import unicode_literals
 
 from django.contrib.auth.handlers.modwsgi import check_password, groups_for_user
 from django.contrib.auth.models import User, Group
-from django.contrib.auth.tests.test_custom_user import CustomUser
+from django.contrib.auth.tests.custom_user import CustomUser
 from django.contrib.auth.tests.utils import skipIfCustomUser
 from django.test import TransactionTestCase
 from django.test.utils import override_settings
diff --git a/django/contrib/auth/tests/test_management.py b/django/contrib/auth/tests/test_management.py
index 91a6a589c1..e56df0676b 100644
--- a/django/contrib/auth/tests/test_management.py
+++ b/django/contrib/auth/tests/test_management.py
@@ -5,7 +5,7 @@ from django.contrib.auth import models, management
 from django.contrib.auth.management import create_permissions
 from django.contrib.auth.management.commands import changepassword
 from django.contrib.auth.models import User
-from django.contrib.auth.tests.test_custom_user import CustomUser
+from django.contrib.auth.tests.custom_user import CustomUser
 from django.contrib.auth.tests.utils import skipIfCustomUser
 from django.contrib.contenttypes.models import ContentType
 from django.core.management import call_command
diff --git a/docs/releases/1.6.txt b/docs/releases/1.6.txt
index 7cded8c544..0f52f224ce 100644
--- a/docs/releases/1.6.txt
+++ b/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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt
index 1407ed4d8f..273f65f09e 100644
--- a/docs/topics/auth/customizing.txt
+++ b/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
 --------------