Backwards incompatible change: Changed the way test.Client.login operates. Old implemenation was fragile, and tightly bound to forms. New implementation interfaces directly with the login system, is compatible with any authentication backend, and doesn't depend upon specific template inputs being available.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@5152 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 27 insertions, 14 deletions

diff --git a/docs/testing.txt b/docs/testing.txt
index 5a2579b624..2133df797f 100644
--- a/docs/testing.txt
+++ b/docs/testing.txt
@@ -246,22 +246,35 @@ can be invoked on the ``Client`` instance.
     file name), and `attachment_file` (containing the file data). Note that you
     need to manually close the file after it has been provided to the POST.
 
-``login(path, username, password)``
-    In a production site, it is likely that some views will be protected with
-    the @login_required decorator provided by ``django.contrib.auth``. Interacting
-    with a URL that has been login protected is a slightly complex operation,
-    so the Test Client provides a simple method to automate the login process. A
-    call to ``login()`` stimulates the series of GET and POST calls required
-    to log a user into a @login_required protected view.
-
-    If login is possible, the final return value of ``login()`` is the response
-    that is generated by issuing a GET request on the protected URL. If login
-    is not possible, ``login()`` returns False.
+``login(**credentials)``
+    ** New in Django development version **
+    
+    On a production site, it is likely that some views will be protected from
+    anonymous access through the use of the @login_required decorator, or some
+    other login checking mechanism. The ``login()`` method can be used to
+    simulate the effect of a user logging into the site. As a result of calling
+    this method, the Client will have all the cookies and session data required
+    to pass any login-based tests that may form part of a view.
+    
+    In most cases, the ``credentials`` required by this method are the username 
+    and password of the user that wants to log in, provided as keyword 
+    arguments::
+    
+        c = Client()
+        c.login(username='fred', password='secret')
+        # Now you can access a login protected view
 
+    If you are using a different authentication backend, this method may
+    require different credentials.
+    
+    ``login()`` returns ``True`` if it the credentials were accepted and login 
+    was successful. 
+        
     Note that since the test suite will be executed using the test database,
-    which contains no users by default. As a result, logins for your production
-    site will not work. You will need to create users as part of the test suite
-    to be able to test logins to your application.
+    which contains no users by default. As a result, logins that are valid
+    on your production site will not work under test conditions. You will 
+    need to create users as part of the test suite (either manually, or
+    using a test fixture).
 
 Testing Responses
 ~~~~~~~~~~~~~~~~~