Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fixed #19472 -- Documented the testing requirements and tools for cus…

…tom User models.

Thanks to gcc for the report.
  • Loading branch information...
commit bd414aed01d48339ed02b9714565939536ffbfcb 1 parent 1b646e6
@freakboy3742 freakboy3742 authored
Showing with 55 additions and 0 deletions.
  1. +55 −0 docs/topics/auth.txt
View
55 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
--------------
Please sign in to comment.
Something went wrong with that request. Please try again.