From a4891a68c4bc5f7b07eea9c5b21ed91fa82afb0d Mon Sep 17 00:00:00 2001 From: Fazeel Usmani Date: Wed, 12 Nov 2025 13:08:59 +0000 Subject: [PATCH 1/3] doc: Clarify conftest.py hooks unavailable during pytest_addoption Fixes #13304 --- AUTHORS | 1 + changelog/13304.doc.rst | 1 + doc/en/how-to/writing_hook_functions.rst | 21 ++++++++++++++++++++- 3 files changed, 22 insertions(+), 1 deletion(-) create mode 100644 changelog/13304.doc.rst diff --git a/AUTHORS b/AUTHORS index 83509281035..c1d5aab5593 100644 --- a/AUTHORS +++ b/AUTHORS @@ -165,6 +165,7 @@ Evgeny Seliverstov Fabian Sturm Fabien Zarifian Fabio Zadrozny +Fazeel Usmani Farbod Ahmadian faph Felix Hofstätter diff --git a/changelog/13304.doc.rst b/changelog/13304.doc.rst new file mode 100644 index 00000000000..f8090d4bbd3 --- /dev/null +++ b/changelog/13304.doc.rst @@ -0,0 +1 @@ +Clarified in the documentation that hook implementations defined in ``conftest.py`` files are not available during ``pytest_addoption()`` execution, as conftest files are discovered and loaded after plugin initialization. Only hooks from builtin plugins, plugins loaded via ``-p``, installed third-party plugins, or plugins from ``PYTEST_PLUGINS`` environment variable are accessible at that stage. diff --git a/doc/en/how-to/writing_hook_functions.rst b/doc/en/how-to/writing_hook_functions.rst index cd18301ce84..099c1171df0 100644 --- a/doc/en/how-to/writing_hook_functions.rst +++ b/doc/en/how-to/writing_hook_functions.rst @@ -285,13 +285,32 @@ and use pytest_addoption as follows: default=default_value, ) -The conftest.py that is using myplugin would simply define the hook as follows: +Another plugin (installed via setuptools entry points, or via the ``-p`` command-line +option) could then define the hook implementation to provide the default value: .. code-block:: python + # contents of third_party_plugin.py + def pytest_config_file_default_value(): return "config.yaml" +.. note:: + + **Hook implementations in conftest.py files are not available during** + ``pytest_addoption()``. This is because conftest.py files are discovered + and loaded *after* plugins are loaded and initialized (including the execution + of their ``pytest_addoption()`` hooks). See :ref:`pluginorder` for the plugin + discovery order. + + Only hook implementations from plugins that are loaded earlier will be available + during ``pytest_addoption()``. These include: + + * builtin plugins + * plugins explicitly loaded with ``-p`` on the command line + * installed third-party plugins (via setuptools entry points) + * plugins specified via the ``PYTEST_PLUGINS`` environment variable + Optionally using hooks from 3rd party plugins --------------------------------------------- From bc291f50140dcfd2256684c46391e6187caf3802 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 12 Nov 2025 13:19:04 +0000 Subject: [PATCH 2/3] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- doc/en/how-to/writing_hook_functions.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/en/how-to/writing_hook_functions.rst b/doc/en/how-to/writing_hook_functions.rst index 099c1171df0..881d6662bbe 100644 --- a/doc/en/how-to/writing_hook_functions.rst +++ b/doc/en/how-to/writing_hook_functions.rst @@ -292,6 +292,7 @@ option) could then define the hook implementation to provide the default value: # contents of third_party_plugin.py + def pytest_config_file_default_value(): return "config.yaml" From 0e5cc5e8a18dd06502a8e7a2abe91188859537de Mon Sep 17 00:00:00 2001 From: Fazeel Usmani Date: Thu, 13 Nov 2025 20:16:24 +0530 Subject: [PATCH 3/3] clarify conftest.py hook behavior during pytest_addoption --- changelog/13304.doc.rst | 2 +- doc/en/how-to/writing_hook_functions.rst | 20 +++++++++++++------- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/changelog/13304.doc.rst b/changelog/13304.doc.rst index f8090d4bbd3..665a61b8462 100644 --- a/changelog/13304.doc.rst +++ b/changelog/13304.doc.rst @@ -1 +1 @@ -Clarified in the documentation that hook implementations defined in ``conftest.py`` files are not available during ``pytest_addoption()`` execution, as conftest files are discovered and loaded after plugin initialization. Only hooks from builtin plugins, plugins loaded via ``-p``, installed third-party plugins, or plugins from ``PYTEST_PLUGINS`` environment variable are accessible at that stage. +Clarified in the documentation that hook implementations defined in ``conftest.py`` files are not available to other plugins during their ``pytest_addoption()`` execution, as conftest files are discovered and loaded after builtin and third-party plugins have been initialized. However, initial conftest files themselves can implement ``pytest_addoption()`` to add their own command-line options. diff --git a/doc/en/how-to/writing_hook_functions.rst b/doc/en/how-to/writing_hook_functions.rst index 881d6662bbe..fb459985b41 100644 --- a/doc/en/how-to/writing_hook_functions.rst +++ b/doc/en/how-to/writing_hook_functions.rst @@ -298,20 +298,26 @@ option) could then define the hook implementation to provide the default value: .. note:: - **Hook implementations in conftest.py files are not available during** - ``pytest_addoption()``. This is because conftest.py files are discovered - and loaded *after* plugins are loaded and initialized (including the execution - of their ``pytest_addoption()`` hooks). See :ref:`pluginorder` for the plugin - discovery order. + **Hook implementations in conftest.py files are not available to other plugins during** + **their** ``pytest_addoption()`` **execution**. This is because conftest.py files are + discovered and loaded *after* builtin plugins, third-party plugins, and command-line + plugins have already been initialized (including the execution of their + ``pytest_addoption()`` hooks). - Only hook implementations from plugins that are loaded earlier will be available - during ``pytest_addoption()``. These include: + However, :ref:`initial conftest files ` themselves *can* implement + ``pytest_addoption()`` to add their own command-line options. When an initial conftest + is loaded, its ``pytest_addoption()`` hook will be called immediately. + + During a plugin's ``pytest_addoption()`` execution, only hook implementations from + plugins that were loaded earlier will be available. These include: * builtin plugins * plugins explicitly loaded with ``-p`` on the command line * installed third-party plugins (via setuptools entry points) * plugins specified via the ``PYTEST_PLUGINS`` environment variable + See :ref:`pluginorder` for the complete plugin discovery order. + Optionally using hooks from 3rd party plugins ---------------------------------------------