Архитектура большого тест-сьюта

Один каталог `tests/` с 20 файлами -- это терпимо. При 200 файлах в 5 модулях становится неясно, куда добавлять новые тесты, какие тесты можно запускать быстро, и почему ранее проходивший тест внезапно падает на свежей ветке. Архитектура тестов -- это набор решений, которые сохраняют ваш тест-сьют навигируемым, надёжным и быстрым по мере роста. ## Трёхслойная модель Тесты естественным образом делятся на три категории в зависимости от того, что они затрагивают: **Юнит-тесты** проверяют одну функцию или класс в изоляции. В них нет I/O -- ни базы данных, ни сети, ни файловой системы. Они выполняются за миллисекунды. Тест-сьют из 500 юнит-тестов типично завершается менее чем за две секунды. **Интеграционные тесты** проверяют как компоненты работают вместе: вью + база данных, сервис + кэш, парсер + ридер файлов. Они настраивают реальную инфраструктуру (тестовую базу данных, запущенный сервер, временный каталог) и медленнее -- часто 100-500 мс на тест. **Сквозные тесты (e2e)** управляют приложением снаружи, обычно через браузер (Selenium, Playwright) или реальный HTTP-клиент против запущенного сервера. Они самые медленные и хрупкие, но ловят регрессии, которые юнит- и интеграционные тесты упустить не могут. Стандартная структура каталогов отражает это разделение: ``` tests/ +-- conftest.py # общие фикстуры для всего тест-сьюта +-- unit/ | +-- conftest.py # фикстуры только для юнит-тестов | +-- test_models.py | +-- test_services.py | +-- test_utils.py +-- integration/ | +-- conftest.py # фикстуры только для интеграционных тестов | +-- test_api.py | +-- test_db.py +-- e2e/ +-- conftest.py +-- test_checkout_flow.py ``` ## Иерархия conftest.py pytest ищет файлы `conftest.py` начиная с каталога тестового файла и поднимаясь до `rootdir`. Фикстура, определённая в `tests/conftest.py`, доступна каждому тесту в тест-сьюте. Фикстура, определённая в `tests/unit/conftest.py`, доступна только тестам под `tests/unit/`. Это слоение позволяет избежать распространённого антипаттерна: одного гигантского `conftest.py` в корне, определяющего всё. Когда юнит-тесты импортируют интеграционные фикстуры (сессии базы данных, HTTP-клиенты), они непреднамеренно наследуют издержки настройки -- и граница между "быстрыми" и "медленными" тестами стирается. Правило большого пальца: **фикстура должна быть определена в самом высоком conftest, где она нужна, и не выше.** Фикстура базы данных, используемая только интеграционными тестами, принадлежит `tests/integration/conftest.py`, а не корневому. ## Принципы изоляции тестов **Никакого общего изменяемого состояния.** Если тест A модифицирует глобальный объект (список на уровне модуля, переменную класса, синглтон), а тест B читает этот объект, результат теста B зависит от того, был ли сначала запущен тест A. Это скрытая зависимость от порядка. Решения: используйте свежие экземпляры для каждого теста (фикстуры со scope function), или `monkeypatch` для восстановления состояния после каждого теста. **Никакой зависимости от порядка.** Ваш тест-сьют должен давать одинаковые результаты независимо от того, запускает ли pytest тесты по алфавиту, в обратном порядке или случайным образом (`pytest-randomly`). Если изменение порядка меняет результаты, тест не изолирован по-настоящему. Запустите `pytest --randomly-seed=last` для воспроизведения конкретного порядка, или `pytest -p randomly --randomly-seed=0` для включения рандомизации. **Никакой коммуникации между тестами.** Тесты не должны передавать данные друг другу через общие переменные. Если вы пишете `test_02_login_after_register`, логика настройки принадлежит фикстуре, а не распределению по тестовым функциям с нумерацией. ## Стратегия производительности Цель -- цикл обратной связи, достаточно быстрый чтобы разработчики запускали полный юнит-сьют перед каждым коммитом, и интеграционные тесты в CI при каждом push. Типичные цели: - **Юнит-сьют**: менее 5 секунд локально, запускается всегда. - **Интеграционный сьют**: менее 2 минут в CI, запускается при push. - **E2e-сьют**: запускается ночью или на релизных ветках. Для запуска подмножеств комбинируйте нацеливание по пути и фильтрацию по меткам: ```bash # Только юнит-тесты (быстро) pytest tests/unit/ # Только интеграционные тесты pytest tests/integration/ # Всё кроме медленных тестов pytest -m "not slow" # Только тесты конкретного модуля pytest tests/unit/test_services.py ``` ## Регистрация кастомных меток pytest предупреждает когда тест использует незарегистрированную метку. Регистрируйте метки в `pytest.ini`: ```ini [pytest] markers = unit: быстрые тесты без I/O integration: тесты использующие базу данных или сеть slow: тесты выполняющиеся более 1 секунды smoke: минимальный набор перед деплоем ``` `--strict-markers` (также в `addopts`) заставляет pytest немедленно завершаться с ошибкой если тест использует незарегистрированную метку -- это ловит опечатки вроде `@pytest.mark.integraion`, которые иначе молча становятся no-op. ## Распространённые антипаттерны **God conftest.** Один `conftest.py` с 50 фикстурами, неявно импортируемый каждым тестом. Тяжело навигировать, скрывает связанность между слоями тестов. **Тесты, которые убирают за собой (вместо использования фикстур).** Если настройка выполняется в теле теста, а завершение -- в `try/finally`, система фикстур обходится стороной. Завершение фикстур в pytest выполняется предсказуемо и корректно; ручной `try/finally` внутри тестов ненадёжен и скрывает намерение. **Злоупотребление фикстурами.** Не всё нуждается в фикстуре. Простое `user = User(name="Alice")` в теле теста понятнее, чем фикстура `alice_user`, делающая то же самое и используемая в 15 тестах. Используйте фикстуры для настройки, которая действительно переиспользуется или включает завершение. **Неявно упорядоченные тесты.** Именование тестов `test_01_`, `test_02_` для управления порядком -- это запах. Если порядок важен, тесты разделяют состояние, которого не должны. Извлеките общее состояние в фикстуру или вспомогательную функцию, вызываемую каждым тестом независимо.

