Fixed #4476 -- Added a ``follow`` option to the test client request methods. This implements browser-like behavior for the test client, following redirect chains when a 30X response is received. Thanks to Marc Fargas and Keith Bussell for their work on this.

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

1 files changed, 75 insertions, 37 deletions

diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt
index bd68f6ba7a..b7d04b4771 100644
--- a/docs/topics/testing.txt
+++ b/docs/topics/testing.txt
@@ -478,7 +478,8 @@ arguments at time of construction:
     Once you have a ``Client`` instance, you can call any of the following
     methods:
 
-    .. method:: Client.get(path, data={})
+    .. method:: Client.get(path, data={}, follow=False)
+
 
         Makes a GET request on the provided ``path`` and returns a ``Response``
         object, which is documented below.
@@ -505,7 +506,18 @@ arguments at time of construction:
         If you provide URL both an encoded GET data and a data argument,
         the data argument will take precedence.
 
-    .. method:: Client.post(path, data={}, content_type=MULTIPART_CONTENT)
+        If you set ``follow`` to ``True`` the client will follow any redirects
+        and a ``redirect_chain`` attribute will be set in the response object
+        containing tuples of the intermediate urls and status codes.
+
+        If you had an url ``/redirect_me/`` that redirected to ``/next/``, that
+        redirected to ``/final/``, this is what you'd see::
+
+            >>> response = c.get('/redirect_me/')
+            >>> response.redirect_chain
+            [(u'http://testserver/next/', 302), (u'http://testserver/final/', 302)]
+
+    .. method:: Client.post(path, data={}, content_type=MULTIPART_CONTENT, follow=False)
 
         Makes a POST request on the provided ``path`` and returns a
         ``Response`` object, which is documented below.
@@ -556,7 +568,7 @@ arguments at time of construction:
         Note that you should manually close the file after it has been provided
         to ``post()``.
 
-        .. versionadded:: development
+        .. versionchanged:: 1.1
 
         If the URL you request with a POST contains encoded parameters, these
         parameters will be made available in the request.GET data. For example,
@@ -568,7 +580,11 @@ arguments at time of construction:
         to retrieve the username and password, and could interrogate request.GET
         to determine if the user was a visitor.
 
-    .. method:: Client.head(path, data={})
+        If you set ``follow`` to ``True`` the client will follow any redirects
+        and a ``redirect_chain`` attribute will be set in the response object
+        containing tuples of the intermediate urls and status codes.
+
+    .. method:: Client.head(path, data={}, follow=False)
 
         .. versionadded:: development
 
@@ -576,14 +592,22 @@ arguments at time of construction:
         object. Useful for testing RESTful interfaces. Acts just like
         :meth:`Client.get` except it does not return a message body.
 
-    .. method:: Client.options(path, data={})
+        If you set ``follow`` to ``True`` the client will follow any redirects
+        and a ``redirect_chain`` attribute will be set in the response object
+        containing tuples of the intermediate urls and status codes.
+
+    .. method:: Client.options(path, data={}, follow=False)
 
         .. versionadded:: development
 
         Makes an OPTIONS request on the provided ``path`` and returns a
         ``Response`` object. Useful for testing RESTful interfaces.
 
-    .. method:: Client.put(path, data={}, content_type=MULTIPART_CONTENT)
+        If you set ``follow`` to ``True`` the client will follow any redirects
+        and a ``redirect_chain`` attribute will be set in the response object
+        containing tuples of the intermediate urls and status codes.
+
+    .. method:: Client.put(path, data={}, content_type=MULTIPART_CONTENT, follow=False)
 
         .. versionadded:: development
 
@@ -591,13 +615,21 @@ arguments at time of construction:
         ``Response`` object. Useful for testing RESTful interfaces. Acts just
         like :meth:`Client.post` except with the PUT request method.
 
-    .. method:: Client.delete(path)
+        If you set ``follow`` to ``True`` the client will follow any redirects
+        and a ``redirect_chain`` attribute will be set in the response object
+        containing tuples of the intermediate urls and status codes.
+
+    .. method:: Client.delete(path, follow=False)
 
         .. versionadded:: development
 
         Makes an DELETE request on the provided ``path`` and returns a
         ``Response`` object. Useful for testing RESTful interfaces.
 
+        If you set ``follow`` to ``True`` the client will follow any redirects
+        and a ``redirect_chain`` attribute will be set in the response object
+        containing tuples of the intermediate urls and status codes.
+
     .. method:: Client.login(**credentials)
 
         .. versionadded:: 1.0
@@ -789,47 +821,47 @@ additions.
 
 .. class:: TransactionTestCase()
 
