From ddb53856b62506128a6d19184dfa80da73c77db8 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee <russell@keith-magee.com>
Date: Tue, 8 Oct 2013 10:32:56 +0800
Subject: [PATCH] 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.
---
.../{test_custom_user.py => custom_user.py} | 0
.../contrib/auth/tests/test_auth_backends.py | 2 +-
django/contrib/auth/tests/test_basic.py | 2 +-
django/contrib/auth/tests/test_handlers.py | 2 +-
django/contrib/auth/tests/test_management.py | 2 +-
docs/releases/1.6.txt | 23 +++++++++++++++++++
docs/topics/auth/customizing.txt | 14 +++++++----
7 files changed, 37 insertions(+), 8 deletions(-)
rename django/contrib/auth/tests/{test_custom_user.py => custom_user.py} (100%)
diff --git a/django/contrib/auth/tests/test_custom_user.py b/django/contrib/auth/tests/custom_user.py
similarity index 100%
rename from django/contrib/auth/tests/test_custom_user.py
rename to 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
--------------