From c65c3ebbb0cdeb21fcfbcaefa8dc514001fbcde4 Mon Sep 17 00:00:00 2001 From: T Date: Tue, 13 Oct 2026 20:45:05 +0100 Subject: [PATCH] docs: clarify the purpose of reporting hooks Explain collection event notifications and link the hook reference sections. Co-authored-by: Codex --- doc/en/reference/reference.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst index 4e0f40f4f93..40c0d1de3c6 100644 --- a/doc/en/reference/reference.rst +++ b/doc/en/reference/reference.rst @@ -721,9 +721,14 @@ Initialization hooks called for plugins and ``conftest.py`` files. .. hook:: pytest_plugin_registered .. autofunction:: pytest_plugin_registered +.. _`collection-hooks`: + Collection hooks ~~~~~~~~~~~~~~~~ +Hooks that report collection events, such as :hook:`pytest_collectstart` and +:hook:`pytest_itemcollected`, are listed under :ref:`reporting-hooks`. + ``pytest`` calls the following hooks for collecting files and directories: .. hook:: pytest_collection @@ -800,9 +805,17 @@ into interactive debugging when a test failure occurs. .. hook:: pytest_pyfunc_call .. autofunction:: pytest_pyfunc_call +.. _`reporting-hooks`: + Reporting hooks ~~~~~~~~~~~~~~~ +Reporting hooks let plugins observe events and reports from pytest, including +events during collection and test execution. A plugin can use these notifications +to produce output, but implementing a reporting hook does not require displaying +anything to the user. Hooks that perform or modify collection are listed under +:ref:`collection-hooks`. + Session related reporting hooks: .. hook:: pytest_collectstart