Merge "Allow debug flag in Barbican tox and debugging documentation"

doc/source/testing.rst

@@ -18,7 +18,7 @@ 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 commands
+with the following command:
 
 .. code-block:: bash
 
@@ -32,6 +32,20 @@ with the following commands
     setting up PyEnv to install multiple versions of Python. See the
     documentation regarding :doc:`/setup/dev` for more information.
 
+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
 -----------------
 
@@ -57,3 +71,27 @@ job will actually use ``testr`` instead of ``nosetests``. If you discover
 issues while running your tests in the gate, then consider running ``testr``
 or :doc:`Devstack</setup/devstack>` to more closely replicate the gating
 environment.
+
+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 on_post`` in ``barbican.api.controllers.secrets.py``
+will allow you to hit the breakpoint when a ``POST`` is done on the
+secrets URL.
+
+..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
+

tox.ini

@@ -38,6 +38,9 @@ commands = flake8 {posargs}
 [testenv:venv]
 commands = {posargs}
 
+[testenv:debug]
+commands = oslo_debug_helper {posargs}
+
 [testenv:py3pep8]
 # This hack is in place to allow us to run py3 based flake8
 # without installing barbican.