Serialization hooks

changelog/4965.trivial.rst

@@ -0,0 +1,9 @@
+New ``pytest_report_serialize`` and ``pytest_report_unserialize`` **experimental** hooks.
+
+These hooks will be used by ``pytest-xdist``, ``pytest-subtests``, and the replacement for
+resultlog to serialize and customize reports.
+
+They are experimental, meaning that their details might change or even be removed
+completely in future patch releases without warning.
+
+Feedback is welcome from plugin authors and users alike.

src/_pytest/config/__init__.py

@@ -140,6 +140,7 @@ def directory_arg(path, optname):
     "stepwise",
     "warnings",
     "logging",
+    "reports",
 )
 
 

src/_pytest/hookspec.py

@@ -375,6 +375,41 @@ def pytest_runtest_logreport(report):
     the respective phase of executing a test. """
 
 
+@hookspec(firstresult=True)
+def pytest_report_serialize(config, report):
+    """
+    .. warning::
+        This hook is experimental and subject to change between pytest releases, even
+        bug fixes.
+
+        The intent is for this to be used by plugins maintained by the core-devs, such
+        as ``pytest-xdist``, ``pytest-subtests``, and as a replacement for the internal
+        'resultlog' plugin.
+
+        In the future it might become part of the public hook API.
+
+    Serializes the given report object into a data structure suitable for sending
+    over the wire, e.g. converted to JSON.
+    """
+
+
+@hookspec(firstresult=True)
+def pytest_report_unserialize(config, data):
+    """
+    .. warning::
+        This hook is experimental and subject to change between pytest releases, even
+        bug fixes.
+
+        The intent is for this to be used by plugins maintained by the core-devs, such
+        as ``pytest-xdist``, ``pytest-subtests``, and as a replacement for the internal
+        'resultlog' plugin.
+
+        In the future it might become part of the public hook API.
+
+    Restores a report object previously serialized with pytest_report_serialize().
+    """
+
+
 # -------------------------------------------------------------------------
 # Fixture related hooks
 # -------------------------------------------------------------------------

src/_pytest/reports.py

@@ -1,8 +1,19 @@
+from pprint import pprint
+
 import py
+import six
 
 from _pytest._code.code import ExceptionInfo
+from _pytest._code.code import ReprEntry
+from _pytest._code.code import ReprEntryNative
+from _pytest._code.code import ReprExceptionInfo
+from _pytest._code.code import ReprFileLocation
+from _pytest._code.code import ReprFuncArgs
+from _pytest._code.code import ReprLocals
+from _pytest._code.code import ReprTraceback
 from _pytest._code.code import TerminalRepr
 from _pytest.outcomes import skip
+from _pytest.pathlib import Path
 
 
 def getslaveinfoline(node):
@@ -137,12 +148,136 @@ def head_line(self):
             fspath, lineno, domain = self.location
             return domain
 
+    def _to_json(self):
+        """
+        This was originally the serialize_report() function from xdist (ca03269).
+
+        Returns the contents of this report as a dict of builtin entries, suitable for
+        serialization.
+
+        Experimental method.
+        """
+
+        def disassembled_report(rep):
+            reprtraceback = rep.longrepr.reprtraceback.__dict__.copy()
+            reprcrash = rep.longrepr.reprcrash.__dict__.copy()
+
+            new_entries = []
+            for entry in reprtraceback["reprentries"]:
+                entry_data = {
+                    "type": type(entry).__name__,
+                    "data": entry.__dict__.copy(),
+                }
+                for key, value in entry_data["data"].items():
+                    if hasattr(value, "__dict__"):
+                        entry_data["data"][key] = value.__dict__.copy()
+                new_entries.append(entry_data)
+
+            reprtraceback["reprentries"] = new_entries
+
+            return {
+                "reprcrash": reprcrash,
+                "reprtraceback": reprtraceback,
+                "sections": rep.longrepr.sections,
+            }
+
+        d = self.__dict__.copy()
+        if hasattr(self.longrepr, "toterminal"):
+            if hasattr(self.longrepr, "reprtraceback") and hasattr(
+                self.longrepr, "reprcrash"
+            ):
+                d["longrepr"] = disassembled_report(self)
+            else:
+                d["longrepr"] = six.text_type(self.longrepr)
+        else:
+            d["longrepr"] = self.longrepr
+        for name in d:
+            if isinstance(d[name], (py.path.local, Path)):
+                d[name] = str(d[name])
+            elif name == "result":
+                d[name] = None  # for now
+        return d
+
+    @classmethod
+    def _from_json(cls, reportdict):
+        """
+        This was originally the serialize_report() function from xdist (ca03269).
+
+        Factory method that returns either a TestReport or CollectReport, depending on the calling
+        class. It's the callers responsibility to know which class to pass here.
+
+        Experimental method.
+        """
+        if reportdict["longrepr"]:
+            if (
+                "reprcrash" in reportdict["longrepr"]
+                and "reprtraceback" in reportdict["longrepr"]
+            ):
+
+                reprtraceback = reportdict["longrepr"]["reprtraceback"]
+                reprcrash = reportdict["longrepr"]["reprcrash"]
+
+                unserialized_entries = []
+                reprentry = None
+                for entry_data in reprtraceback["reprentries"]:
+                    data = entry_data["data"]
+                    entry_type = entry_data["type"]
+                    if entry_type == "ReprEntry":
+                        reprfuncargs = None
+                        reprfileloc = None
+                        reprlocals = None
+                        if data["reprfuncargs"]:
+                            reprfuncargs = ReprFuncArgs(**data["reprfuncargs"])
+                        if data["reprfileloc"]:
+                            reprfileloc = ReprFileLocation(**data["reprfileloc"])
+                        if data["reprlocals"]:
+                            reprlocals = ReprLocals(data["reprlocals"]["lines"])
+
+                        reprentry = ReprEntry(
+                            lines=data["lines"],
+                            reprfuncargs=reprfuncargs,
+                            reprlocals=reprlocals,
+                            filelocrepr=reprfileloc,
+                            style=data["style"],
+                        )
+                    elif entry_type == "ReprEntryNative":
+                        reprentry = ReprEntryNative(data["lines"])
+                    else:
+                        _report_unserialization_failure(entry_type, cls, reportdict)
+                    unserialized_entries.append(reprentry)
+                reprtraceback["reprentries"] = unserialized_entries
+
+                exception_info = ReprExceptionInfo(
+                    reprtraceback=ReprTraceback(**reprtraceback),
+                    reprcrash=ReprFileLocation(**reprcrash),
+                )
+
+                for section in reportdict["longrepr"]["sections"]:
+                    exception_info.addsection(*section)
+                reportdict["longrepr"] = exception_info
+
+        return cls(**reportdict)
+
+
+def _report_unserialization_failure(type_name, report_class, reportdict):
+    url = "https://github.com/pytest-dev/pytest/issues"
+    stream = py.io.TextIO()
+    pprint("-" * 100, stream=stream)
+    pprint("INTERNALERROR: Unknown entry type returned: %s" % type_name, stream=stream)
+    pprint("report_name: %s" % report_class, stream=stream)
+    pprint(reportdict, stream=stream)
+    pprint("Please report this bug at %s" % url, stream=stream)
+    pprint("-" * 100, stream=stream)
+    raise RuntimeError(stream.getvalue())
+
 
 class TestReport(BaseReport):
     """ Basic test report object (also used for setup and teardown calls if
     they fail).
     """
 
+    __test__ = False
+
     def __init__(
         self,
         nodeid,
@@ -272,3 +407,19 @@ def __init__(self, msg):
 
     def toterminal(self, out):
         out.line(self.longrepr, red=True)
+
+
+def pytest_report_serialize(report):
+    if isinstance(report, (TestReport, CollectReport)):
+        data = report._to_json()
+        data["_report_type"] = report.__class__.__name__
+        return data
+
+
+def pytest_report_unserialize(data):
+    if "_report_type" in data:
+        if data["_report_type"] == "TestReport":
+            return TestReport._from_json(data)
+        elif data["_report_type"] == "CollectReport":
+            return CollectReport._from_json(data)
+        assert "Unknown report_type unserialize data: {}".format(data["_report_type"])