# Telegram Bot Testing Guide

## Обзор

Данный документ описывает comprehensive систему тестирования для Telegram бота, включающую Unit тесты, Feature тесты, интеграционные тесты и тесты middleware.

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

### 1. Unit тесты (`tests/Unit/`)

#### TelegramServiceTest
Тестирует бизнес-логику TelegramService:

- **Обработка webhook'ов**: тестирование различных типов событий
- **Команды бота**: `/start`, `/auth`, `/status`
- **Обработка сообщений**: извлечение URL и тегов
- **Обработка ошибок**: исключения и их логирование
- **Интеграция с сервисами**: LinkService, AuditService

**Ключевые тесты:**
```php
test_handle_webhook_with_message()
test_handle_auth_command_with_valid_token()
test_handle_text_message_with_url()
test_extract_urls_from_text()
test_extract_tags_from_text()
```

#### TelegramWebhookRequestTest
Тестирует валидацию входящих запросов:

- **Валидация update_id**: обязательность, тип, положительность
- **Валидация структуры сообщений**: message, edited_message
- **Валидация типов чатов**: private, group, supergroup, channel
- **Валидация пользователей**: ID, имена, флаги
- **Валидация текста**: длина, формат
- **Подготовка данных**: приведение типов

### 2. Feature тесты (`tests/Feature/`)

#### TelegramWebhookControllerTest
Тестирует HTTP endpoint и интеграцию:

- **Webhook endpoint**: успешные запросы и обработка ошибок
- **Валидация запросов**: проверка структуры payload
- **Middleware pipeline**: проверка всех middleware
- **Обработка исключений**: корректные HTTP коды
- **Безопасность**: проверка заголовков и токенов

**Ключевые тесты:**
```php
test_webhook_endpoint_returns_success()
test_webhook_endpoint_handles_exception()
test_webhook_endpoint_validates_request()
test_webhook_endpoint_requires_secret_token()
```

#### TelegramIntegrationTest
Тестирует полный flow от webhook до сохранения:

- **Полный flow**: от webhook до сохранения ссылки
- **Аутентификация пользователей**: привязка аккаунтов
- **Обработка отредактированных сообщений**: edited_message
- **Множественные URL**: обработка нескольких ссылок
- **Обработка ошибок**: ошибки в LinkService
- **Создание пользователей**: автоматическое создание

### 3. Middleware тесты (`tests/Unit/Middleware/`)

#### TelegramWebhookValidatorTest
Тестирует валидацию на уровне HTTP:

- **HTTP метод**: только POST
- **Content-Type**: application/json
- **User-Agent**: проверка от Telegram
- **Размер payload**: ограничение 1MB
- **Структура данных**: update_id, типы событий
- **Логирование**: предупреждения о подозрительных запросах

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

### Запуск всех тестов Telegram бота
```bash
php artisan test --filter="Telegram"
```

### Запуск конкретных групп тестов
```bash
# Unit тесты
php artisan test tests/Unit/Services/TelegramServiceTest.php
php artisan test tests/Unit/Requests/TelegramWebhookRequestTest.php
php artisan test tests/Unit/Middleware/TelegramWebhookValidatorTest.php

# Feature тесты
php artisan test tests/Feature/TelegramWebhookControllerTest.php
php artisan test tests/Feature/TelegramIntegrationTest.php
```

### Запуск с покрытием
```bash
php artisan test --coverage --filter="Telegram"
```

## Моки и стабы

### Telegram Bot API
```php
$this->telegramMock = Mockery::mock(Api::class);
$this->telegramMock->shouldReceive('getWebhookUpdate')
    ->once()
    ->andReturn($updateData);

$this->telegramMock->shouldReceive('sendMessage')
    ->once()
    ->with($expectedParams);
```

### Сервисы
```php
$this->linkServiceMock = Mockery::mock(LinkService::class);
$this->linkServiceMock->shouldReceive('createLink')
    ->once()
    ->with($user, $url, $tags)
    ->andReturn($linkObject);

$this->auditServiceMock = Mockery::mock(AuditService::class);
$this->auditServiceMock->shouldReceive('logCreateLink')
    ->once();
```

