Export CollectReport and TestReport

Refs #7469.

changelog/7469.feature.rst

@@ -16,6 +16,8 @@ The newly-exported types are:
 - ``pytest.RecordedHookCall`` for the :class:`RecordedHookCall <pytest.HookRecorder>` type returned from :class:`~pytest.HookRecorder`.
 - ``pytest.RunResult`` for the :class:`RunResult <pytest.RunResult>` type returned from :class:`~pytest.Pytester`.
 - ``pytest.LineMatcher`` for the :class:`LineMatcher <pytest.RunResult>` type used in :class:`~pytest.RunResult` and others.
+- ``pytest.TestReport`` for the :class:`TestReport <pytest.TestReport>` type used in various hooks.
+- ``pytest.CollectReport`` for the :class:`CollectReport <pytest.CollectReport>` type used in various hooks.
 
 Constructing most of them directly is not supported; they are only meant for use in type annotations.
 Doing so will emit a deprecation warning, and may become a hard-error in pytest 8.0.

doc/en/reference/reference.rst

@@ -813,7 +813,7 @@ Collector
 CollectReport
 ~~~~~~~~~~~~~
 
-.. autoclass:: _pytest.reports.CollectReport()
+.. autoclass:: pytest.CollectReport()
     :members:
     :show-inheritance:
     :inherited-members:
@@ -951,7 +951,7 @@ Session
 TestReport
 ~~~~~~~~~~
 
-.. autoclass:: _pytest.reports.TestReport()
+.. autoclass:: pytest.TestReport()
     :members:
     :show-inheritance:
     :inherited-members:

src/_pytest/hookspec.py

@@ -323,7 +323,8 @@ def pytest_deselected(items: Sequence["Item"]) -> None:
 
 @hookspec(firstresult=True)
 def pytest_make_collect_report(collector: "Collector") -> "Optional[CollectReport]":
-    """Perform ``collector.collect()`` and return a CollectReport.
+    """Perform :func:`collector.collect() <pytest.Collector.collect>` and return
+    a :class:`~pytest.CollectReport`.
 
     Stops at first non-None result, see :ref:`firstresult`.
     """
@@ -522,19 +523,19 @@ def pytest_runtest_teardown(item: "Item", nextitem: Optional["Item"]) -> None:
 def pytest_runtest_makereport(
     item: "Item", call: "CallInfo[None]"
 ) -> Optional["TestReport"]:
-    """Called to create a :py:class:`_pytest.reports.TestReport` for each of
+    """Called to create a :class:`~pytest.TestReport` for each of
     the setup, call and teardown runtest phases of a test item.
 
     See :func:`pytest_runtest_protocol` for a description of the runtest protocol.
 
-    :param CallInfo[None] call: The ``CallInfo`` for the phase.
+    :param call: The :class:`~pytest.CallInfo` for the phase.
 
     Stops at first non-None result, see :ref:`firstresult`.
     """
 
 
 def pytest_runtest_logreport(report: "TestReport") -> None:
-    """Process the :py:class:`_pytest.reports.TestReport` produced for each
+    """Process the :class:`~pytest.TestReport` produced for each
     of the setup, call and teardown runtest phases of an item.
 
     See :func:`pytest_runtest_protocol` for a description of the runtest protocol.
@@ -555,7 +556,8 @@ def pytest_report_from_serializable(
     config: "Config",
     data: Dict[str, Any],
 ) -> Optional[Union["CollectReport", "TestReport"]]:
-    """Restore a report object previously serialized with pytest_report_to_serializable()."""
+    """Restore a report object previously serialized with
+    :func:`pytest_report_to_serializable`."""
 
 
 # -------------------------------------------------------------------------
@@ -753,7 +755,7 @@ def pytest_report_teststatus(
     for example ``"rerun", "R", ("RERUN", {"yellow": True})``.
 
     :param report: The report object whose status is to be returned.
-    :param pytest.Config config: The pytest config object.
+    :param config: The pytest config object.
 
     Stops at first non-None result, see :ref:`firstresult`.
     """
@@ -894,10 +896,10 @@ def pytest_exception_interact(
     interactively handled.
 
     May be called during collection (see :py:func:`pytest_make_collect_report`),
-    in which case ``report`` is a :py:class:`_pytest.reports.CollectReport`.
+    in which case ``report`` is a :class:`CollectReport`.
 
     May be called during runtest of an item (see :py:func:`pytest_runtest_protocol`),
-    in which case ``report`` is a :py:class:`_pytest.reports.TestReport`.
+    in which case ``report`` is a :class:`TestReport`.
 
     This hook is not called if the exception that was raised is an internal
     exception like ``skip.Exception``.

src/_pytest/reports.py

@@ -143,18 +143,22 @@ class BaseReport:
 
     @property
     def passed(self) -> bool:
+        """Whether the outcome is passed."""
         return self.outcome == "passed"
 
     @property
     def failed(self) -> bool:
+        """Whether the outcome is failed."""
         return self.outcome == "failed"
 
     @property
     def skipped(self) -> bool:
+        """Whether the outcome is skipped."""
         return self.outcome == "skipped"
 
     @property
     def fspath(self) -> str:
+        """The path portion of the reported node, as a string."""
         return self.nodeid.split("::")[0]
 
     @property
@@ -237,7 +241,10 @@ def _report_unserialization_failure(
 @final
 class TestReport(BaseReport):
     """Basic test report object (also used for setup and teardown calls if
-    they fail)."""
+    they fail).
+
+    Reports can contain arbitrary extra attributes.
+    """
 
     __test__ = False
 
@@ -354,7 +361,10 @@ class TestReport(BaseReport):
 
 @final
 class CollectReport(BaseReport):
-    """Collection report object."""
+    """Collection report object.
+
+    Reports can contain arbitrary extra attributes.
+    """
 
     when = "collect"
 

src/pytest/__init__.py

@@ -57,6 +57,8 @@ from _pytest.python_api import raises
 from _pytest.recwarn import deprecated_call
 from _pytest.recwarn import WarningsRecorder
 from _pytest.recwarn import warns
+from _pytest.reports import CollectReport
+from _pytest.reports import TestReport
 from _pytest.runner import CallInfo
 from _pytest.stash import Stash
 from _pytest.stash import StashKey
@@ -86,6 +88,7 @@ __all__ = [
     "cmdline",
     "collect",
     "Collector",
+    "CollectReport",
     "Config",
     "console_main",
     "deprecated_call",
@@ -143,6 +146,7 @@ __all__ = [
     "StashKey",
     "version_tuple",
     "TempPathFactory",
+    "TestReport",
     "UsageError",
     "WarningsRecorder",
     "warns",