Add testing documentation to Castellan

Adds documentation showing how to run unit and functional test
in for Castellan.

Change-Id: I9141f828dd1bc1eb9938c889c32ac80dea424d40

doc/source/index.rst

@@ -14,6 +14,7 @@ Contents:
    readme
    installation
    usage
+   testing
    contributing
 
 Indices and tables

doc/source/testing.rst

@@ -0,0 +1,98 @@
+=======
+Testing
+=======
+
+Every Castellan code submission is automatically tested against a number
+of gating jobs to prevent regressions. Castellan developers should have a
+habit of running tests locally to ensure the code works as intended before
+submission.
+
+For your convenience we provide the ability to run all tests through
+the ``tox`` utility. If you are unfamiliar with tox please see
+refer to the `tox documentation`_ for assistance.
+
+.. _`tox documentation`: https://tox.readthedocs.org/en/latest/
+
+Unit Tests
+----------
+
+Currently, we provide tox environments for a variety of different Python
+versions. By default all available test environments within the tox
+configuration will execute when calling ``tox``. If you want to run an
+independent version, you can do so with the following command:
+
+.. code-block:: bash
+
+    # Executes tests on Python 2.7
+    tox -e py27
+
+
+.. note::
+
+    Other available environments are py34, py26, and pypy.
+
+    If you do not have the appropriate Python versions available, consider
+    setting up PyEnv to install multiple versions of Python. See the
+    documentation regarding `Setting up a Barbican development environment`_
+    for more information.
+
+Functional Tests
+----------------
+
+Unlike running unit tests, the functional tests require Barbican and
+Keystone services to be running in order to execute. For more
+information on this please see `Setting up a Barbican development environment`_
+and `Using Keystone Middleware with Barbican`_
+
+.. _`Setting up a Barbican development environment`: http://docs.openstack.org/developer/barbican/setup/dev.html
+.. _`Using Keystone Middleware with Barbican`: http://docs.openstack.org/developer/barbican/setup/keystone.html
+
+Castellan uses ``/etc/castellan/castellan-functional.conf`` in order to
+run functional tests. A sample file can be generated by running:
+
+.. code-block:: bash
+
+    # Generate a sample configuration file
+    tox -e genconfig
+
+``castellan/etc/castellan/castellan-functional.conf.sample`` is generated.
+It must be renamed to ``castellan-functional.conf`` and placed in
+``/etc/castellan``.
+
+The file should look something like the following:
+
+.. code-block:: bash
+
+    [DEFAULT]
+
+    [identity]
+    username = 'admin'
+    password = 'openstack'
+    project_name = 'admin'
+    auth_url = 'http://localhost:5000/v3'
+
+Once you have the appropriate services running and configured you can execute
+the functional tests through tox.
+
+.. code-block:: bash
+
+    # Execute Barbican Functional Tests
+    tox -e functional
+
+
+By default, the functional tox job will use ``testr`` to execute the
+functional tests.
+
+Pep8 Check
+----------
+
+Pep8 is a style guide for Python code. Castellan code should be have proper
+style before submission. In order to ensure that pep8 tests can be run through
+tox as follows:
+
+.. code-block:: bash
+
+    # Checks python code style
+    tox -e pep8
+
+Any comments on bad coding style will output to the terminal.