Fixed #20916 -- Added Client.force_login() to bypass authentication.

3 files changed, 33 insertions, 0 deletions

diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index b80d14f985..48c850f9a7 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -484,6 +484,11 @@ Tests
 * Added the :meth:`json() <django.test.Response.json>` method to test client
   responses to give access to the response body as JSON.
 
+* Added the :meth:`~django.test.Client.force_login()` method to the test
+  client. Use this method to simulate the effect of a user logging into the
+  site while skipping the authentication and verification steps of
+  :meth:`~django.test.Client.login()`.
+
 URLs
 ^^^^
 
diff --git a/docs/topics/testing/overview.txt b/docs/topics/testing/overview.txt
index cee2f2c1fe..d345e9c36d 100644
--- a/docs/topics/testing/overview.txt
+++ b/docs/topics/testing/overview.txt
@@ -312,6 +312,8 @@ failed and erroneous tests. If all the tests pass, the return code is 0. This
 feature is useful if you're using the test-runner script in a shell script and
 need to test for success or failure at that level.
 
+.. _speeding-up-tests-auth-hashers:
+
 Speeding up the tests
 ---------------------
 
diff --git a/docs/topics/testing/tools.txt b/docs/topics/testing/tools.txt
index 2ebe98eda4..fef718c7c6 100644
--- a/docs/topics/testing/tools.txt
+++ b/docs/topics/testing/tools.txt
@@ -384,6 +384,32 @@ Use the ``django.test.Client`` class to make requests.
         :meth:`~django.contrib.auth.models.UserManager.create_user` helper
         method to create a new user with a correctly hashed password.
 
+    .. method:: Client.force_login(user, backend=None)
+
+        .. versionadded:: 1.9
+
+        If your site uses Django's :doc:`authentication
+        system</topics/auth/index>`, you can use the ``force_login()`` method
+        to simulate the effect of a user logging into the site. Use this method
+        instead of :meth:`login` when a test requires a user be logged in and
+        the details of how a user logged in aren't important.
+
+        Unlike ``login()``, this method skips the authentication and
+        verification steps: inactive users (:attr:`is_active=False
+        <django.contrib.auth.models.User.is_active>`) are permitted to login
+        and the user's credentials don't need to be provided.
+
+        The user will have its ``backend`` attribute set to the value of the
+        ``backend`` argument (which should be a dotted Python path string), or
+        to ``settings.AUTHENTICATION_BACKENDS[0]`` if a value isn't provided.
+        The :func:`~django.contrib.auth.authenticate` function called by
+        :meth:`login` normally annotates the user like this.
+
+        This method is faster than ``login()`` since the expensive
+        password hashing algorithms are bypassed. Also, you can speed up
+        ``login()`` by :ref:`using a weaker hasher while testing
+        <speeding-up-tests-auth-hashers>`.
+
     .. method:: Client.logout()
 
         If your site uses Django's :doc:`authentication system</topics/auth/index>`,