Preserve chronological order of stdout and stderr with capsys.

Author: aklajnert

changelog/5449.feature.rst

@@ -0,0 +1 @@
+Allow ``capsys`` to retrieve combined stdout + stderr streams with original order of messages.

doc/en/capture.rst

@@ -170,3 +170,41 @@ as a context manager, disabling capture inside the ``with`` block:
         with capsys.disabled():
             print("output not captured, going directly to sys.stdout")
         print("this output is also captured")
+
+
+Preserving streams order
+------------------------
+
+By default, the ``readouterr()`` method returns two values - one for ``stdout`` and one for ``stderr``. This
+can be problematic if you want to ensure that all messages were in correct order regardless of the stream.
+When using ``capsys`` you can use ``combine=True`` to have both streams returned with the chronological order
+of messages preserved. The output will still be a tuple, but the second argument will be ``None``.
+
+.. code-block:: python
+
+    def test_combine(capsys):
+        print("I'm in stdout")
+        print("I'm in stderr", file=sys.stderr)
+        print("Hey, stdout again!")
+
+        out, err = capsys.readouterr(combined=True)
+
+        assert out == "I'm in stdout\nI'm in stderr\nHey, stdout again!\n"
+        assert err is None
+
+If you care about correct order and want to make sure that certain message went into correct stream, you can
+use ``flush=False`` with ``readouterr()`` so you will be able to retrieve streams twice:
+
+.. code-block:: python
+
+    def test_no_flush(capsys):
+        print("I'm in stdout")
+        print("I'm in stderr", file=sys.stderr)
+        print("Hey, stdout again!")
+
+        out, err = capsys.readouterr(flush=False)
+        combined, _ = capsys.readouterr(combined=True)
+
+        assert out == "I'm in stdout\nHey, stdout again!\n"
+        assert err == "I'm in stderr\n"
+        assert combined == "I'm in stdout\nI'm in stderr\nHey, stdout again!\n"

src/_pytest/capture.py

@@ -348,11 +348,17 @@ def close(self):
             self._capture.stop_capturing()
             self._capture = None
 
-    def readouterr(self):
+    def readouterr(self, combined: bool = False, flush: bool = True) -> "CaptureResult":
         """Read and return the captured output so far, resetting the internal buffer.
 
         :return: captured content as a namedtuple with ``out`` and ``err`` string attributes
         """
+        if flush is False:
+            if self.captureclass is not OrderedCapture:
+                raise AttributeError("Only capsys can read streams without flushing.")
+            OrderedCapture.set_flush(False)
+        if combined:
+            return CaptureResult(self._get_combined(), None)
         captured_out, captured_err = self._captured_out, self._captured_err
         if self._capture is not None:
             out, err = self._capture.readouterr()
@@ -362,6 +368,13 @@ def readouterr(self):
         self._captured_err = self.captureclass.EMPTY_BUFFER
         return CaptureResult(captured_out, captured_err)
 
+    def _get_combined(self):
+        if self.captureclass is not OrderedCapture:
+            raise AttributeError("Only capsys is able to combine streams.")
+        result = "".join(line[0] for line in OrderedCapture.streams)
+        OrderedCapture.flush()
+        return result
+
     def _suspend(self):
         """Suspends this fixture's own capturing temporarily."""
         if self._capture is not None:
@@ -604,13 +617,17 @@ def __init__(self, fd, tmpfile=None):
         name = patchsysdict[fd]
         self._old = getattr(sys, name)
         self.name = name
+        self.fd = fd
         if tmpfile is None:
             if name == "stdin":
                 tmpfile = DontReadFromInput()
             else:
-                tmpfile = CaptureIO()
+                tmpfile = self._get_writer()
         self.tmpfile = tmpfile
 
+    def _get_writer(self):
+        return CaptureIO()
+
     def __repr__(self):
         return "<{} {} _old={} _state={!r} tmpfile={!r}>".format(
             self.__class__.__name__,
@@ -677,14 +694,74 @@ def __init__(self, fd, tmpfile=None):
         self.tmpfile = tmpfile
 
 
+class OrderedCapture(SysCapture):
+    """Capture class that keeps streams in order."""
+
+    streams = collections.deque()  # type: collections.deque
+    _flush = True
+
+    def _get_writer(self):
+        return OrderedWriter(self.fd)
+
+    def snap(self):
+        res = self.tmpfile.getvalue()
+        if self.name == "stderr":
+            # both streams are being read one after another, while stderr is last - it will clear the queue
+            self.flush()
+        return res
+
+    @classmethod
+    def set_flush(cls, flush: bool) -> None:
+        cls._flush = flush
+
+    @classmethod
+    def flush(cls) -> None:
+        """Clear streams."""
+        if cls._flush is False:
+            cls.set_flush(True)
+        else:
+            cls.streams.clear()
+
+    @classmethod
+    def close(cls) -> None:
+        cls.set_flush(True)
+        cls.flush()
+
+
 map_fixname_class = {
     "capfd": FDCapture,
     "capfdbinary": FDCaptureBinary,
-    "capsys": SysCapture,
+    "capsys": OrderedCapture,
     "capsysbinary": SysCaptureBinary,
 }
 
 
+class OrderedWriter:
+    encoding = sys.getdefaultencoding()
+
+    def __init__(self, fd: int) -> None:
+        super().__init__()
+        self._fd = fd  # type: int
+
+    def write(self, text: str, **kwargs) -> int:
+        OrderedCapture.streams.append((text, self._fd))
+        return len(text)
+
+    def getvalue(self) -> str:
+        return "".join(
+            line[0] for line in OrderedCapture.streams if line[1] == self._fd
+        )
+
+    def flush(self) -> None:
+        pass
+
+    def isatty(self) -> bool:
+        return False
+
+    def close(self) -> None:
+        OrderedCapture.close()
+
+
 class DontReadFromInput:
     encoding = None
 

testing/test_capture.py

@@ -1493,3 +1493,45 @@ def test__get_multicapture() -> None:
     pytest.raises(ValueError, _get_multicapture, "unknown").match(
         r"^unknown capturing method: 'unknown'"
     )
+
+
+def test_combined_streams(capsys):
+    """Show that capsys is capable of preserving chronological order of streams."""
+    print("stdout1")
+    print("stdout2")
+    print("stderr1", file=sys.stderr)
+    print("stdout3")
+    print("stderr2", file=sys.stderr)
+    print("stderr3", file=sys.stderr)
+    print("stdout4")
+    print("stdout5")
+
+    # this won't clear streams
+    out, err = capsys.readouterr(flush=False)
+    assert "stdout1" in out
+    assert "stdout1" not in err
+    assert "stderr1" in err
+    assert "stderr1" not in out
+
+    out, err = capsys.readouterr(combined=True)
+    assert (
+        out == "stdout1\n"
+        "stdout2\n"
+        "stderr1\n"
+        "stdout3\n"
+        "stderr2\n"
+        "stderr3\n"
+        "stdout4\n"
+        "stdout5\n"
+    )
+    assert err is None
+
+
+def test_no_capsys_exceptions(capfd):
+    with pytest.raises(AttributeError, match="Only capsys is able to combine streams."):
+        capfd.readouterr(combined=True)
+
+    with pytest.raises(
+        AttributeError, match="Only capsys can read streams without flushing."
+    ):
+        capfd.readouterr(flush=False)