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` - Общие фикстуры и конфигурация

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

```bash
make install
```

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

### Все тесты
```bash
make test
```

### Отдельные категории тестов
```bash
# Тесты базы данных
make test-db

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

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

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

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

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

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

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

### Фильтрация тестов
```bash
# Только 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
- Фильтрация предупреждений
- Маркеры для категоризации тестов

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

### Структура теста
```python
@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()
```

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

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

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

### Подробный вывод
```bash
pytest -v -s
```

### Остановка на первой ошибке
```bash
pytest -x
```

### Вывод полного traceback
```bash
pytest --tb=long
```

### Запуск конкретного теста
```bash
pytest tests/test_bot.py::TestPrivateHandlers::test_handle_start_message_new_user -v
```

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

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

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

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

Для просмотра покрытия кода:
```bash
make test-html
# Открыть htmlcov/index.html в браузере
```

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

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

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

### Ошибки импорта
Убедитесь, что Python path настроен правильно:
```bash
export PYTHONPATH="${PYTHONPATH}:$(pwd)"
```

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

### Ошибки моков
Проверьте, что все внешние зависимости замоканы:
```python
with patch('module.function') as mock_func:
    # тест
```

### Медленные тесты
Используйте маркер `@pytest.mark.slow` для медленных тестов и исключайте их при необходимости:
```bash
pytest -m "not slow"
```