# Python Pytest Testing

> Используй как вспомогательный скил при настройке и организации тестов Python через pytest, pytest-asyncio и pytest-cov: структура unit/integration, фикстуры, фабрики, conftest.py, параметризация, маркеры, асинхронные тесты, команды запуска, покрытие и общий lifecycle временной интеграционной инфраструктуры. Не использовать для определения тестовых сценариев, ожидаемого поведения компонентов и технологически специфичных проверок.

- Skill: `nemagu/python-pytest-testing` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add nemagu/python-pytest-testing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nemagu/python-pytest-testing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: Nemagu (https://skillmd.com/u/nemagu)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/nemagu/python-pytest-testing

---


# Общие практики pytest

Применяй единые технические приёмы pytest, не определяя, что именно должен
проверять конкретный компонент. Состав сценариев, ожидаемые результаты и
технологические гарантии бери из требований тестируемого компонента.

## Порядок работы

1. Изучи инструкции репозитория и существующую организацию тестов.
2. Получи перечень проверяемых сценариев из требований компонента.
3. Раздели unit- и integration-тесты.
4. Размести фикстуры и фабрики на минимально необходимом общем уровне.
5. Параметризуй одинаковые по структуре сценарии.
6. Настрой асинхронное выполнение и инфраструктурный lifecycle при необходимости.
7. Запусти узкие проверки, затем обязательный полный набор и покрытие.

Не добавляй happy path, граничные случаи, ошибочные исходы, инварианты или
приоритеты покрытия самостоятельно.

## Структура

Используй базовое разделение:

```text
src/tests/
├── units/
└── integration/
```

- Внутри повторяй только полезную часть структуры исходного кода.
- Не создавай пустые каталоги заранее.
- Unit-тест проверяет локальный контракт с контролируемыми зависимостями.
- Integration-тест проверяет взаимодействие написанного в проекте кода с
  настоящей технологической инфраструктурой.
- Не смешивай unit- и integration-цель в одном тесте.

## Фикстуры и фабрики

- Используй локальную фикстуру, если она нужна одному модулю.
- При использовании несколькими модулями переноси её в ближайший общий
  `conftest.py`.
- Не дублируй фикстуры и фабрики.
- Фабрику предоставляй фикстурой.
- Значения по умолчанию фабрики должны создавать валидный объект.
- Не скрывай случайность, I/O и лишнее поведение внутри фабрики.
- Расширяй scope только при измеримой необходимости.
- Используй `autouse` только для необходимой поперечной изоляции между тестами.
- Удаляй пустой `conftest.py`.
- Какие объекты создавать фабриками, определяют требования компонента.

Decision tree и параметризация приведены в
[fixtures-and-parametrization.md](references/fixtures-and-parametrization.md).

## Тестовые двойники

- В unit-тесте используй небольшую fake- или stub-реализацию внешней зависимости.
- Реализуй только необходимый публичный контракт.
- Предпочитай понятный fake хрупким цепочкам `Mock` и `AsyncMock`.
- В integration-тесте не заменяй проверяемую технологическую инфраструктуру
  mock-объектом.
- Не проверяй внутреннее поведение сторонних библиотек.

## Параметризация

- Объединяй сценарии с одинаковой последовательностью Arrange–Act–Assert через
  `pytest.mark.parametrize`.
- Всегда задавай `ids`, описывающие смысл вариантов.
- Не объединяй существенно разные сценарии ради сокращения кода.
- Для сложного набора входов и ожиданий используй неизменяемый case-объект.

## Маркеры

- Помечай integration-тесты `@pytest.mark.integration`.
- Регистрируй каждый пользовательский маркер в конфигурации pytest.
- Добавляй остальные маркеры только при реальном использовании.
- Маркеры дополняют структуру каталогов, но не заменяют её.

## Асинхронные тесты

- Используй `pytest-asyncio` и явно выбранный проектом asyncio mode.
- Не управляй event loop вручную внутри теста.
- Отменяй созданные фоновые задачи и дожидайся их завершения.
- Не оставляй pending tasks после теста.
- Подменяй время, ожидания и сигналы управляемыми часами и событиями.
- Не используй реальные долгие `sleep`.
- Ограничивай ожидание асинхронного результата timeout.

Подробности — в
[async-and-stability.md](references/async-and-stability.md).

## Интеграционная инфраструктура

Поддерживай два согласованных проектом режима:

- локальный — тестовая сессия сама поднимает и освобождает инфраструктуру;
- внешний — тесты подключаются к уже подготовленным зависимостям и не управляют
  их lifecycle.

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

Общие требования локального режима:

- запускать инфраструктуру автоматически через subprocess;
- создавать конфигурацию вне репозитория в уникальном временном каталоге;
- использовать уникальные имена файлов, проекта и глобальных ресурсов;
- выбирать порты динамически;
- проверять готовность активной проверкой с timeout;
- выполнять cleanup в `finally`, включая частично успешный startup;
- поддерживать параллельные прогоны без общего namespace.

Общие требования внешнего режима:

- получать подключения из переменных окружения;
- не создавать, не изменять и не останавливать внешнюю инфраструктуру;
- явно обрабатывать отсутствие обязательных параметров;
- проверять готовность;
- сохранять изоляцию ресурсов параллельных прогонов.

Одна session-scoped фикстура владеет общим lifecycle и возвращает минимальный
типизированный runtime-контекст. Технологические фикстуры выполняют подготовку
схемы, создание клиентов и очистку состояния штатными средствами технологии.
Не закрепляй эти механизмы в общем скиле.

Подробности — в
[integration-infrastructure.md](references/integration-infrastructure.md).

## Наблюдаемое поведение и стабильность

- Проверяй публично наблюдаемый результат и согласованные побочные эффекты.
- Не проверяй приватные методы и внутреннюю последовательность вызовов без
  контрактной причины.
- Не завязывай тест на порядок запуска.
- Контролируй случайные значения, время и timezone.
- Жди наблюдаемое условие вместо произвольного `sleep`.
- Не маскируй flaky-тест безусловным retry.
- После теста не оставляй процессы, задачи, соединения и временные файлы.

## Запуск и покрытие

Используй команды, принятые репозиторием. Для проекта на `uv`:

```bash
uv run pytest
uv run pytest src/tests/units
uv run pytest -m integration
uv run pytest path/to/test_file.py
uv run pytest path/to/test_file.py::test_name
uv run pytest --cov=src --cov-report=term-missing
```

- Настраивай source и форматы отчётов согласно требованиям проекта.
- При раздельных прогонах объединяй coverage-данные штатным способом инструмента.
- Не устанавливай проценты, приоритеты и исключения покрытия в общем скиле.
- Не создавай искусственные тесты только ради процента.

## Границы

В область скила входят:

- конфигурация pytest, pytest-asyncio и pytest-cov;
- структура unit/integration;
- фикстуры, фабрики и `conftest.py`;
- test doubles;
- параметризация и маркеры;
- общие правила асинхронности и стабильности;
- общий lifecycle временной интеграционной инфраструктуры;
- команды запуска и сбор покрытия.

Не входят:

- выбор тестовых сценариев и ожидаемых результатов;
- проверки конкретных инвариантов, операций, endpoint-ов и протоколов;
- SQL, миграции и очистка конкретной БД;
- stream, subject, ACK и другие правила брокера;
- требования к проценту покрытия;
- тестирование поведения сторонних библиотек.

## Критерии готовности

- Состав сценариев получен из требований компонента.
- Unit- и integration-тесты разделены.
- Фикстуры и фабрики не дублируются.
- Параметризация содержит читаемые `ids`.
- Пользовательские маркеры зарегистрированы.
- Асинхронные задачи корректно завершаются.
- Инфраструктура изолирована, проверяет готовность и освобождается автоматически.
- Локальный и внешний режимы соблюдают согласованный контракт проекта.
- Команды запуска и сбор покрытия работают.
- Полный обязательный набор тестов проходит.

## Материалы

- [Фикстуры и параметризация](references/fixtures-and-parametrization.md)
- [Асинхронность и стабильность](references/async-and-stability.md)
- [Интеграционная инфраструктура](references/integration-infrastructure.md)