Add capteesys capture fixture to bubble up output to --capture handler

doc/en/how-to/capture-stdout-stderr.rst

@@ -4,14 +4,10 @@
 How to capture stdout/stderr output
 =========================================================
 
-Pytest can intercept stdout and stderr. Using the `--capture=` command-line
-argument (described below) allows pytest to add captured output to reports
-generated after tests. The reports can customized by `-r` (described below).
-
-Built-in fixtures (also described below) can be passed to tests as arguments
-to capture stdout and stderr and make it accessible to the developer during
-the test for inspection. It will not be available for reports if it is captured,
-unless it is re-printed with capturing turned off (see below).
+Pytest can intercept stdout and stderr by using the ``--capture=`` command-line
+or argument or by using fixtures. The flag ``--capture=`` configures reporting,
+whereas the fixtures offer somewhat more granular control and allow inspection
+during testing. The reports can customized with the `-r flag <../reference/reference.html#command-line-flags>`_.
 
 Default stdout/stderr/stdin capturing behaviour
 ---------------------------------------------------------

doc/en/reference/fixtures.rst

@@ -32,6 +32,10 @@ Built-in fixtures
    :fixture:`capsys`
         Capture, as text, output to ``sys.stdout`` and ``sys.stderr``.
 
+   :fixture:`capteesys`
+        Capture in the same manner as :fixture:`capsys`, but also pass text
+        through according to ``--capture=``.
+
    :fixture:`capsysbinary`
         Capture, as bytes, output to ``sys.stdout`` and ``sys.stderr``.
 

doc/en/reference/reference.rst

@@ -402,6 +402,16 @@ capsys
 .. autoclass:: pytest.CaptureFixture()
     :members:
 
+.. fixture:: capteesys
+
+capteesys
+~~~~~~~~~
+
+**Tutorial**: :ref:`captures`
+
+.. autofunction:: _pytest.capture.capteesys()
+    :no-auto-options:
+
 .. fixture:: capsysbinary
 
 capsysbinary

src/_pytest/capture.py

@@ -1007,14 +1007,15 @@ def test_output(capsys):
 @fixture
 def capteesys(request: SubRequest) -> Generator[CaptureFixture[str]]:
     r"""Enable simultaneous text capturing and pass-through of writes
-    to ``sys.stdout`` and ``sys.stderr``.
+    to ``sys.stdout`` and ``sys.stderr`` as defined by ``--capture=``.
 
 
     The captured output is made available via ``capteesys.readouterr()`` method
     calls, which return a ``(out, err)`` namedtuple.
     ``out`` and ``err`` will be ``text`` objects.
 
-    The output is also passed-through, allowing it to be "live-printed".
+    The output is also passed-through, allowing it to be "live-printed",
+    reported, or both as defined by ``--capture=``.
 
     Returns an instance of :class:`CaptureFixture[str] <pytest.CaptureFixture>`.