Add page about tests to developer docs

Add page that explains how to run tests using tox and gives minimal
introduction to the test suite structure to the developers docs.

Change-Id: Idaade8a5837d3b6c41d0a58817eb58aeddfbcba7

doc/source/index.rst

@@ -81,3 +81,11 @@ Concepts
    glossary
 
 
+Running and writing tests
+=========================
+
+.. toctree::
+   :maxdepth: 1
+
+   running_tests
+   test_suite

doc/source/running_tests.rst

@@ -0,0 +1,66 @@
+Running tests
+=============
+
+Zaqar contains a suite of tests (both unit and functional) in the
+``zaqar/tests`` and ``tests`` directories.
+
+Any proposed code change 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::
+
+    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.6 tests::
+
+    tox -e py26
+
+To run the style tests::
+
+    tox -e pep8
+
+To run multiple tests separate items by commas::
+
+    tox -e py27,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.
+
+To run the tests located only in the ``tests/unit/queues/storage`` directory use::
+
+    tox -e py27 tests.unit.queues.storage
+
+To run the tests specific to the MongoDB driver in the ``tests/unit/queues/storage/test_impl_mongodb.py`` file::
+
+    tox -e py27 test_impl_mongodb
+
+To run the tests in the ``MongodbMessageTests`` class in
+the ``tests/unit/queues/storage/test_impl_mongodb.py`` file::
+
+    tox -e py27 test_impl_mongodb.MongodbMessageTests
+
+To run the `MongodbMessageTests.test_message_lifecycle` test method in
+the ``tests/unit/queues/storage/test_impl_mongodb.py`` file::
+
+    tox -e py27 test_impl_mongodb.MongodbMessageTests.test_message_lifecycle
+
+.. rubric:: Footnotes
+
+.. [#f1] See http://ci.openstack.org/jenkins.html

doc/source/test_suite.rst

@@ -0,0 +1,41 @@
+Test suite structure
+====================
+
+There are three types of tests for Zaqar:
+
+Unit tests
+    Unit tests check modules separately. For example, there
+    are checks for each individual method that the storage layer provides.
+
+Functional tests
+    Functional tests verify that the service works as expected. In particular,
+    in Zaqar they exercise the API endpoints and validate that the API responses
+    conform to the specs.  These include positive and negative tests.
+
+Tempest tests
+    Tempest tests are integration tests for Openstack [#f1]_.
+    Tempest tests for Zaqar are available at https://github.com/openstack/tempest.
+
+This document focuses on the unit and functional tests.  Please refer to the
+Tempest repository for details on how to run these tests.
+
+Code structure
+--------------
+
+The test suite lives in two directories:
+
+- ``zaqar/tests`` contains all base classes and defines tests for APIs (on both storage and transport levels).
+- ``tests`` usually contains implementations for specific drivers and additional tests.
+
+Thus base class and all common tests for storage drivers are located in the ``zaqar/tests/queues/storage/base.py`` file.
+The specific instances of the base classes for any particular storage driver are located at the
+``tests/unit/queues/storage/`` directory. See ``tests/unit/queues/storage/test_impl_mongodb.py`` for example.
+
+Similarly, unit tests for the transport layer are located in ``zaqar/tests/queues/transport``
+and are run from classes located in the ``tests/unit/queues/transport`` directory.
+
+All functional tests for Zaqar are located in the ``tests/functional`` directory.
+
+.. rubric:: Footnotes
+
+.. [#f1] See http://docs.openstack.org/developer/tempest/overview.html