telegram-helper-bot/README_TESTING.md

Тестирование Telegram Helper Bot

Этот документ описывает систему тестирования для Telegram Helper Bot.

Структура тестов

Тесты организованы в следующие файлы:

• tests/test_bot.py - Основные тесты бота (запуск, хэндлеры, интеграция)
• tests/test_media_handlers.py - Тесты обработки медиа-контента
• tests/test_error_handling.py - Тесты обработки ошибок и граничных случаев
• tests/test_utils.py - Тесты утилит и вспомогательных функций
• tests/test_keyboards_and_filters.py - Тесты клавиатур и фильтров
• tests/test_db.py - Тесты базы данных
• tests/conftest.py - Общие фикстуры и конфигурация

Установка зависимостей

make install

Запуск тестов

Все тесты

make test

Отдельные категории тестов

# Тесты базы данных
make test-db

# Тесты бота (запуск и хэндлеры)
make test-bot

# Тесты обработки медиа
make test-media

# Тесты обработки ошибок
make test-errors

# Тесты утилит
make test-utils

# Тесты клавиатур и фильтров
make test-keyboards

Тесты с покрытием

# Покрытие с выводом в терминал
make test-coverage

# Покрытие с HTML отчетом
make test-html

Фильтрация тестов

# Только unit тесты
pytest -m unit

# Только интеграционные тесты
pytest -m integration

# Только асинхронные тесты
pytest -m asyncio

# Исключить медленные тесты
pytest -m "not slow"

# Конкретный файл тестов
pytest tests/test_bot.py

# Конкретный тест
pytest tests/test_bot.py::TestBotStartup::test_bot_initialization

Типы тестов

Unit тесты

Тестируют отдельные функции и компоненты в изоляции:

• Вспомогательные функции (get_first_name, get_text_message)
• Утилиты (BaseDependencyFactory, get_message)
• Фильтры (ChatTypeFilter)
• Клавиатуры

Интеграционные тесты

Тестируют взаимодействие между компонентами:

• Регистрация роутеров в диспетчере
• Обработка сообщений через хэндлеры
• Интеграция с базой данных

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

Тестируют асинхронные функции:

• Хэндлеры сообщений
• Запуск бота
• Обработка медиа-контента

Моки и фикстуры

Основные фикстуры

• mock_message - Мок сообщения Telegram
• mock_state - Мок состояния FSM
• mock_db - Мок базы данных
• mock_bot - Мок бота
• mock_dispatcher - Мок диспетчера
• mock_factory - Мок фабрики зависимостей

Специализированные фикстуры

• sample_photo_message - Сообщение с фото
• sample_video_message - Сообщение с видео
• sample_audio_message - Сообщение с аудио
• sample_voice_message - Голосовое сообщение
• sample_video_note_message - Видеокружок
• sample_media_group - Медиагруппа
• sample_text_message - Текстовое сообщение

Покрытие тестами

Основные компоненты

• ✅ Запуск бота (start_bot)
• ✅ Приватные хэндлеры (handle_start_message, suggest_post, etc.)
• ✅ Обработка медиа-контента (фото, видео, аудио, голос)
• ✅ Обработка ошибок и исключений
• ✅ Утилиты и вспомогательные функции
• ✅ Клавиатуры и фильтры
• ✅ Фабрика зависимостей

Тестируемые сценарии

• ✅ Новые пользователи
• ✅ Существующие пользователи
• ✅ Пользователи без username
• ✅ Обработка различных типов контента
• ✅ Медиагруппы
• ✅ Ошибки при получении стикеров
• ✅ Ошибки базы данных
• ✅ Граничные случаи (пустой текст, отсутствие подписей)

Настройка окружения

Переменные окружения

Для тестов не требуются реальные токены бота или подключения к базе данных, так как все внешние зависимости замоканы.

Конфигурация pytest

Настройки pytest находятся в файле pytest.ini:

• Автоматический режим asyncio
• Фильтрация предупреждений
• Маркеры для категоризации тестов

Добавление новых тестов

Структура теста

@pytest.mark.asyncio
async def test_function_name(mock_message, mock_state, mock_db):
    """Описание теста"""
    # Arrange (подготовка)
    mock_message.text = "test"
    
    # Act (действие)
    result = await function_to_test(mock_message, mock_state)
    
    # Assert (проверка)
    assert result is True
    mock_message.answer.assert_called_once()

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

@pytest.mark.unit  # Unit тест
@pytest.mark.integration  # Интеграционный тест
@pytest.mark.asyncio  # Асинхронный тест
@pytest.mark.slow  # Медленный тест

Использование фикстур

def test_with_fixtures(mock_message, sample_photo_message, mock_db):
    # Используем готовые фикстуры
    pass

Отладка тестов

Подробный вывод

pytest -v -s

Остановка на первой ошибке

pytest -x

Вывод полного traceback

pytest --tb=long

Запуск конкретного теста

pytest tests/test_bot.py::TestPrivateHandlers::test_handle_start_message_new_user -v

CI/CD интеграция

Тесты могут быть интегрированы в CI/CD pipeline:

# Пример для GitHub Actions
- name: Run tests
  run: |
    make install
    make test-coverage

Покрытие кода

Для просмотра покрытия кода:

make test-html
# Открыть htmlcov/index.html в браузере

Лучшие практики

1. Изоляция тестов - каждый тест должен быть независимым
2. Использование моков - избегайте реальных внешних зависимостей
3. Описательные имена - имена тестов должны описывать что тестируется
4. Arrange-Act-Assert - структурируйте тесты по этому паттерну
5. Фикстуры - используйте фикстуры для переиспользования кода
6. Маркировка - правильно маркируйте тесты для фильтрации

Устранение неполадок

Ошибки импорта

Убедитесь, что Python path настроен правильно:

export PYTHONPATH="${PYTHONPATH}:$(pwd)"

Ошибки asyncio

Для асинхронных тестов используйте маркер @pytest.mark.asyncio

Ошибки моков

Проверьте, что все внешние зависимости замоканы:

with patch('module.function') as mock_func:
    # тест

Медленные тесты

Используйте маркер @pytest.mark.slow для медленных тестов и исключайте их при необходимости:

pytest -m "not slow"