В двух непакетных каталогах проекта лежат тестовые файлы с одинаковым именем. Что может произойти при их сборке pytest и какое решение предотвращает конфликт?
При стандартном режиме импорта pytest может загрузить оба файла как один и тот же модуль по его базовому имени. В результате возникает конфликт импорта: один тестовый файл ошибочно связывается с уже загруженным другим или pytest сообщает о несоответствии пути модуля. Конфликт устраняют уникальными именами тестовых файлов, превращением каталогов в пакеты или явным использованием режима importlib.
Тестовый файл Python перед выполнением должен стать модулем. Поэтому pytest не только находит файлы, но и выбирает способ сопоставить путь файла с именем модуля и загрузить его через механизм импорта Python.
Проблема особенно заметна в проектах, где тесты хранятся в нескольких непакетных каталогах. В традиционном режиме pytest добавляет каталог теста в sys.path и импортирует файл по простому имени, поэтому одинаковые базовые имена оказываются неразличимыми.
Предположим, в проекте есть tests/unit/test_api.py и tests/integration/test_api.py, причём каталоги не содержат __init__.py. Для Python это не два уникальных модуля с полными именами, а два кандидата на импорт под именем test_api.
После загрузки первого модуля запись о нём появляется в sys.modules. При попытке загрузить второй pytest может получить уже существующий модуль, путь которого не совпадает с текущим файлом. Это приводит к ошибке сборки, пропуску ожидаемых тестов или труднообъяснимому поведению импорта вспомогательных объектов.
В режиме prepend, который долгое время был стандартным, pytest добавляет каталог найденного теста в начало sys.path, а затем импортирует файл по имени. Для непакетного файла имя обычно основано на его basename, поэтому test_api.py в разных каталогах конфликтуют.
Наиболее прозрачное решение — давать тестовым файлам уникальные имена. Если каталоги оформлены как Python-пакеты с __init__.py, pytest может использовать квалифицированные имена модулей, включающие пакетный путь, и одинаковые basenames уже не обязаны конфликтовать.
Другой вариант — режим importlib. Он загружает тестовые модули через importlib без добавления каталогов тестов в sys.path и позволяет сосуществовать одноимённым файлам из разных каталогов. Однако тестовые файлы при таком режиме не следует рассматривать как обычные импортируемые друг другом модули; общие функции лучше вынести в пакет приложения или отдельный тестовый пакет.
Минимальная иллюстрация:
Выбор зависит от структуры проекта. Уникальные имена проще диагностировать, пакетная структура лучше отражает архитектуру, а importlib уменьшает зависимость поведения от изменения sys.path, но может потребовать переработать импорты между тестовыми файлами.
В проекте после добавления интеграционного слоя появился второй файл test_api.py. Локально разработчик запускал только один каталог, поэтому проблема не проявлялась; полный CI-запуск собирал оба каталога и завершался ошибкой о несовпадении пути импортированного модуля.
Рассматривались три варианта. Переименование файлов было самым простым, но потребовало изменить соглашения о названиях. Добавление __init__.py сделало каталоги пакетами, однако потребовало проверить абсолютные и относительные импорты. Переход на importlib устранил конфликт без переименования, но выявил несколько тестов, которые напрямую импортировали функции из соседних тестовых модулей.
Выбрали пакетную структуру и вынесли общие помощники в tests.support. Это дало уникальные квалифицированные имена модулей, явные границы импортов и предсказуемый запуск как отдельных каталогов, так и всего набора.
__init__.py только в каталог с тестом?Нет, важно, чтобы pytest мог построить однозначный пакетный путь от корня импорта до файла. Если структура пакетов неполная или одноимённые пакеты находятся в разных корнях импорта, конфликт всё ещё возможен. После изменения структуры нужно проверить фактические имена модулей в выводе pytest и импорты вспомогательных компонентов.
__pycache__ обычно не исправляет эту проблему?Конфликт возникает не из-за устаревшего байткода, а из-за сопоставления двух файлов с одним именем модуля и записи в sys.modules. Очистка кэша может случайно изменить порядок или скрыть симптом, но не устраняет причину. Нужно изменить имена, пакетную структуру или режим импорта.
importlib не всегда является безусловно лучшим решением?Он хорошо изолирует загрузку тестовых файлов и предотвращает многие конфликты базовых имён, но не добавляет каталоги тестов в sys.path как обычные места импорта. Поэтому импорт одного тестового файла из другого может перестать работать. Общую логику следует размещать в нормальном импортируемом пакете, а не связывать тесты прямыми зависимостями.