Это пошаговое руководство показывает как выглядит хорошо структурированный тест-сьют для Django e-commerce проекта: каталог товаров, аккаунты пользователей, сервис заказов и публичное API. Цель -- тест-сьют, где быстрая обратная связь занимает 3 секунды, а полный сьют в CI выполняется менее чем за 90 секунд. ## Дерево каталогов ``` my_shop/ +-- src/ | +-- catalogue/ | +-- orders/ | +-- accounts/ +-- tests/ | +-- conftest.py | +-- unit/ | | +-- conftest.py | | +-- catalogue/ | | | +-- test_models.py | | | +-- test_services.py | | +-- orders/ | | | +-- test_pricing.py | | | +-- test_validators.py | | +-- accounts/ | | +-- test_password_policy.py | +-- integration/ | | +-- conftest.py | | +-- test_order_flow.py | | +-- test_api_products.py | | +-- test_api_checkout.py | +-- e2e/ | +-- conftest.py | +-- test_checkout_browser.py +-- pytest.ini +-- Makefile ``` Дерево исходников зеркалируется в дереве тестов под `tests/unit/`. Это упрощает поиск тестов для модуля: `catalogue/models.py` → `tests/unit/catalogue/test_models.py`. ## Корневой conftest.py `tests/conftest.py` содержит только то, что нужно каждому тесту: ```python # tests/conftest.py import pytest # django_db_setup предоставляется pytest-django автоматически. # Переопределяйте только если нужна кастомная логика создания БД (редко). @pytest.fixture def settings_override(settings): # Безопасное переопределение настроек -- изменения откатываются после каждого теста. settings.EMAIL_BACKEND = 'django.core.mail.backends.locmem.EmailBackend' return settings ``` Держите этот файл маленьким. Правило: если вы добавляете сюда фикстуру, и 90% тестов никогда её не используют, переместите её в conftest соответствующего подкаталога. ## Unit conftest.py ```python # tests/unit/conftest.py import pytest from catalogue.models import Product from accounts.models import User @pytest.fixture def product(): # Product в памяти -- база данных не нужна. return Product(name="Widget", price=9_99, stock=10) @pytest.fixture def user(): return User(email="[email protected]", is_active=True) ``` Эти фикстуры создают объекты в памяти без обращения к базе данных. Они работают в области функции (по умолчанию), поэтому каждый тест получает свежий объект. ## Integration conftest.py ```python # tests/integration/conftest.py import pytest @pytest.fixture(scope='session') def api_base_url(live_server): # Полный URL тестового сервера Django. return live_server.url @pytest.fixture def auth_client(client, django_user_model): # Авторизованный тестовый клиент Django. user = django_user_model.objects.create_user( username='testuser', password='testpass' ) client.force_login(user) return client @pytest.fixture def seeded_catalogue(db): # Три товара в базе данных. from catalogue.models import Product Product.objects.bulk_create([ Product(name='Widget', price=999, stock=10), Product(name='Gadget', price=1999, stock=5), Product(name='Doohickey', price=499, stock=0), ]) ``` Фикстура `db` (от pytest-django) помечает эти тесты как тесты с базой данных. Обратите внимание на `scope='session'` у `api_base_url` -- запуск живого сервера дорогой, поэтому он разделяется на всю тестовую сессию. ## Метки и pytest.ini ```ini [pytest] addopts = -v --tb=short --strict-markers testpaths = tests markers = unit: быстрые тесты без I/O integration: тесты использующие базу данных или сеть slow: тесты выполняющиеся более 1 секунды smoke: минимальный набор перед деплоем ``` Применяйте метки на уровне модуля чтобы не повторять их на каждой функции: ```python # tests/integration/test_order_flow.py import pytest pytestmark = [pytest.mark.integration] @pytest.mark.django_db def test_order_created_on_checkout(auth_client, seeded_catalogue): resp = auth_client.post('/api/orders/', {'product_id': 1, 'quantity': 2}) assert resp.status_code == 201 @pytest.mark.django_db @pytest.mark.slow def test_order_email_sent(auth_client, seeded_catalogue, mailoutbox): auth_client.post('/api/orders/', {'product_id': 1, 'quantity': 1}) assert len(mailoutbox) == 1 assert 'Order confirmation' in mailoutbox[0].subject ``` `pytestmark` -- список на уровне модуля. Каждый тест в файле наследует все метки из списка. Добавление `pytest.mark.slow` к отдельным тяжёлым тестам позволяет исключать их из быстрого интеграционного прогона. ## Цели Makefile ```makefile .PHONY: test test-unit test-integration test-fast test-ci test-unit: pytest tests/unit/ -q test-integration: pytest tests/integration/ -q test-fast: pytest tests/unit/ tests/integration/ -m "not slow" -q test: pytest -q test-ci: pytest --cov=src --cov-report=term-missing --cov-fail-under=80 -q ``` `-q` (тихий режим) подавляет отдельные имена тестов и печатает только итог -- полезно для быстрых циклов обратной связи. ## Обнаружение и исправление зависимости от порядка тестов Вот реальный паттерн, создающий зависимости от порядка: ```python # СЛОМАНО -- тесты разделяют состояние через список на уровне модуля # (Product и client импортируются откуда-то; фокус на _created_ids) _created_ids = [] def test_create_product(): product = Product.objects.create(name='Widget', price=999) _created_ids.append(product.id) def test_created_product_appears_in_list(): # Проходит только если test_create_product запущен первым resp = client.get('/api/products/') assert any(p['id'] in _created_ids for p in resp.json()) ``` Исправление -- перенести настройку в фикстуру, делая каждый тест самодостаточным: ```python # ИСПРАВЛЕНО -- каждый тест независим @pytest.fixture def widget(db): return Product.objects.create(name='Widget', price=999) @pytest.mark.django_db def test_create_product(db): product = Product.objects.create(name='Widget', price=999) assert product.id is not None @pytest.mark.django_db def test_created_product_appears_in_list(widget, client): resp = client.get('/api/products/') ids = [p['id'] for p in resp.json()] assert widget.id in ids ``` Теперь каждый тест настраивает то, что ему нужно, и не зависит от другого теста, который был запущен первым. База данных откатывается между тестами транзакционными фикстурами pytest-django. Для проактивного обнаружения зависимостей от порядка установите `pytest-randomly` и запустите: ```bash pip install pytest-randomly pytest --randomly-seed=random ``` Если ваш тест-сьют падает с одним seed, но проходит с другим -- у вас скрытая зависимость от порядка.

