Skip to content

Commit 6d0aff1

Browse files
authored
Docs: clarify -p vs PYTEST_PLUGINS plugin loading (#14113)
Closes #13388
1 parent d794da3 commit 6d0aff1

2 files changed

Lines changed: 30 additions & 1 deletion

File tree

changelog/13388.doc.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Clarified documentation for ``-p`` vs ``PYTEST_PLUGINS`` plugin loading and fixed an incorrect ``-p`` example.

doc/en/how-to/plugins.rst

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -158,7 +158,7 @@ manually specify each plugin with :option:`-p` or :envvar:`PYTEST_PLUGINS`, you
158158
159159
.. code-block:: bash
160160
161-
pytest --disable-plugin-autoload -p NAME,NAME2
161+
pytest --disable-plugin-autoload -p NAME -p NAME2
162162
163163
.. tab:: toml
164164

@@ -180,3 +180,31 @@ manually specify each plugin with :option:`-p` or :envvar:`PYTEST_PLUGINS`, you
180180
.. versionadded:: 8.4
181181

182182
The :option:`--disable-plugin-autoload` command-line flag.
183+
184+
.. note::
185+
186+
:option:`-p` and :envvar:`PYTEST_PLUGINS` are both ways to explicitly control which
187+
plugins are loaded, but they serve slightly different use-cases.
188+
189+
* :option:`-p` loads (or disables with ``-p no:<name>``) a plugin by name or entry point
190+
for a specific pytest invocation, and is processed early during startup.
191+
* :envvar:`PYTEST_PLUGINS` is a comma-separated list of Python modules that are imported
192+
and registered as plugins during startup. This mechanism is commonly used by test
193+
suites, for example when testing a plugin.
194+
195+
When explicitly controlling plugin loading (especially with
196+
:envvar:`PYTEST_DISABLE_PLUGIN_AUTOLOAD` or :option:`--disable-plugin-autoload`),
197+
avoid specifying the same plugin via multiple mechanisms. Registering the same plugin
198+
more than once can lead to errors during plugin registration.
199+
200+
Examples:
201+
202+
.. code-block:: bash
203+
204+
# Disable auto-loading and load only specific plugins for this invocation
205+
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest -p xdist
206+
207+
.. code-block:: bash
208+
209+
# Disable auto-loading and load plugin modules during startup
210+
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 PYTEST_PLUGINS=mymodule.plugin,xdist pytest

0 commit comments

Comments
 (0)