diff --git a/doc/source/developing.rst b/doc/source/developing.rst
index c9ff4ca7f4..87238c8593 100644
--- a/doc/source/developing.rst
+++ b/doc/source/developing.rst
@@ -123,25 +123,45 @@ Once run, you can see the sample data that has been created by using the
 Running Tests
 =============
 
-To run the full suites of tests maintained within Keystone, run::
+Before running tests, you should have ``tox`` installed and available in your
+environment (in addition to the other external dependencies in :doc:`setup`)::
 
-    $ ./run_tests.sh
+    $ pip install tox
 
-This shows realtime feedback during test execution, iterates over
-multiple configuration variations, and uses external projects to do
-light integration testing to verify the keystone API against other projects.
+.. NOTE::
+
+    You may need to perform both the above operation and the next inside a
+    python virtualenv, or prefix the above command with ``sudo``, depending on
+    your preference.
+
+To execute the full suite of tests maintained within Keystone, simply run::
+
+    $ tox
+
+This iterates over multiple configuration variations, and uses external
+projects to do light integration testing to verify the Identity API against
+other projects.
+
+.. NOTE::
+
+    The first time you run ``tox``, it will take additional time to build
+    virtualenvs. You can later use the ``-r`` option with ``tox`` to rebuild
+    your virtualenv in a similar manner.
+
+To run tests for one or more specific test environments (for example, the most
+common configuration of Python 2.7 and PEP-8), list the environments with the
+``-e`` option, separated by spaces::
+
+    $ tox -e py27,pep8
+
+See ``tox.ini`` for the full list of available test environments.
 
 Test Structure
 --------------
 
-``./run_test.sh`` uses its python cohort (``run_tests.py``) to iterate
-through the ``keystone/tests`` directory, using Nosetest to collect the tests
-and invoke them using an OpenStack custom test running that displays the tests
-as well as the time taken to run those tests.
-
 Not all of the tests in the tests directory are strictly unit tests. Keystone
-intentionally includes tests that run the service locally and drives the
-entire configuration to achieve basic functional testing.
+intentionally includes tests that run the service locally and drives the entire
+configuration to achieve basic functional testing.
 
 For the functional tests, an in-memory key-value store is used to keep the
 tests fast.
diff --git a/keystone/tests/test_sql_upgrade.py b/keystone/tests/test_sql_upgrade.py
index 7687bfe579..35f8aa5c60 100644
--- a/keystone/tests/test_sql_upgrade.py
+++ b/keystone/tests/test_sql_upgrade.py
@@ -15,16 +15,22 @@
 # under the License.
 """
 To run these tests against a live database:
-1. Modify the file `keystone/tests/backend_sql.conf` to use the connection for
-   your live database
-2. Set up a blank, live database.
-3. run the tests using
-    ./run_tests.sh -N  test_sql_upgrade
-    WARNING::
-        Your database will be wiped.
-    Do not do this against a Database with valuable data as
-    all data will be lost.
+
+1. Modify the file ``keystone/tests/backend_sql.conf`` to use the connection
+   for your live database
+2. Set up a blank, live database
+3. Run the tests using::
+
+    tox keystone.tests.test_sql_upgrade
+
+WARNING::
+
+    Your database will be wiped.
+
+    Do not do this against a database with valuable data as all data will be
+    lost.
 """
+
 import copy
 import json
 import uuid