Merge "Make Client test documentation similar to Barbican"

3 files changed, 175 insertions, 64 deletions

diff --git a/doc/source/functional_tests.rst b/doc/source/functional_tests.rst
deleted file mode 100644
index 661d670..0000000
--- a/doc/source/functional_tests.rst
+++ /dev/null
@@ -1,63 +0,0 @@
-Running Functional Tests
-========================
-
-In order to run functional tests you must enter into the top-level directory
-of the python-barbicanclient and run:
-
-.. code-block:: bash
-
-    tox -e functional
-
-By default, the functional tox job will use nosetests to execute the functional
-tests. This is primarily due to nose being a very well known and common
-workflow among developers.
-
-Prerequisites
--------------
-
-In order to run functional tests, Barbican must be running and configured to
-use the Keystone Middleware. For more information on setting up this up
-please visit http://docs.openstack.org/developer/barbican/setup/keystone.html
-
-
-Functional Test Configuration
------------------------------
-
-A configuration file for functional tests must be edited before the tests
-can be run. In the top-level directory of the python-barbicanclient, edit
-``/etc/functional_tests.conf`` to the values you setup in Keystone.
-
-.. code-block:: bash
-
-    [DEFAULT]
-    # Leaving this as a placeholder
-
-    [keymanager]
-    # Replace values that represent barbican server and user information
-    url=http://localhost:9311
-    username=barbican
-    password=secretservice
-    project_name=service
-    project_id=service
-    #max_payload_size=10000
-    project_domain_name=Default
-
-    [identity]
-    # Replace these with values that represent your identity configuration
-    uri=http://localhost:5000/v2.0
-    uri_v3=http://localhost:5000/v3
-    auth_version=v3
-
-    username=admin
-    tenant_name=admin
-    password=password
-    domain_name=Default
-
-    admin_username=admin
-    admin_tenant_name=admin
-    admin_password=password
-    admin_domain_name=Default
-
-
-    [identity-feature-enabled]
-    # Leaving this as a placeholder
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 331c18e..d61f363 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -21,7 +21,7 @@ Contents:
    cli_usage
    reference
    contributing
-   functional_tests
+   testing
 
 Indices and tables
 ==================
diff --git a/doc/source/testing.rst b/doc/source/testing.rst
new file mode 100644
index 0000000..e94ce75
--- /dev/null
+++ b/doc/source/testing.rst
@@ -0,0 +1,174 @@
+Writing and Running Barbican Client Tests
+=========================================
+
+As a part of every code review that is submitted to the python-barbicanclient
+project there are a number of gating jobs which aid in the prevention of
+regression issues within python-barbicanclient. As a result, a
+python-barbicanclient developer should be familiar with running
+python-barbicanclient tests locally.
+
+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 Python 2.7. By default
+all available test environments within the tox configuration will execute
+when calling ``tox``. If you want to run them independently, you can do so
+with the following command:
+
+.. code-block:: bash
+
+    # Executes tests on Python 2.7
+    tox -e py27
+
+.. note::
+
+    If you do not have the appropriate Python versions available, consider
+    setting up PyEnv to install multiple versions of Python. See the
+    documentation regarding :doc:`/setup/dev` for more information.
+
+.. note::
+
+    Individual unit tests can also be run, using the following commands:
+
+    .. code-block:: bash
+
+        # runs a single test with the function named
+        # test_should_entity_str
+        tox -e py27 -- test_should_entity_str
+
+        # runs only tests in the WhenTestingSecrets class and
+        # the WhenTestingOrderManager class
+        tox -e py27 -- '(WhenTestingSecrets|WhenTestingOrderManager)'
+
+    The function name or class specified must be one located in the
+    `barbicanclient/tests` directory.
+
+    Groups of tests can also be run with a regex match after the ``--``.
+    For more information on what can be done with ``testr``, please see:
+    http://testrepository.readthedocs.org/en/latest/MANUAL.html
+
+You can also setup breakpoints in the unit tests. This can be done by
+adding ``import pdb; pdb.set_trace()`` to the line of the unit test you
+want to examine, then running the following command:
+
+.. code-block:: bash
+
+    # Executes tests on Python 2.7
+    tox -e debug
+
+.. note::
+
+    For a list of pdb commands, please see:
+    https://docs.python.org/2/library/pdb.html
+
+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 :doc:`setting up a Barbican development environment
+</setup/dev>` and using :doc:`Keystone with Barbican </setup/keystone>`,
+see our accompanying project documentation.
+
+A configuration file for functional tests must be edited before the tests
+can be run. In the top-level directory of the python-barbicanclient, edit
+``/etc/functional_tests.conf`` to the values you setup in Keystone.
+
+.. code-block:: bash
+
+    [DEFAULT]
+    # Leaving this as a placeholder
+
+    [keymanager]
+    # Replace values that represent barbican server and user information
+    url=http://localhost:9311
+    username=barbican
+    password=secretservice
+    project_name=service
+    project_id=service
+    #max_payload_size=10000
+    project_domain_name=Default
+
+    [identity]
+    # Replace these with values that represent your identity configuration
+    uri=http://localhost:5000/v2.0
+    uri_v3=http://localhost:5000/v3
+    auth_version=v3
+
+    username=admin
+    tenant_name=admin
+    password=password
+    domain_name=Default
+
+    admin_username=admin
+    admin_tenant_name=admin
+    admin_password=password
+    admin_domain_name=Default
+
+
+    [identity-feature-enabled]
+    # Leaving this as a placeholder
+
+
+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 nosetests to execute the functional
+tests. This is primarily due to nose being a very well known and common
+workflow among developers.
+
+.. note::
+
+    In order to run individual functional test functions, you must use the
+    following commands:
+
+    .. code-block:: bash
+
+        # runs only tests in the test_secrets.py file
+        tox -e functional -- client/v1/functional/test_secrets.py
+
+        # runs only tests in the SecretsTestCase class
+        tox -e functional -- client/v1/functional/test_secrets.py:\
+        SecretsTestCase
+
+        # runs a single test with the function named
+        # test_secret_create_defaults_check_content_types
+        tox -e functional -- client/v1/functional/test_secrets.py:\
+        SecretsTestCase.test_secret_create_defaults_check_content_types
+
+    The path specified must be one located in the `functionaltests`
+    directory.
+
+Remote Debugging
+----------------
+
+In order to be able to hit break-points on API calls, you must use remote
+debugging. This can be done by adding ``import rpdb; rpdb.set_trace()`` to
+the line of the API call you wish to test. For example, adding the breakpoint
+in ``def create`` in ``barbicanclient.secrets.py`` will allow you to hit the
+breakpoint whenever the ``create`` function is called.
+
+.. note::
+
+    After performing the ``POST`` the application will freeze. In order to use
+    ``rpdb``, you must open up another terminal and run the following:
+
+    .. code-block:: bash
+
+        # enter rpdb using telnet
+        telnet localhost 4444
+
+    Once in rpdb, you can use the same commands as pdb, as seen here:
+    https://docs.python.org/2/library/pdb.html