Механизмы импорта pytest и sys.path/PYTHONPATH

Режимы импорта

pytest как среде тестирования необходимо импортировать тестовые модули и файлы conftest.py для выполнения.

Импорт файлов в Python — нетривиальный процесс, поэтому отдельными аспектами импорта можно управлять с помощью флага командной строки --import-mode, который может принимать следующие значения:

• prepend (по умолчанию): путь к каталогу, содержащему каждый модуль, будет вставлен в начало sys.path, если его там ещё нет, после чего модуль будет импортирован с помощью функции importlib.import_module.

  Настоятельно рекомендуется организовать тестовые модули в виде пакетов, добавив файлы __init__.py в каталоги с тестами. Это позволит включить тесты в полноценный пакет Python, благодаря чему pytest сможет определить их полное имя (например, tests.core.test_core для test_core.py в пакете tests.core).

  Если дерево каталогов с тестами не организовано в виде пакетов, имена всех тестовых файлов должны быть уникальными, иначе pytest выдаст ошибку, если обнаружит два теста с одинаковыми именами.

  Это классический механизм, существующий со времён, когда Python 2 ещё поддерживался.

• append: каталог, содержащий каждый модуль, будет добавлен в конец sys.path, если его там ещё нет, после чего модуль будет импортирован с помощью importlib.import_module.

  Этот режим позволяет пользователям запускать тестовые модули для установленных версий пакета, даже если корень импорта тестируемого пакета совпадает. Например:

  testing/__init__.py
  testing/test_pkg_under_test.py
  pkg_under_test/
  

  тесты будут выполняться для установленной версии pkg_under_test при использовании --import-mode=append, тогда как при использовании prepend они будут использовать локальную версию. Именно из-за подобных неоднозначностей мы рекомендуем использовать структуру каталогов src.

  Как и prepend, этот режим требует уникальных имён тестовых модулей, если дерево каталогов с тестами не организовано в виде пакетов, поскольку после импорта модули будут помещены в sys.modules.

• importlib: в этом режиме для импорта тестовых модулей используются более гибкие механизмы, предоставляемые importlib, без изменения sys.path.

  Преимущества этого режима:

  • pytest совсем не изменяет sys.path.
  • Имена тестовых модулей не обязательно должны быть уникальными — pytest автоматически сгенерирует уникальное имя на основе rootdir.

  Недостатки:

  • Тестовые модули не могут импортировать друг друга.

  • Вспомогательные модули для тестирования в каталогах с тестами (например, модуль tests.helpers с функциями/классами, связанными с тестированием) импортировать нельзя. В этом случае рекомендуется разместить вспомогательные модули для тестирования рядом с кодом приложения/библиотеки, например в app.testing.helpers.

    Важно: под «вспомогательными модулями для тестирования» мы подразумеваем функции/классы, которые непосредственно импортируются другими тестами; это не относится к фикстурам, которые следует размещать в файлах conftest.py вместе с тестовыми модулями. pytest обнаруживает их автоматически.

  Это работает следующим образом:

  1. Для заданного пути к модулю, например tests/core/test_models.py, выводится каноническое имя, например tests.core.test_models, после чего выполняется попытка импорта.

     Для модулей, не являющихся тестовыми, это сработает, если они доступны через sys.path. Так, например, .env/lib/site-packages/app/core.py можно будет импортировать как app.core. Это происходит, когда плагины импортируют модули, не являющиеся тестовыми (например, при тестировании документации).

     Если этот шаг выполнится успешно, модуль будет возвращён.

     Для тестовых модулей этот шаг завершится неудачей, если они недоступны через sys.path.

  2. Если предыдущий шаг завершился неудачей, мы импортируем модуль напрямую с помощью средств importlib, что позволяет импортировать его, не изменяя sys.path.

     Поскольку Python требует, чтобы модуль также был доступен в sys.modules, pytest выводит для него уникальное имя на основе его относительного расположения относительно rootdir и добавляет модуль в sys.modules.

     Например, tests/core/test_models.py в итоге будет импортирован как модуль tests.core.test_models.

  Добавлено в версии 6.0.

Сценарии режимов импорта prepend и append

Ниже приведён список сценариев использования режимов импорта prepend или append, в которых pytest необходимо изменить sys.path, чтобы импортировать тестовые модули или файлы conftest.py, а также возможных проблем, с которыми пользователи могут столкнуться из-за этого.

root/
|- foo/
   |- __init__.py
   |- conftest.py
   |- bar/
      |- __init__.py
      |- tests/
         |- __init__.py
         |- test_foo.py

pytest root/

root/
|- foo/
   |- conftest.py
   |- bar/
      |- tests/
         |- test_foo.py

pytest root/

Запуск pytest и python -m pytest

Запуск pytest с помощью pytest [...] вместо python -m pytest [...] приводит к почти такому же поведению, за исключением того, что последний вариант добавляет текущий каталог в sys.path, как это принято в python.

См. также раздел Вызов pytest с помощью python -m pytest.