launchpad-reviewers team mailing list archive

[Jürgen Gmach <mp+415501@xxxxxxxxxxxxxxxxxx>]

Jürgen Gmach has proposed merging ~jugmac00/launchpad:how-to-avoid-debugging-errors-when-running-a-layer-in-a-subprocess into launchpad:master.

Commit message:
Add "How to avoid debugging issues" how-to

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)

For more details, see:
https://code.launchpad.net/~jugmac00/launchpad/+git/launchpad/+merge/415501
-- 
Your team Launchpad code reviewers is requested to review the proposed merge of ~jugmac00/launchpad:how-to-avoid-debugging-errors-when-running-a-layer-in-a-subprocess into launchpad:master.

diff --git a/doc/how-to/avoid-debugging-issues.rst b/doc/how-to/avoid-debugging-issues.rst
new file mode 100644
index 0000000..bbaaf7a
--- /dev/null
+++ b/doc/how-to/avoid-debugging-issues.rst
@@ -0,0 +1,21 @@
+=============================
+How to avoid debugging issues
+=============================
+
+
+When you set a breakpoint, e.g. via ``import pdb;pdb.set_trace()``
+and run a collection of tests,
+you may receive the following message:
+
+.. code-block:: shell-session
+
+    Can't use pdb.set_trace when running a layer as a subprocess!
+
+This happens when you are running a collection of tests which span multiple layers,
+and a previous layer could not be safely torn down in-process,
+so the testrunner had to spawn a subprocess instead.
+
+The workaround is to run just the one test you are trying to debug.
+
+You can read more about this issue in `zope.testrunner's documentation
+<https://zopetestrunner.readthedocs.io/en/latest/testrunner-layers-ntd.html>`_.
diff --git a/doc/index.rst b/doc/index.rst
index 399ca93..2cd472c 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -32,6 +32,7 @@ How-to Guides
    how-to/exceptions
    how-to/security
    how-to/new-user
+   how-to/avoid-debugging-issues
 
 Explanation
 ===========