Merge "Added test document"

2 files changed, 89 insertions, 0 deletions

diff --git a/doc/index.rst b/doc/index.rst
index 69dcd2bf9..461829ac7 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -66,3 +66,4 @@ Developer Docs
    CONTRIBUTING
    heat-dev-env
    vagrant-dev-env
+   running-tests
diff --git a/doc/running-tests.rst b/doc/running-tests.rst
new file mode 100644
index 000000000..473cbcc97
--- /dev/null
+++ b/doc/running-tests.rst
@@ -0,0 +1,88 @@
+.. _running-tests:
+
+=============
+Running tests
+=============
+
+Kolla contains a suite of tests in the
+``tests`` and ``kolla/tests`` directories.
+
+Any proposed code change in gerrit is automatically rejected by the OpenStack
+Jenkins server [#f1]_ if the change causes test failures.
+
+It is recommended for developers to run the test suite before submitting patch
+for review. This allows to catch errors as early as possible.
+
+Preferred way to run the tests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The preferred way to run the unit tests is using ``tox``. It executes tests in
+isolated environment, by creating separate virtualenv and installing
+dependencies from the ``requirements.txt`` and ``test-requirements.txt`` files,
+so the only package you install is ``tox`` itself:
+
+.. code-block:: console
+
+    $ pip install tox
+
+See `the unit testing section of the Testing wiki page`_ for more information.
+Following are some simple examples.
+
+To run the Python 2.7 tests:
+
+.. code-block:: console
+
+    $ tox -e py27
+
+To run the style tests:
+
+.. code-block:: console
+
+    $ tox -e pep8
+
+To run multiple tests separate items by commas:
+
+.. code-block:: console
+
+    $ tox -e py27,py34,pep8
+
+.. _the unit testing section of the Testing wiki page: https://wiki.openstack.org/wiki/Testing#Unit_Tests
+
+Running a subset of tests
+-------------------------
+
+Instead of running all tests, you can specify an individual directory, file,
+class or method that contains test code, i.e. filter full names of tests by a
+string.
+
+To run the tests located only in the ``kolla/tests``
+directory use:
+
+.. code-block:: console
+
+    $ tox -e py27 kolla.tests
+
+To run the tests of a specific file say ``kolla/tests/test_kolla_docker.py``:
+
+.. code-block:: console
+
+    $ tox -e py27 test_kolla_docker
+
+To run the tests in the ``ModuleArgsTest`` class in
+the ``kolla/tests/test_kolla_docker.py`` file:
+
+.. code-block:: console
+
+    $ tox -e py27 test_kolla_docker.ModuleArgsTest
+
+To run the ``ModuleArgsTest.test_module_args`` test method in
+the ``kolla/tests/test_kolla_docker.py``` file:
+
+.. code-block:: console
+
+    $ tox -e py27 test_kolla_docker.ModuleArgsTest.test_module_args
+
+
+.. rubric:: Footnotes
+
+.. [#f1] See http://docs.openstack.org/infra/system-config/jenkins.html