Fixed #2879 -- Added support for the integration with Selenium and other in-browser testing frameworks. Also added the first Selenium tests for `contrib.admin`. Many thanks to everyone for their contributions and feedback: Mikeal Rogers, Dirk Datzert, mir, Simon G., Almad, Russell Keith-Magee, Denis Golomazov, devin, robertrv, andrewbadr, Idan Gazit, voidspace, Tom Christie, hjwp2, Adam Nelson, Jannis Leidel, Anssi Kääriäinen, Preston Holmes, Bruno Renié and Jacob Kaplan-Moss.

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

4 files changed, 136 insertions, 13 deletions

diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt
index 5ec09fe84c..275ee154f6 100644
--- a/docs/internals/contributing/writing-code/unit-tests.txt
+++ b/docs/internals/contributing/writing-code/unit-tests.txt
@@ -122,6 +122,19 @@ Going beyond that, you can specify an individual test method like this:
 
     ./runtests.py --settings=path.to.settings i18n.TranslationTests.test_lazy_objects
 
+Running the Selenium tests
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some admin tests require Selenium 2, Firefox and Python >= 2.6 to work via a
+real Web browser. To allow those tests to run and not be skipped, you must
+install the selenium_ package (version > 2.13) into your Python path.
+
+Then, run the tests normally, for example:
+
+.. code-block:: bash
+
+    ./runtests.py --settings=test_sqlite admin_inlines
+
 Running all the tests
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -135,6 +148,7 @@ dependencies:
 *  setuptools_
 *  memcached_, plus a :ref:`supported Python binding <memcached>`
 *  gettext_ (:ref:`gettext_on_windows`)
+*  selenium_ (if also using Python >= 2.6)
 
 If you want to test the memcached cache backend, you'll also need to define
 a :setting:`CACHES` setting that points at your memcached instance.
@@ -149,6 +163,7 @@ associated tests will be skipped.
 .. _setuptools: http://pypi.python.org/pypi/setuptools/
 .. _memcached: http://www.danga.com/memcached/
 .. _gettext: http://www.gnu.org/software/gettext/manual/gettext.html
+.. _selenium: http://pypi.python.org/pypi/selenium
 
 .. _contrib-apps:
 
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt
index 8b83a43179..fac18f3b48 100644
--- a/docs/ref/django-admin.txt
+++ b/docs/ref/django-admin.txt
@@ -976,15 +976,22 @@ information.
 .. versionadded:: 1.2
 .. django-admin-option:: --failfast
 
-Use the :djadminopt:`--failfast` option to stop running tests and report the failure
-immediately after a test fails.
+The ``--failfast`` option can be used to stop running tests and report the
+failure immediately after a test fails.
 
 .. versionadded:: 1.4
 .. django-admin-option:: --testrunner
 
-The :djadminopt:`--testrunner` option can be used to control the test runner
-class that is used to execute tests. If this value is provided, it overrides
-the value provided by the :setting:`TEST_RUNNER` setting.
+The ``--testrunner`` option can be used to control the test runner class that
+is used to execute tests. If this value is provided, it overrides the value
+provided by the :setting:`TEST_RUNNER` setting.
+
+.. versionadded:: 1.4
+.. django-admin-option:: --liveserver
+
+The ``--liveserver`` option can be used to override the default address where
+the live server (used with :class:`~django.test.LiveServerTestCase`) is
+expected to run from. The default value is ``localhost:8081``.
 
 testserver <fixture fixture ...>
 --------------------------------
diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt
index 7ffc1aa654..51abdf1b03 100644
--- a/docs/releases/1.4.txt
+++ b/docs/releases/1.4.txt
@@ -40,6 +40,19 @@ before the release of Django 1.4.
 What's new in Django 1.4
 ========================
 
+Support for in-browser testing frameworks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Django 1.4 now supports the integration with in-browser testing frameworks such
+as Selenium_ or Windmill_ thanks to the :class:`django.test.LiveServerTestCase`
+base class, allowing you to test the interactions between your site's front and
+back ends more comprehensively. See the
+:class:`documentation<django.test.LiveServerTestCase>` for more details and
+concrete examples.
+
+.. _Windmill: http://www.getwindmill.com/
+.. _Selenium: http://seleniumhq.org/
+
 ``SELECT FOR UPDATE`` support
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt
index d6f54ad691..727ef2cb8e 100644
--- a/docs/topics/testing.txt
+++ b/docs/topics/testing.txt
@@ -581,21 +581,20 @@ Some of the things you can do with the test client are:
 * Test that a given request is rendered by a given Django template, with
   a template context that contains certain values.
 
