doc/en/how-to/plugins.rst - main - niceSOFT/python3-pytest

doc/en/how-to/plugins.rst
214 строк6 KB
Shriprasad
docs: endorse pytest-skip-slow plugin
09 авг 2026, 09:44
09 авг 2026, 09:44325893f
.. _`external plugins`:
.. _`extplugins`:
.. _`using plugins`:

How to install and use plugins
===============================

This section talks about installing and using third party plugins.
For writing your own plugins, please refer to :ref:`writing-plugins`.

Installing a third party plugin can be easily done with ``pip``:

.. code-block:: bash

    pip install pytest-NAME
    pip uninstall pytest-NAME

If a plugin is installed, ``pytest`` automatically finds and integrates it,
there is no need to activate it.

Here is a little annotated list for some popular plugins:

* :pypi:`pytest-django`: write tests
  for `django <https://docs.djangoproject.com/>`_ apps, using pytest integration.

* :pypi:`pytest-twisted`: write tests
  for `twisted <https://twistedmatrix.com/>`_ apps, starting a reactor and
  processing deferreds from test functions.

* :pypi:`pytest-cov`:
  coverage reporting, compatible with distributed testing

* :pypi:`pytest-xdist`:
  to distribute tests to CPUs and remote hosts, to run in boxed
  mode that allows pytest to survive segmentation faults, to run in
  looponfailing mode, automatically re-running failing tests
  on file changes.

* :pypi:`pytest-instafail`:
  to report failures while the test run is happening.

* :pypi:`pytest-bdd`:
  to write tests using behaviour-driven testing.

* :pypi:`pytest-timeout`:
  to timeout tests based on function marks or global definitions.

* :pypi:`pytest-skip-slow`:
  to skip tests marked ``@pytest.mark.slow`` by default, and run them with
  ``--slow``.

* :pypi:`pytest-pep8`:
  a ``--pep8`` option to enable PEP8 compliance checking.

* :pypi:`pytest-flakes`:
  check source code with pyflakes.

* :pypi:`allure-pytest`:
  report test results via `allure-framework <https://github.com/allure-framework/>`_.

To see a complete list of all plugins with their latest testing
status against different pytest and Python versions, please visit
:ref:`plugin-list`.

You may also discover more plugins through a `pytest- pypi.org search`_.

.. _`pytest- pypi.org search`: https://pypi.org/search/?q=pytest-


.. _`available installable plugins`:

Requiring/Loading plugins in a test module or conftest file
-----------------------------------------------------------

You can require plugins in a test module or a conftest file using :globalvar:`pytest_plugins`:

.. code-block:: python

    pytest_plugins = ("myapp.testsupport.myplugin",)

When the test module or conftest plugin is loaded the specified plugins
will be loaded as well.

.. note::

    Requiring plugins using a ``pytest_plugins`` variable in non-root
    ``conftest.py`` files is deprecated. See
    :ref:`full explanation <requiring plugins in non-root conftests>`
    in the Writing plugins section.

.. note::
   The name ``pytest_plugins`` is reserved and should not be used as a
   name for a custom plugin module.


.. _`findpluginname`:

Finding out which plugins are active
------------------------------------

If you want to find out which plugins are active in your
environment you can type:

.. code-block:: bash

    pytest --trace-config

and will get an extended test header which shows activated plugins
and their names. It will also print local plugins aka
:ref:`conftest.py <conftest.py plugins>` files when they are loaded.

.. _`cmdunregister`:

Deactivating / unregistering a plugin by name
---------------------------------------------

You can prevent plugins from loading or unregister them:

.. code-block:: bash

    pytest -p no:NAME

This means that any subsequent try to activate/load the named
plugin will not work.

If you want to unconditionally disable a plugin for a project, you can add
this option to your configuration file:

.. tab:: toml

    .. code-block:: toml

        [pytest]
        addopts = ["-p", "no:NAME"]

.. tab:: ini

    .. code-block:: ini

        [pytest]
        addopts = -p no:NAME

Alternatively to disable it only in certain environments (for example in a
CI server), you can set ``PYTEST_ADDOPTS`` environment variable to
``-p no:name``.

See :ref:`findpluginname` for how to obtain the name of a plugin.

.. _`disable_plugin_autoload`:

Disabling plugins from autoloading
----------------------------------

If you want to disable plugins from loading automatically, instead of requiring you to
manually specify each plugin with :option:`-p` or :envvar:`PYTEST_PLUGINS`, you can use :option:`--disable-plugin-autoload` or :envvar:`PYTEST_DISABLE_PLUGIN_AUTOLOAD`.

.. code-block:: bash

   export PYTEST_DISABLE_PLUGIN_AUTOLOAD=1
   export PYTEST_PLUGINS=NAME,NAME2
   pytest

.. code-block:: bash

   pytest --disable-plugin-autoload -p NAME -p NAME2

.. tab:: toml

    .. code-block:: toml

        [pytest]
        addopts = ["--disable-plugin-autoload", "-p", "NAME", "-p", "NAME2"]

.. tab:: ini

    .. code-block:: ini

        [pytest]
        addopts =
            --disable-plugin-autoload
            -p NAME
            -p NAME2

.. 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:<name>``) 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 or plugin
     entry point names that are loaded 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