## Стандартная структура каталогов ``` tests/ +-- conftest.py <- фикстуры для всех тестов +-- unit/ | +-- conftest.py <- фикстуры только для юнит-тестов | +-- module_name/ | +-- test_*.py +-- integration/ | +-- conftest.py <- фикстуры только для интеграционных тестов | +-- test_*.py +-- e2e/ +-- conftest.py +-- test_*.py ``` ## Правила области видимости conftest.py | Где определено | Доступно | |---|---| | `tests/conftest.py` | Всем тестам | | `tests/unit/conftest.py` | Только тестам под `tests/unit/` | | `tests/integration/conftest.py` | Только тестам под `tests/integration/` | Фикстуры, определённые ниже в дереве, **переопределяют** одноимённые фикстуры выше. ## Настройка меток в pytest.ini ```ini [pytest] addopts = -v --tb=short --strict-markers testpaths = tests markers = unit: быстрые тесты без I/O integration: использует базу данных или сеть slow: выполняется более 1 секунды smoke: минимальная проверка перед деплоем ``` ## Запуск подмножеств ```bash pytest tests/unit/ # только юнит-сьют pytest tests/integration/ # только интеграционный сьют pytest -m "not slow" # исключить медленные тесты pytest -m "smoke" # только smoke-тесты pytest -m "integration and not slow" # комбинирование меток pytest tests/unit/test_models.py # один файл pytest tests/unit/test_models.py::test_price_is_positive # один тест ``` ## Метка на уровне модуля ```python # Применяется к каждому тесту в файле pytestmark = [pytest.mark.integration, pytest.mark.django_db] ``` ## Обнаружение зависимостей от порядка ```bash pip install pytest-randomly pytest --randomly-seed=random # случайный порядок при каждом запуске pytest --randomly-seed=last # воспроизвести последний порядок pytest -p no:randomly # отключить рандомизацию ``` ## Цели Makefile ```makefile test-unit: pytest tests/unit/ -q test-integration: pytest tests/integration/ -q test-fast: pytest tests/unit/ tests/integration/ -m "not slow" -q test-ci: pytest --cov=src --cov-fail-under=80 -q ``` ## Распространённые антипаттерны | Антипаттерн | Симптом | Решение | |---|---|---| | God conftest | Корневой conftest с 50+ фикстурами | Перенести фикстуры в conftest подкаталога | | Нумерованные тесты | `test_01_`, `test_02_` | Извлечь общую настройку в фикстуру | | Общее изменяемое состояние | Тесты падают в случайном порядке | Использовать фикстуры с function scope вместо глобалей модуля | | Злоупотребление фикстурами | Фикстура `alice_user` используется в 1 тесте | Создавать объект прямо в теле теста | | Смешанные слои | Юнит-тесты импортируют фикстуру `db` | Держать unit conftest без I/O фикстур | | Ручное завершение в теле теста | `try/finally` внутри тестовых функций | Использовать `yield`-фикстуры -- они выполняются даже при ошибке |