-Note that the test client is not intended to be a replacement for Twill_,
+Note that the test client is not intended to be a replacement for Windmill_,
 Selenium_, or other "in-browser" frameworks. Django's test client has
 a different focus. In short:
 
 * Use Django's test client to establish that the correct view is being
   called and that the view is collecting the correct context data.
 
-* Use in-browser frameworks such as Twill and Selenium to test *rendered*
-  HTML and the *behavior* of Web pages, namely JavaScript functionality.
+* Use in-browser frameworks such as Windmill_ and Selenium_ to test *rendered*
+  HTML and the *behavior* of Web pages, namely JavaScript functionality. Django
+  also provides special support for those frameworks; see the section on
+  :class:`~django.test.LiveServerTestCase` for more details.
 
 A comprehensive test suite should use a combination of both test types.
 
-.. _Twill: http://twill.idyll.org/
-.. _Selenium: http://seleniumhq.org/
-
 Overview and a quick example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1753,6 +1752,97 @@ under MySQL with MyISAM tables)::
         def test_transaction_behavior(self):
             # ... conditional test code
 
+Live test server
+----------------
+
+.. versionadded:: 1.4
+
+.. currentmodule:: django.test
+
+.. class:: LiveServerTestCase()
+
+``LiveServerTestCase`` does basically the same as
+:class:`~django.test.TransactionTestCase` with one extra feature: it launches a
+live Django server in the background on setup, and shuts it down on teardown.
+This allows the use of automated test clients other than the
+:ref:`Django dummy client <test-client>` such as, for example, the Selenium_ or
+Windmill_ clients, to execute a series of functional tests inside a browser and
+simulate a real user's actions.
+
+By default the live server's address is `'localhost:8081'` and the full URL
+can be accessed during the tests with ``self.live_server_url``. If you'd like
+to change the default address (in the case, for example, where the 8081 port is
+already taken) you may pass a different one to the :djadmin:`test` command via
+the :djadminopt:`--liveserver` option, for example:
+
+.. code-block:: bash
+
+    ./manage.py test --liveserver=localhost:8082
+
+Another way of changing the default server address is by setting the
+`DJANGO_LIVE_TEST_SERVER_ADDRESS` environment variable.
+
+To demonstrate how to use ``LiveServerTestCase``, let's write a simple Selenium
+test. First of all, you need to install the `selenium package`_ into your
+Python path:
+
+.. code-block:: bash
+
+   pip install selenium
+
+Then, add a ``LiveServerTestCase``-based test to your app's tests module
+(for example: ``myapp/tests.py``). The code for this test may look as follows:
+
+.. code-block:: python
+
+    from django.test import LiveServerTestCase
+    from selenium.webdriver.firefox.webdriver import WebDriver
+
+    class MySeleniumTests(LiveServerTestCase):
+        fixtures = ['user-data.json']
+
+        @classmethod
+        def setUpClass(cls):
+            cls.selenium = WebDriver()
+            super(MySeleniumTests, cls).setUpClass()
+
+        @classmethod
+        def tearDownClass(cls):
+            super(MySeleniumTests, cls).tearDownClass()
+            cls.selenium.quit()
+
+        def test_login(self):
+            self.selenium.get('%s%s' % (self.live_server_url, '/login/'))
+            username_input = self.selenium.find_element_by_name("username")
+            username_input.send_keys('myuser')
+            password_input = self.selenium.find_element_by_name("password")
+            password_input.send_keys('secret')
+            self.selenium.find_element_by_xpath('//input[@value="Log in"]').click()
+
+Finally, you may run the test as follows:
+
+.. code-block:: bash
+
+    ./manage.py test myapp.MySeleniumTests.test_login
+
+This example will automatically open Firefox then go to the login page, enter
+the credentials and press the "Log in" button. Selenium offers other drivers in
+case you do not have Firefox installed or wish to use another browser. The
+example above is just a tiny fraction of what the Selenium client can do; check
+out the `full reference`_ for more details.
+
+.. _Windmill: http://www.getwindmill.com/
+.. _Selenium: http://seleniumhq.org/
+.. _selenium package: http://pypi.python.org/pypi/selenium
+.. _full reference: http://readthedocs.org/docs/selenium-python/en/latest/api.html
+.. _Firefox: http://www.mozilla.com/firefox/
+
+.. note::
+
+    ``LiveServerTestCase`` makes use of the :doc:`staticfiles contrib app
+    </howto/static-files>` so you'll need to have your project configured
+    accordingly (in particular by setting :setting:`STATIC_URL`).
+
 
 Using different testing frameworks
 ==================================
@@ -1833,11 +1923,9 @@ set up, execute and tear down the test suite.
     those options will be added to the list of command-line options that
     the :djadmin:`test` command can use.
 
-
 Attributes
 ~~~~~~~~~~
 
-
 .. attribute:: DjangoTestSuiteRunner.option_list
 
     .. versionadded:: 1.4