Add tee-fd capture mode and capteefd fixtures

changelog/14159.feature.rst

@@ -0,0 +1 @@
+Added ``--capture=tee-fd`` capture mode and ``capteefd``/``capteefdbinary`` fixtures for FD-level capture with real-time terminal passthrough.

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

@@ -32,7 +32,7 @@ a test.
 Setting capturing methods or disabling capturing
 -------------------------------------------------
 
-There are three ways in which ``pytest`` can perform capturing:
+There are four ways in which ``pytest`` can perform capturing:
 
 * ``fd`` (file descriptor) level capturing (default): All writes going to the
   operating system file descriptors 1 and 2 will be captured.
@@ -46,6 +46,11 @@ There are three ways in which ``pytest`` can perform capturing:
   the actual ``sys.stdout`` and ``sys.stderr``. This allows output to be
   'live printed' and captured for plugin use, such as junitxml (new in pytest 5.4).
 
+* ``tee-fd`` capturing: All writes going to file descriptors 1 and 2 will be
+  captured, including subprocess output. The writes will also be passed-through
+  to the original file descriptors in real-time. This combines the subprocess
+  capture ability of ``fd`` with the live output visibility of ``tee-sys``.
+
 .. _`disable capturing`:
 
 You can influence output capturing mechanisms from the command line:
@@ -57,6 +62,7 @@ You can influence output capturing mechanisms from the command line:
     pytest --capture=fd        # also point filedescriptors 1 and 2 to temp file
     pytest --capture=tee-sys   # combines 'sys' and '-s', capturing sys.stdout/stderr
                                # and passing it along to the actual sys.stdout/stderr
+    pytest --capture=tee-fd    # like 'fd' but also passes output through in real-time
 
 .. _printdebugging:
 

doc/en/reference/fixtures.rst

@@ -39,6 +39,14 @@ Built-in fixtures
    :fixture:`capsysbinary`
         Capture, as bytes, output to ``sys.stdout`` and ``sys.stderr``.
 
+   :fixture:`capteefd`
+        Capture, as text, output to file descriptors 1 and 2, with real-time
+        pass-through.
+
+   :fixture:`capteefdbinary`
+        Capture, as bytes, output to file descriptors 1 and 2, with real-time
+        pass-through.
+
    :fixture:`cache`
         Store and retrieve values across pytest runs.
 

doc/en/reference/reference.rst

@@ -422,6 +422,26 @@ capteesys
 .. autofunction:: _pytest.capture.capteesys()
     :no-auto-options:
 
+.. fixture:: capteefd
+
+capteefd
+~~~~~~~~
+
+**Tutorial**: :ref:`captures`
+
+.. autofunction:: _pytest.capture.capteefd()
+    :no-auto-options:
+
+.. fixture:: capteefdbinary
+
+capteefdbinary
+~~~~~~~~~~~~~~
+
+**Tutorial**: :ref:`captures`
+
+.. autofunction:: _pytest.capture.capteefdbinary()
+    :no-auto-options:
+
 .. fixture:: capsysbinary
 
 capsysbinary
@@ -3111,7 +3131,8 @@ Output Capture
     * ``fd``: capture at file descriptor level (default)
     * ``sys``: capture at sys level
     * ``no``: don't capture output
-    * ``tee-sys``: capture but also show output on terminal
+    * ``tee-sys``: capture sys level but also show output on terminal
+    * ``tee-fd``: capture fd level but also show output on terminal
 
     See :ref:`captures`.