Docs: collection hooks listed under reporting hooks

[soxofaan]

In the docs, under "reporting hooks" I see a couple of hooks that I would expect under "collection hooks":

• pytest_collectstart
• pytest_make_collect_report
• pytest_itemcollected
• pytest_collectreport
• pytest_deselected

pytest/doc/en/reference/reference.rst

Lines 759 to 773 in 6c806b4

	Reporting hooks
	~~~~~~~~~~~~~~~
	Session related reporting hooks:
	.. hook:: pytest_collectstart
	.. autofunction:: pytest_collectstart
	.. hook:: pytest_make_collect_report
	.. autofunction:: pytest_make_collect_report
	.. hook:: pytest_itemcollected
	.. autofunction:: pytest_itemcollected
	.. hook:: pytest_collectreport
	.. autofunction:: pytest_collectreport
	.. hook:: pytest_deselected
	.. autofunction:: pytest_deselected

is that intended for some reason?

[soxofaan]

And while looking at it, some more hooks that look out of place in this section:

• pytest_fixture_setup
• pytest_fixture_post_finalizer
• pytest_runtest_logreport

Maybe they better fit under "Test running (runtest) hooks"?

[nicoddemus]

Hi,

is that intended for some reason?

The rationale is that those hooks "report" events (item collected, header, test status, etc), while the "collection" hooks actually perform the collection itself.

And while looking at it, some more hooks that look out of place in this section:

You are right, pytest_fixture_setup and pytest_fixture_post_finalizer do seem like they belong in "Test running (runtest) hooks", but I would keep pytest_runtest_logreport there as it is about reporting the status of a test.

[soxofaan]

The rationale is that those hooks "report" events (item collected, header, test status, etc), while the "collection" hooks actually perform the collection itself.

Ok thanks for the quick response, that clarifies the current state.
Still, if pytest_collectstart is a for reporting a start event, isn't that also true for pytest_sessionstart and pytest_runtest_logstart?

I guess a hook has multiple aspects which can be used for categorizing: what phase of the test suite are they about (collection, running, reporting), what scope do they have (session, fixture, node, report), are they about manipulating inputs or outcomes or just simple reporting, ...
That easily leads to mismatching mental models of course 😄

Another subtlety that might play here: if you talk about "reporting": is that about pytest reporting an event to a plugin, or about giving plugins the opportunity to report outcomes to the user?

[nicoddemus]

Another subtlety that might play here: if you talk about "reporting": is that about pytest reporting an event to a plugin, or about giving plugins the opportunity to report outcomes to the user?

Usually it is in the pytest -> plugin direction, and the plugin decides what to do with it.