-Django ``TestCase`` classes make use of database transaction facilities, if 
-available, to speed up the process of resetting the database to a known state 
-at the beginning of each test. A consequence of this, however, is that the 
-effects of transaction commit and rollback cannot be tested by a Django 
-``TestCase`` class. If your test requires testing of such transactional 
+Django ``TestCase`` classes make use of database transaction facilities, if
+available, to speed up the process of resetting the database to a known state
+at the beginning of each test. A consequence of this, however, is that the
+effects of transaction commit and rollback cannot be tested by a Django
+``TestCase`` class. If your test requires testing of such transactional
 behavior, you should use a Django ``TransactionTestCase``.
 
-``TransactionTestCase`` and ``TestCase`` are identical except for the manner 
-in which the database is reset to a known state and the ability for test code 
-to test the effects of commit and rollback. A ``TranscationTestCase`` resets 
-the database before the test runs by truncating all tables and reloading 
-initial data. A ``TransactionTestCase`` may call commit and rollback and 
-observe the effects of these calls on the database.  
+``TransactionTestCase`` and ``TestCase`` are identical except for the manner
+in which the database is reset to a known state and the ability for test code
+to test the effects of commit and rollback. A ``TranscationTestCase`` resets
+the database before the test runs by truncating all tables and reloading
+initial data. A ``TransactionTestCase`` may call commit and rollback and
+observe the effects of these calls on the database.
 
-A ``TestCase``, on the other hand, does not truncate tables and reload initial 
-data at the beginning of a test. Instead, it encloses the test code in a 
-database transaction that is rolled back at the end of the test.  It also 
-prevents the code under test from issuing any commit or rollback operations 
-on the database, to ensure that the rollback at the end of the test restores 
-the database to its initial state. In order to guarantee that all ``TestCase`` 
-code starts with a clean database, the Django test runner runs all ``TestCase`` 
-tests first, before any other tests (e.g. doctests) that may alter the 
+A ``TestCase``, on the other hand, does not truncate tables and reload initial
+data at the beginning of a test. Instead, it encloses the test code in a
+database transaction that is rolled back at the end of the test.  It also
+prevents the code under test from issuing any commit or rollback operations
+on the database, to ensure that the rollback at the end of the test restores
+the database to its initial state. In order to guarantee that all ``TestCase``
+code starts with a clean database, the Django test runner runs all ``TestCase``
+tests first, before any other tests (e.g. doctests) that may alter the
 database without restoring it to its original state.
 
-When running on a database that does not support rollback (e.g. MySQL with the 
-MyISAM storage engine), ``TestCase`` falls back to initializing the database 
+When running on a database that does not support rollback (e.g. MySQL with the
+MyISAM storage engine), ``TestCase`` falls back to initializing the database
 by truncating tables and reloading initial data.
 
 
 .. note::
-    The ``TestCase`` use of rollback to un-do the effects of the test code 
-    may reveal previously-undetected errors in test code.  For example, 
-    test code that assumes primary keys values will be assigned starting at 
-    one may find that assumption no longer holds true when rollbacks instead 
-    of table truncation are being used to reset the database.  Similarly, 
-    the reordering of tests so that all ``TestCase`` classes run first may 
-    reveal unexpected dependencies on test case ordering.  In such cases a 
+    The ``TestCase`` use of rollback to un-do the effects of the test code
+    may reveal previously-undetected errors in test code.  For example,
+    test code that assumes primary keys values will be assigned starting at
+    one may find that assumption no longer holds true when rollbacks instead
+    of table truncation are being used to reset the database.  Similarly,
+    the reordering of tests so that all ``TestCase`` classes run first may
+    reveal unexpected dependencies on test case ordering.  In such cases a
     quick fix is to switch the ``TestCase`` to a ``TransactionTestCase``.
     A better long-term fix, that allows the test to take advantage of the
     speed benefit of ``TestCase``, is to fix the underlying test problem.
-              
+
 
 Default test client
 ~~~~~~~~~~~~~~~~~~~
@@ -1028,9 +1060,15 @@ applications:
 .. method:: assertRedirects(response, expected_url, status_code=302, target_status_code=200)
 
     Asserts that the response return a ``status_code`` redirect status, it
-    redirected to ``expected_url`` (including any GET data), and the subsequent
+    redirected to ``expected_url`` (including any GET data), and the final
     page was received with ``target_status_code``.
 
+    .. versionadded:: 1.1
+
+    If your request used the ``follow`` argument, the ``expected_url`` and
+    ``target_status_code`` will be the url and status code for the final
+    point of the redirect chain.
+
 E-mail services
 ---------------