From 541b30a044fb709e6ab7c7b202237b0d75c7a34e Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Sat, 12 Sep 2020 14:11:43 -0300 Subject: [PATCH 1/2] Improve docs about plugin discovery/loading at startup Fix #7691 --- doc/en/writing_plugins.rst | 36 ++++++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/doc/en/writing_plugins.rst b/doc/en/writing_plugins.rst index cf4dbf99f..ee500253d 100644 --- a/doc/en/writing_plugins.rst +++ b/doc/en/writing_plugins.rst @@ -33,26 +33,34 @@ Plugin discovery order at tool startup ``pytest`` loads plugin modules at tool startup in the following way: -* by loading all builtin plugins +1. by scanning the command line for the ``-p no:name`` option + and *blocking* that plugin from being loaded (even builtin plugins can + be blocked this way). This happens before normal command-line parsing. -* by loading all plugins registered through `setuptools entry points`_. +2. by loading all builtin plugins. -* by pre-scanning the command line for the ``-p name`` option - and loading the specified plugin before actual command line parsing. +3. by scanning the command line for the ``-p name`` option + and loading the specified plugin. This happens before normal command-line parsing. -* by loading all :file:`conftest.py` files as inferred by the command line - invocation: +4. by loading all plugins registered through `setuptools entry points`_. - - if no test paths are specified use current dir as a test path - - if exists, load ``conftest.py`` and ``test*/conftest.py`` relative - to the directory part of the first test path. +5. by loading all plugins specified through the :envvar:`PYTEST_PLUGINS` environment variable. - Note that pytest does not find ``conftest.py`` files in deeper nested - sub directories at tool startup. It is usually a good idea to keep - your ``conftest.py`` file in the top level test or project root directory. +6. by loading all :file:`conftest.py` files as inferred by the command line + invocation: -* by recursively loading all plugins specified by the - :globalvar:`pytest_plugins` variable in ``conftest.py`` files + - if no test paths are specified use current dir as a test path + - if exists, load ``conftest.py`` and ``test*/conftest.py`` relative + to the directory part of the first test path. After the ``conftest.py`` + file is loaded, load all plugins specified in its + :globalvar:`pytest_plugins` variable if present. + + Note that pytest does not find ``conftest.py`` files in deeper nested + sub directories at tool startup. It is usually a good idea to keep + your ``conftest.py`` file in the top level test or project root directory. + +7. by recursively loading all plugins specified by the + :globalvar:`pytest_plugins` variable in ``conftest.py`` files. .. _`pytest/plugin`: http://bitbucket.org/pytest-dev/pytest/src/tip/pytest/plugin/ From 7324e901995fd6eca609ac95badb03c9811f6acb Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Sat, 19 Sep 2020 16:14:28 -0300 Subject: [PATCH 2/2] Update doc/en/writing_plugins.rst Co-authored-by: Ran Benita --- doc/en/writing_plugins.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/en/writing_plugins.rst b/doc/en/writing_plugins.rst index ee500253d..474f355f6 100644 --- a/doc/en/writing_plugins.rst +++ b/doc/en/writing_plugins.rst @@ -49,7 +49,7 @@ Plugin discovery order at tool startup 6. by loading all :file:`conftest.py` files as inferred by the command line invocation: - - if no test paths are specified use current dir as a test path + - if no test paths are specified, use the current dir as a test path - if exists, load ``conftest.py`` and ``test*/conftest.py`` relative to the directory part of the first test path. After the ``conftest.py`` file is loaded, load all plugins specified in its