From 1c034de9aab97f43e3500515472825da5d84c1ab Mon Sep 17 00:00:00 2001
From: Doug Hellmann <doug@doughellmann.com>
Date: Thu, 24 Sep 2015 19:07:30 +0000
Subject: [PATCH] Add documentation about using oslo_debug_helper

Change-Id: I7fcae0676aaa2c598dbd14c0c7674d95357c4022
---
 doc/source/debugging.rst | 29 +++++++++++++++++++++++++++++
 doc/source/index.rst     |  1 +
 2 files changed, 30 insertions(+)
 create mode 100644 doc/source/debugging.rst

diff --git a/doc/source/debugging.rst b/doc/source/debugging.rst
new file mode 100644
index 0000000..b0e0450
--- /dev/null
+++ b/doc/source/debugging.rst
@@ -0,0 +1,29 @@
+=================
+ Debugging Tests
+=================
+
+Running tests through testrepository_ makes it difficult to use pdb for
+debugging them. oslotest includes ``oslo_debug_helper`` to make using
+pdb simpler/possible.
+
+First, add a pdb call to the test code::
+
+  import pdb; pdb.set_trace()
+
+Then run the tests through ``oslo_debug_helper`` like
+
+::
+
+  $ oslo_debug_helper [tests to run]
+
+or
+
+::
+
+  $ tox -e venv -- oslo_debug_helper [tests to run]
+
+.. seealso::
+
+   * https://wiki.openstack.org/wiki/Testr
+
+.. _testrepository: https://pypi.python.org/pypi/testrepository
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 2e3f9b0..40186ad 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -9,6 +9,7 @@
    testing
    features
    cross-testing
+   debugging
    resources
    contributing