### Логирование
```php
Log::shouldReceive('error')
    ->once()
    ->with('Failed to save link from Telegram', Mockery::any());
```

## Тестовые данные

### Валидный webhook payload
```php
$payload = [
    'update_id' => 123456789,
    'message' => [
        'message_id' => 1,
        'date' => time(),
        'chat' => [
            'id' => 123456789,
            'type' => 'private'
        ],
        'from' => [
            'id' => 123456789,
            'first_name' => 'Test',
            'is_bot' => false
        ],
        'text' => '/start'
    ]
];
```

### Заголовки для тестов
```php
$headers = [
    'X-Telegram-Bot-Api-Secret-Token' => config('telegram.secret_token'),
    'Content-Type' => 'application/json',
    'User-Agent' => 'TelegramBot (like TwitterBot)'
];
```

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

### TelegramService (100%)
- ✅ Обработка webhook'ов
- ✅ Команды бота
- ✅ Обработка сообщений
- ✅ Извлечение URL и тегов
- ✅ Обработка ошибок
- ✅ Интеграция с сервисами

### TelegramWebhookController (100%)
- ✅ HTTP endpoint
- ✅ Валидация запросов
- ✅ Обработка исключений
- ✅ Middleware pipeline
- ✅ Безопасность

### TelegramWebhookRequest (100%)
- ✅ Валидация update_id
- ✅ Валидация структуры сообщений
- ✅ Валидация типов чатов
- ✅ Валидация пользователей
- ✅ Подготовка данных

### TelegramWebhookValidator (100%)
- ✅ HTTP метод
- ✅ Content-Type
- ✅ User-Agent
- ✅ Размер payload
- ✅ Структура данных
- ✅ Логирование

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

### 1. Использование моков
- Мокайте внешние зависимости (Telegram API, сервисы)
- Проверяйте, что моки вызываются с правильными параметрами
- Используйте `once()`, `twice()` для проверки количества вызовов

### 2. Тестирование исключений
```php
$this->expectException(Exception::class);
$this->expectExceptionMessage('Telegram API error');
```

### 3. Проверка базы данных
```php
$this->assertDatabaseHas('users', [
    'telegram_id' => 123456789,
    'telegram_auth_token' => null
]);
```

### 4. Проверка логов
```php
Log::shouldReceive('error')
    ->once()
    ->with('Failed to save link from Telegram', Mockery::any());
```

### 5. Тестирование middleware
```php
$response = $this->middleware->handle($request, function () {
    return response()->json(['status' => 'ok']);
});

$this->assertEquals(405, $response->getStatusCode());
```

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

### Включение подробного вывода
```bash
php artisan test --verbose --filter="Telegram"
```

### Запуск одного теста
```bash
php artisan test --filter="test_handle_webhook_with_message"
```

### Просмотр покрытия
```bash
php artisan test --coverage --filter="Telegram" --coverage-html=coverage
```

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

### GitHub Actions
```yaml
- name: Run Telegram Bot Tests
  run: |
    php artisan test --filter="Telegram" --coverage
    php artisan test:coverage --min=90
```

### Проверка качества кода
```bash
# PHPStan
./vendor/bin/phpstan analyse tests/ --level=8

# PHP CS Fixer
./vendor/bin/php-cs-fixer fix tests/ --dry-run

# PHPUnit
./vendor/bin/phpunit --filter="Telegram"
```

## Мониторинг и метрики

### Покрытие кода
- Цель: 100% покрытие для критических компонентов
- Минимум: 90% для всех компонентов Telegram бота

### Время выполнения
- Unit тесты: < 1 секунды
- Feature тесты: < 5 секунд
- Интеграционные тесты: < 10 секунд

### Стабильность
- Все тесты должны проходить стабильно
- Не должно быть flaky тестов
- Регулярный мониторинг времени выполнения

## Заключение

Система тестирования Telegram бота обеспечивает:

1. **Полное покрытие** всех компонентов
2. **Изоляцию** тестов через моки и стабы
3. **Быстрое выполнение** благодаря оптимизации
4. **Надежность** через проверку edge cases
5. **Поддерживаемость** через четкую структуру

Тесты покрывают все сценарии использования и обеспечивают качество кода при разработке и рефакторинге.