From 5aa6ed2c2a91a709ac256ee63eee981fc71ad3bb Mon Sep 17 00:00:00 2001
From: Karl Hobley <karlhobley10@gmail.com>
Date: Wed, 18 Mar 2015 19:44:30 +0000
Subject: [PATCH] Docs for running the tests

Fixes #1004
---
 docs/howto/contributing.rst | 64 +++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/docs/howto/contributing.rst b/docs/howto/contributing.rst
index 7971769971..f43c63d46d 100644
--- a/docs/howto/contributing.rst
+++ b/docs/howto/contributing.rst
@@ -18,6 +18,70 @@ Coding guidelines
 * Python 2 and 3 compatibility. All contributions should support Python 2 and 3 and we recommend using the `six <https://pythonhosted.org/six/>`_ compatibility library (use the pip version installed as a dependency, not the version bundled with Django).
 * Tests. Wagtail has a suite of tests, which we are committed to improving and expanding. We run continuous integration at `travis-ci.org/torchbox/wagtail <https://travis-ci.org/torchbox/wagtail>`_ to ensure that no commits or pull requests introduce test failures. If your contributions add functionality to Wagtail, please include the additional tests to cover it; if your contributions alter existing functionality, please update the relevant tests accordingly.
 
+Running the unit tests
+~~~~~~~~~~~~~~~~~~~~~~
+
+In order to run Wagtail's test suite, you will need to install some dependencies first. We recommend installing these into a virtual environment.
+
+
+**Setting up the virtual environment**
+
+If you are using Python 3.3 or above, run the following commands in your shell
+at the root of the Wagtail repo::
+
+    pyvenv venv
+    source venv/bin/activate
+    python setup.py develop
+    pip install -r requirements-dev.txt
+
+For Python 2, you will need to install the ``virtualenv`` package and replace
+the first line above with:
+
+    virtualenv venv
+
+**Running the tests**
+
+With your virtual environment active, run the following command to run all the
+tests::
+
+    python runtests.py
+
+**Running only some of the tests**
+
+At the time of writing, Wagtail has nearly 1000 tests which takes a while to
+run. You can run tests for only one part of Wagtail by passing in the path as
+an argument to ``runtests.py``::
+
+    python runtests.py wagtail.wagtailcore
+
+**Testing against PostgreSQL**
+
+By default, Wagtail tests against SQLite. If you need to test against a
+different database, set the ``DATABASE_ENGINE`` environment variable to the
+name of the Django database backend to test against::
+
+    DATABASE_ENGINE=django.db.backends.postgresql_psycopg2 python runtests.py
+
+This will create a new database called ``test_wagtail`` in PostgreSQL and run
+the tests against it.
+
+If you need to use a different user, password or host. Use the ``PGUSER``, ``PGPASSWORD`` and ``PGHOST`` environment variables.
+
+**Testing Elasticsearch**
+
+To test Elasticsearch, you need to have the ``elasticsearch`` package installed.
+
+Once installed, Wagtail will attempt to connect to a local instance of
+Elasticsearch (``http://localhost:9200``) and use the index ``test_wagtail``.
+
+If your Elasticsearch instance is located somewhere else, you can set the
+``ELASTICSEARCH_URL`` environment variable to point to its location::
+
+    ELASTICSEARCH_URL=http://my-elasticsearch-instance:9200 python runtests.py
+
+If you no longer want Wagtail to test against Elasticsearch, uninstall the
+``elasticsearch`` package.
+
 Styleguide
 ~~~~~~~~~~