diff --git a/changelog/7469.feature.rst b/changelog/7469.feature.rst index d1dd8359b85..4694e97e9d9 100644 --- a/changelog/7469.feature.rst +++ b/changelog/7469.feature.rst @@ -16,6 +16,8 @@ The newly-exported types are: - ``pytest.RecordedHookCall`` for the :class:`RecordedHookCall ` type returned from :class:`~pytest.HookRecorder`. - ``pytest.RunResult`` for the :class:`RunResult ` type returned from :class:`~pytest.Pytester`. - ``pytest.LineMatcher`` for the :class:`LineMatcher ` type used in :class:`~pytest.RunResult` and others. +- ``pytest.TestReport`` for the :class:`TestReport ` type used in various hooks. +- ``pytest.CollectReport`` for the :class:`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. diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index f90070acb75..00b9d308c8a 100644 --- a/doc/en/reference/reference.rst +++ b/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: diff --git a/src/_pytest/hookspec.py b/src/_pytest/hookspec.py index e3cfc07186e..ee9553e0f77 100644 --- a/src/_pytest/hookspec.py +++ b/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() ` 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``. diff --git a/src/_pytest/reports.py b/src/_pytest/reports.py index 983f27d2780..282682c47ba 100644 --- a/src/_pytest/reports.py +++ b/src/_pytest/reports.py @@ -143,18 +143,22 @@ def capstderr(self) -> str: @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 @@ def from_item_and_call(cls, item: Item, call: "CallInfo[None]") -> "TestReport": @final class CollectReport(BaseReport): - """Collection report object.""" + """Collection report object. + + Reports can contain arbitrary extra attributes. + """ when = "collect" diff --git a/src/pytest/__init__.py b/src/pytest/__init__.py index 83a0df11c36..69aa90fdd9f 100644 --- a/src/pytest/__init__.py +++ b/src/pytest/__init__.py @@ -57,6 +57,8 @@ 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 @@ "cmdline", "collect", "Collector", + "CollectReport", "Config", "console_main", "deprecated_call", @@ -143,6 +146,7 @@ "StashKey", "version_tuple", "TempPathFactory", + "TestReport", "UsageError", "WarningsRecorder", "warns",