.. _mark:

Маркировка тестов
====================

Благодаря ``pytest.mark`` можно передавать метаданные
в ваши тесты. Ниже приведены примеры некоторых встроенных маркеров:

* :ref:`skip <skip>` - пропускает (skip) тестовую функцию
* :ref:`skipif <skipif>` - пропускает (skip) тестовую функцию при соблюдении определенных условий
* :ref:`xfail <xfail>` - помечает тест как  "ожидаемо падающий" (xfail) при соблюдении каких-то условий
* :ref:`parametrize <parametrizemark>` - используется для многократного вызова одной и той же
  тестовой функции с разными параметрами

Можно с легкостью создавать маркеры и применять их
ко всему тестовому классу или модулю. Маркеры можно использовать в плагинах
и для :ref:`отбора тестов <mark run>` при запуске
``pytest`` из командной строки с опцией ``-m``.

Примеры и документацию см. :ref:`mark examples`.

.. note::

    Маркеры можно применять только к самим тестам, на :ref:`фикстуры <fixtures>` они никак не влияют.

Регистрация маркера
---------------------

Свой маркер можно зарегистрировать в файле ``pytest.ini``:

.. code-block:: ini

    [pytest]
    markers =
        slow: помечает тесты как "медленные" (не будут выбраны при запуске с '-m "not slow"')
        serial

При этом все, что после  ``:``  - это описание маркера (опционально).

Можно также зарегистрировать новые маркеры программно в хуке (hook)
`pytest_configure <https://docs.pytest.org/en/latest/reference.html#initialization-hooks>`_.

.. code-block:: python

    def pytest_configure(config):
        config.addinivalue_line(
            "markers", "env(name): mark test to run only on named environment"
        )

Если маркер зарегистрирован, то запуск ``pytest`` не генерирует предупреждений (см. ниже).
Поэтому рекомендуется всегда :ref:`регистрировать свои маркеры <registering-markers>`
для сторонних плагинов.


.. _unknown-marks:

Генерация ошибок при обнаружении неопознанного маркера
-----------------------------------------------------------

Незарегистрированные маркеры, применяемые с помощью декоратора ``@pytest.mark.name_of_the_mark``,
будут всегда генерировать предупреждения. Это сделано, чтобы избежать сюрпризов из-за опечаток.
В предыдущем разделе рассказано, как отключить генерацию предупреждений для
настроенных маркеров с помощью регистрации их в ``pytest.ini`` или хуке
``pytest_configure``.

Если применить опцию командной строки ``--strict-markers``, то все неопознанные маркеры,
используемые декоратором ``@pytest.mark.name_of_the_mark``, будут генерировать ошибку.
Для своего проекта эту опцию можно применить по умолчанию, добавив
``--strict-markers`` в ``addopts`` в ``pytest.ini``.

.. code-block:: ini

    [pytest]
    addopts = --strict-markers
    markers =
        slow: marks tests as slow (deselect with '-m "not slow"')
        serial