Fixed #22446 -- Added tox.ini to automate pull request checks.

3 files changed, 73 insertions, 0 deletions

diff --git a/docs/internals/contributing/writing-code/coding-style.txt b/docs/internals/contributing/writing-code/coding-style.txt
index 46b12a11ed..137ab3e67f 100644
--- a/docs/internals/contributing/writing-code/coding-style.txt
+++ b/docs/internals/contributing/writing-code/coding-style.txt
@@ -4,6 +4,8 @@ Coding style
 
 Please follow these coding standards when writing code for inclusion in Django.
 
+.. _coding-style-python:
+
 Python style
 ============
 
@@ -51,6 +53,8 @@ Python style
   (``six.assertRaisesRegex()`` as long as we support Python 2) only if you need
   to use regular expression matching.
 
+.. _coding-style-imports:
+
 Imports
 =======
 
diff --git a/docs/internals/contributing/writing-code/javascript.txt b/docs/internals/contributing/writing-code/javascript.txt
index 8b8534e384..25a46695c3 100644
--- a/docs/internals/contributing/writing-code/javascript.txt
+++ b/docs/internals/contributing/writing-code/javascript.txt
@@ -60,6 +60,8 @@ Closure Compiler library requires `Java`_ 7 or higher.
 Please don't forget to run ``compress.py`` and include the ``diff`` of the
 minified scripts when submitting patches for Django's JavaScript.
 
+.. _javascript-tests:
+
 JavaScript tests
 ================
 
diff --git a/docs/internals/contributing/writing-code/unit-tests.txt b/docs/internals/contributing/writing-code/unit-tests.txt
index f92174a9a9..188a71d5e6 100644
--- a/docs/internals/contributing/writing-code/unit-tests.txt
+++ b/docs/internals/contributing/writing-code/unit-tests.txt
@@ -45,6 +45,73 @@ See :ref:`installing-development-version`.
 
 Having problems? See :ref:`troubleshooting-unit-tests` for some common issues.
 
+Running tests using ``tox``
+---------------------------
+
+`Tox <http://tox.testrun.org/>`_ is a tool for running tests in different
+virtual environments. Django includes a basic ``tox.ini`` that automates some
+checks that our build server performs on pull requests. To run the unit tests
+and other checks (such as :ref:`import sorting <coding-style-imports>`, the
+:ref:`documentation spelling checker <documentation-spelling-check>`, and
+:ref:`code formatting <coding-style-python>`), install and run the ``tox``
+command from any place in the Django source tree::
+
+    $ pip install tox
+    $ tox
+
+By default, ``tox`` runs the test suite with the bundled test settings file for
+SQLite, ``flake8``, ``isort``, and the documentation spelling checker. In
+addition to the system dependencies noted elsewhere in this documentation,
+the commands ``python2`` and ``python3`` must be on your path and linked to
+the appropriate versions of Python. A list of default environments can be seen
+as follows::
+
+    $ tox -l
+    py3
+    flake8
+    docs
+    isort
+
+Testing other Python versions and database backends
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to the default environments, ``tox`` supports running unit tests
+for other versions of Python and other database backends. Since Django's test
+suite doesn't bundle a settings file for database backends other than SQLite,
+however, you must :ref:`create and provide your own test settings
+<running-unit-tests-settings>`. For example, to run the tests on Python 3.5
+using PostgreSQL::
+
+    $ tox -e py35-postgres -- --settings=my_postgres_settings
+
+This command sets up a Python 3.5 virtual environment, installs Django's
+test suite dependencies (including those for PostgreSQL), and calls
+``runtests.py`` with the supplied arguments (in this case,
+``--settings=my_postgres_settings``).
+
+The remainder of this documentation shows commands for running tests without
+``tox``, however, any option passed to ``runtests.py`` can also be passed to
+``tox`` by prefixing the argument list with ``--``, as above.
+
+Tox also respects the ``DJANGO_SETTINGS_MODULE`` environment variable, if set.
+For example, the following is equivalent to the command above::
+
+    $ DJANGO_SETTINGS_MODULE=my_postgres_settings tox -e py35-postgres
+
+Running the JavaScript tests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Django includes a set of :ref:`JavaScript unit tests <javascript-tests>` for
+functions in certain contrib apps. The JavaScript tests aren't run by default
+using ``tox`` because they require `Node.js` to be installed and aren't
+necessary for the majority of patches. To run the JavaScript tests using
+``tox``::
+
+    $ tox -e javascript
+
+This command runs ``npm install`` to ensure test requirements are up to
+date and then runs ``npm test``.
+
 .. _running-unit-tests-settings:
 
 Using another ``settings`` module