diff --git a/src/_pytest/hookspec.py b/src/_pytest/hookspec.py index 5edec31d5..0d552088a 100644 --- a/src/_pytest/hookspec.py +++ b/src/_pytest/hookspec.py @@ -170,28 +170,22 @@ def pytest_load_initial_conftests(early_config, parser, args): def pytest_collection(session: "Session") -> Optional[Any]: """Perform the collection protocol for the given session. - Usually plugins will implement this hook only to perform some action before - collection, for example the terminal plugin will use this to start displaying - the collection counter, so usually plugins return `None` from this hook after - performing the desired operation. - - However a plugin might decide to override the collection completely, - in which case it should return `True`, but then it is usually expected - that this hook will also need to perform the following operations - that are usually part of the collection process: - + Stops at first non-None result, see :ref:`firstresult`. + The return value is not used, but only stops further processing. + + The hook is meant to set `session.items` to a sequence of items at least, + but normally should follow this procedure: + 1. Call the pytest_collectstart hook. 2. Call the pytest_collectreport hook. 3. Call the pytest_collection_modifyitems hook. 4. Call the pytest_collection_finish hook. 5. Set session.testscollected to the amount of collect items. 6. Set `session.items` to a list of items. - - If a plugin just wants to skip collection entirely, like `pytest-xdist` - does for master nodes, then it is OK to not do anything other than - returning `True` from here. - Stops at first non-None result, see :ref:`firstresult`. + You can implement this hook to only perform some action before collection, + for example the terminal plugin uses it to start displaying the collection + counter (and returns `None`). :param _pytest.main.Session session: the pytest session object """