From 8c93224475e6283cfb308d5cdf2b3ed951ceba65 Mon Sep 17 00:00:00 2001 From: pctablet505 Date: Wed, 15 Jul 2026 17:51:10 +0000 Subject: [PATCH] docs: document terminal-size inconsistency under -n Add a note to the known limitations explaining that workers replace stdio with pipes, so code that queries the terminal width sees the default size. Fixes #1208 --- changelog/1208.doc.rst | 1 + docs/known-limitations.rst | 10 ++++++++++ 2 files changed, 11 insertions(+) create mode 100644 changelog/1208.doc.rst diff --git a/changelog/1208.doc.rst b/changelog/1208.doc.rst new file mode 100644 index 00000000..5f0ae140 --- /dev/null +++ b/changelog/1208.doc.rst @@ -0,0 +1 @@ +Document that workers run with replaced standard streams and a default terminal size, so tests asserting on width-dependent output may need to monkeypatch the expected width. diff --git a/docs/known-limitations.rst b/docs/known-limitations.rst index 6dad018d..bfa5bfa3 100644 --- a/docs/known-limitations.rst +++ b/docs/known-limitations.rst @@ -69,3 +69,13 @@ 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. + +Terminal size +------------- + +Because ``pytest-xdist`` replaces the workers' standard streams with I/O pipes for its protocol, code that queries the terminal size (for example, ``shutil.get_terminal_size()`` or argparse help formatting) sees the default size instead of the actual terminal width. This can cause output to be formatted differently when using ``-n`` than when running plain ``pytest``. + +Workaround +~~~~~~~~~~ + +In tests that assert on such output, impose the expected width by monkeypatching ``shutil.get_terminal_size`` or by setting the ``COLUMNS`` environment variable for the subprocess that produces the output.