diff --git a/changelog/13731.doc.rst b/changelog/13731.doc.rst new file mode 100644 index 00000000000..0cfdbebfc40 --- /dev/null +++ b/changelog/13731.doc.rst @@ -0,0 +1 @@ +Clarified that capture fixtures (e.g. ``capsys`` and ``capfd``) take precedence over the ``-s`` / ``--capture=no`` command-line options in :ref:`Accessing captured output from a test function `. diff --git a/doc/en/how-to/capture-stdout-stderr.rst b/doc/en/how-to/capture-stdout-stderr.rst index 14807b9b777..a80891b2ffd 100644 --- a/doc/en/how-to/capture-stdout-stderr.rst +++ b/doc/en/how-to/capture-stdout-stderr.rst @@ -109,6 +109,8 @@ of the failing function and hide the other one: FAILED test_module.py::test_func2 - assert False ======================= 1 failed, 1 passed in 0.12s ======================== +.. _accessing-captured-output: + Accessing captured output from a test function --------------------------------------------------- @@ -129,6 +131,17 @@ Here is an example test function that performs some output related checks: captured = capsys.readouterr() assert captured.out == "next\n" + +.. note:: + + When a capture fixture such as :fixture:`capsys` or :fixture:`capfd` is used, + it takes precedence over the global capturing configuration set via + command-line options such as ``-s`` or ``--capture=no``. + + This means that output produced within a test using a capture fixture will + still be captured and available via ``readouterr()``, even if global capturing + is disabled. + The ``readouterr()`` call snapshots the output so far - and capturing will be continued. After the test function finishes the original streams will