From 354602abe6c06ec874cd091c56f0c548b17f796d Mon Sep 17 00:00:00 2001 From: Daniel Hahler Date: Thu, 2 Apr 2020 12:01:43 +0200 Subject: [PATCH] Update src/_pytest/hookspec.py Co-Authored-By: Bruno Oliveira --- src/_pytest/hookspec.py | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/src/_pytest/hookspec.py b/src/_pytest/hookspec.py index 6db543feb..5edec31d5 100644 --- a/src/_pytest/hookspec.py +++ b/src/_pytest/hookspec.py @@ -170,7 +170,26 @@ def pytest_load_initial_conftests(early_config, parser, args): def pytest_collection(session: "Session") -> Optional[Any]: """Perform the collection protocol for the given session. - The hook has to set `session.items` to a sequence of items. + 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: + + 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`.