diff --git a/changelog/13388.doc.rst b/changelog/13388.doc.rst new file mode 100644 index 00000000000..bade402a60d --- /dev/null +++ b/changelog/13388.doc.rst @@ -0,0 +1 @@ +Clarified documentation for ``-p`` vs ``PYTEST_PLUGINS`` plugin loading and fixed an incorrect ``-p`` example. diff --git a/doc/en/how-to/plugins.rst b/doc/en/how-to/plugins.rst index 48a45619324..c6641eb8484 100644 --- a/doc/en/how-to/plugins.rst +++ b/doc/en/how-to/plugins.rst @@ -158,7 +158,7 @@ manually specify each plugin with :option:`-p` or :envvar:`PYTEST_PLUGINS`, you .. code-block:: bash - pytest --disable-plugin-autoload -p NAME,NAME2 + pytest --disable-plugin-autoload -p NAME -p NAME2 .. tab:: toml @@ -180,3 +180,31 @@ manually specify each plugin with :option:`-p` or :envvar:`PYTEST_PLUGINS`, you .. versionadded:: 8.4 The :option:`--disable-plugin-autoload` command-line flag. + +.. note:: + + :option:`-p` and :envvar:`PYTEST_PLUGINS` are both ways to explicitly control which + plugins are loaded, but they serve slightly different use-cases. + + * :option:`-p` loads (or disables with ``-p no:``) a plugin by name or entry point + for a specific pytest invocation, and is processed early during startup. + * :envvar:`PYTEST_PLUGINS` is a comma-separated list of Python modules that are imported + and registered as plugins during startup. This mechanism is commonly used by test + suites, for example when testing a plugin. + + When explicitly controlling plugin loading (especially with + :envvar:`PYTEST_DISABLE_PLUGIN_AUTOLOAD` or :option:`--disable-plugin-autoload`), + avoid specifying the same plugin via multiple mechanisms. Registering the same plugin + more than once can lead to errors during plugin registration. + +Examples: + +.. code-block:: bash + + # Disable auto-loading and load only specific plugins for this invocation + PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest -p xdist + +.. code-block:: bash + + # Disable auto-loading and load plugin modules during startup + PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 PYTEST_PLUGINS=mymodule.plugin,xdist pytest