Отделяем тестовое окружение целиком
Создайте отдельного бота через BotFather и выделенный чат команды. Используйте другую БД или схему, отдельные очереди, webhook URL и конфигурацию. Подмена только chat_id недостаточна: тест может изменить реальную заявку, запустить платёжный сценарий или передать данные в CRM ещё до отправки сообщения.
Рабочие секреты не должны быть доступны тестовому процессу. Для сетевой проверки заведите явный список разрешённых тестовых получателей и остановку при попытке отправить вне этого списка. Для локальных тестов по возможности запретите исходящую сеть: ошибочно подключённый реальный клиент тогда не выполнит запрос.
Не меняйте webhook рабочего бота на тестовый адрес и не запускайте getUpdates тем же токеном параллельно. Это вмешательство в доставку действующих событий. Локальные фикстуры передавайте в обработчик напрямую, а end-to-end проверку выполняйте отдельным ботом.
Готовим небольшие фиктивные события
Сохраните по одному понятному JSON на каждый существенный тип: сообщение, callback_query, файл, альбом или заявка на вступление. Используйте вымышленные ID и тексты. Реальные updates перед копированием нужно очистить от токенов, имён, телефонов, ссылок доступа и иных персональных данных.
{
"update_id": 101,
"message": {
"message_id": 11,
"date": 1793952000,
"from": {"id": 1001, "is_bot": false, "first_name": "Тест"},
"chat": {"id": 1001, "type": "private"},
"text": "/start"
}
}
Обработчик бизнес-логики получает уже проверенное событие. Подлинность webhook тестируйте отдельно на уровне HTTP-входа. Для BotGate проверьте его HMAC-контракт: правильная подпись проходит, отсутствующая подпись и изменение подписанного тела дают отказ. Для прямого Telegram webhook проверьте совпадение заголовка X-Telegram-Bot-Api-Secret-Token с настроенным secret_token и отказ при отсутствующем или неверном значении. Этот заголовок не является подписью тела. Не выключайте проверку подлинности в рабочем маршруте ради загрузки фикстуры.
Фикстуры должны включать также отсутствующие необязательные поля и незнакомый тип update. Нельзя предполагать, что каждое событие содержит message.text или что callback обязательно содержит обычное доступное сообщение.
Подменяем API на границе приложения
Вынесите вызов API в небольшой интерфейс. Обработчик должен знать, какой метод и параметры он отправляет, а тест решает, какой ответ вернуть. Ниже законченный локальный пример для PHP 8.3+: он не содержит HTTP-клиента, токена и сетевых вызовов.
<?php
declare(strict_types=1);
interface TelegramTransport
{
public function call(string $method, array $parameters): array;
}
final class FakeTelegram implements TelegramTransport
{
public array $calls = [];
public function __construct(private array|Throwable $outcome) {}
public function call(string $method, array $parameters): array
{
$this->calls[] = [$method, $parameters];
if ($this->outcome instanceof Throwable) throw $this->outcome;
return $this->outcome;
}
}
function sendGreeting(TelegramTransport $api, int $chatId): string
{
try {
$response = $api->call('sendMessage', [
'chat_id' => $chatId, 'text' => 'Здравствуйте! Чем помочь?',
]);
} catch (Throwable) {
return 'unknown';
}
if (($response['ok'] ?? null) === true) return 'sent';
if (($response['ok'] ?? null) === false) return 'rejected';
return 'unknown';
}
function check(bool $condition, string $label): void
{
if (!$condition) throw new RuntimeException('FAIL: '.$label);
}
$success = new FakeTelegram(['ok' => true, 'result' => ['message_id' => 7]]);
check(sendGreeting($success, 1001) === 'sent', 'successful reply');
check($success->calls === [['sendMessage', [
'chat_id' => 1001, 'text' => 'Здравствуйте! Чем помочь?',
]]], 'method, recipient and text');
$rejected = new FakeTelegram(['ok' => false, 'error_code' => 403]);
check(sendGreeting($rejected, 1001) === 'rejected', 'explicit rejection');
$timeout = new FakeTelegram(new RuntimeException('Simulated lost response'));
check(sendGreeting($timeout, 1001) === 'unknown', 'unknown outcome');
check(count($timeout->calls) === 1, 'no blind retry');
$invalid = new FakeTelegram([]);
check(sendGreeting($invalid, 1001) === 'unknown', 'malformed response');
echo "All checks passed without network calls\n";
php test-reply.php
В рабочем проекте реализация интерфейса вызывает ваш клиент Telegram или BotGate; в тесте передаётся FakeTelegram. Пример проверяет только принятие решения по ответу и параметры отправки, не webhook, очередь или доставку. Не переносите catch всех исключений без отдельной диагностики программных ошибок: здесь это упрощённая граница учебного клиента.
Если приложение использует Laravel Http, доступны Http::fake и Http::preventStrayRequests. Они подменяют именно Laravel HTTP client. Отдельный SDK на Guzzle или PSR-18 потребует подмены его собственного транспорта: Http::fake не перехватывает любой PHP-запрос автоматически.
Проверяем дубликаты и неизвестный результат
Дважды передайте один update одного бота: ожидается одна бизнес-операция. Затем передайте тот же update_id другого бота: при общей таблице это независимое событие. Уникальность только по update_id без идентификатора бота может ошибочно подавить обработку.
Проверьте два параллельных обработчика на отдельной БД. Последовательный тест не доказывает отсутствие гонки между «проверил наличие» и «создал запись». Защиту должен обеспечивать уникальный ключ или атомарный переход состояния, а не надежда на редкую одновременность.
Смоделируйте сбой после сохранения задачи, но до её запуска: worker должен найти надёжно записанную работу. Отдельно смоделируйте падение после отправки, но до записи sent. Здесь результат остаётся неизвестным — очередной запуск не должен безусловно отправлять второе сообщение.
Для 429 верните фиктивный retry_after и проверьте время следующей попытки и предел повторов через управляемые часы. Не заставляйте тест реально спать несколько минут. Таймаут, явный отказ и подтверждённый лимит — разные исходы, как описано в статье о 429.
Проводим короткую проверку отдельным ботом
После локальных проверок подключите тестовый бот к изолированному webhook. Отправьте /start, нажмите кнопку и загрузите маленький файл, если такой сценарий затронут. Проверьте путь от входящего события до записи в БД и ответа в разрешённый тестовый чат.
Сверьте через getMe, что подключён тестовый бот, и проверьте его webhook URL. Настройки Privacy Mode, права в тестовой группе и способ запуска Mini App должны соответствовать проверяемому сценарию. Успешный fake не подтверждает права в Telegram, TLS, доставку файлов или ограничения клиента.
Для BotGate тестовому окружению нужен отдельный тестовый бот и подходящий ключ доступа. Подмена транспорта проверяет вашу обработку ответа; настоящая интеграция проверяет ещё авторизацию шлюза и его контракт ошибок. В частности, отдельно моделируйте Telegram 429 внутри HTTP 400 и собственный HTTP 429 BotGate.
Что считать готовой проверкой
В отчёте разделите проверенные локальные решения, проверки в тестовом Telegram и ещё не выполненную production-проверку. Укажите сценарии и ожидаемые последствия: одна заявка, один переход состояния, отсутствие повторной отправки при неизвестном исходе. Число зелёных тестов без описания границ не доказывает готовность всей интеграции.
Сохраняйте только полезные фикстуры и проверки поведения, которое может сломаться. Не создавайте тест на каждую строку сообщения, если формулировка не является контрактом. После успешного запуска удалите временные тестовые данные по правилам вашего проекта и убедитесь, что в рабочую очередь они не попали.