From 017cc72b7090dc4bb7e7ad3d0caab024feb977a8 Mon Sep 17 00:00:00 2001 From: Thomas Kolar Date: Thu, 12 Jan 2023 16:57:20 +0100 Subject: [PATCH] Document limitations for debugging as well as a workaround (#867) Closes #863 --- changelog/863.doc | 1 + docs/known-limitations.rst | 7 +++++++ 2 files changed, 8 insertions(+) create mode 100644 changelog/863.doc diff --git a/changelog/863.doc b/changelog/863.doc new file mode 100644 index 00000000..d509be12 --- /dev/null +++ b/changelog/863.doc @@ -0,0 +1 @@ +Document limitations for debugging due to standard I/O of workers not being forwarded. Also, mention remote debugging as a possible workaround. diff --git a/docs/known-limitations.rst b/docs/known-limitations.rst index 335544d2..6dad018d 100644 --- a/docs/known-limitations.rst +++ b/docs/known-limitations.rst @@ -62,3 +62,10 @@ The ``-s``/``--capture=no`` option is meant to disable pytest capture, so users However, this option does not work with ``pytest-xdist`` because `execnet `__ the underlying library used for communication between master and workers, does not support transferring stdout/stderr from workers. Currently, there are no plans to support this in ``pytest-xdist``. + +Debugging +~~~~~~~~~ + +This also means that debugging using PDB (or any other debugger that wants to use standard I/O) will not work. The ``--pdb`` option is disabled when distributing tests with ``pytest-xdist`` for this reason. + +It is generally likely best to use ``pytest-xdist`` to find failing tests and then debug them without distribution; however, if you need to debug from within a worker process (for example, to address failures that only happen when running tests concurrently), remote debuggers (for example, `python-remote-pdb `__ or `python-web-pdb `__) have been reported to work for this purpose.