Перейти к содержанию
10 минут чтения
Тема: Практика Telegram · PHP · Тестирование

Как тестировать Telegram-бота, не отправляя сообщения клиентам

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

Отделяем тестовое окружение целиком

Создайте отдельного бота через BotFather и выделенный чат команды. Используйте другую БД или схему, отдельные очереди, webhook URL и конфигурацию. Подмена только chat_id недостаточна: тест может изменить реальную заявку, запустить платёжный сценарий или передать данные в CRM ещё до отправки сообщения.

Рабочие секреты не должны быть доступны тестовому процессу. Для сетевой проверки заведите явный список разрешённых тестовых получателей и остановку при попытке отправить вне этого списка. Для локальных тестов по возможности запретите исходящую сеть: ошибочно подключённый реальный клиент тогда не выполнит запрос.

Не меняйте webhook рабочего бота на тестовый адрес и не запускайте getUpdates тем же токеном параллельно. Это вмешательство в доставку действующих событий. Локальные фикстуры передавайте в обработчик напрямую, а end-to-end проверку выполняйте отдельным ботом.

Готовим небольшие фиктивные события

Сохраните по одному понятному JSON на каждый существенный тип: сообщение, callback_query, файл, альбом или заявка на вступление. Используйте вымышленные ID и тексты. Реальные updates перед копированием нужно очистить от токенов, имён, телефонов, ссылок доступа и иных персональных данных.

JSON · fixture-message.json
{
  "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 · test-reply.php
<?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";
Bash · Локальный запуск
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.

Проверяем старые кнопки и права

Сохраните callback с внутренним ID заявки. Затем измените состояние заявки и повторите нажатие. Если заявка закрыта, обработчик должен ответить понятным отказом и не повторить действие. Удаление кнопки из сообщения помогает интерфейсу, но не заменяет проверку текущего состояния на сервере.

Проверьте callback от другого пользователя, менеджера со снятой ролью, для другого бота и с изменённым ID. Пользовательские callback_data не должны определять доступ. Обработчик ищет запись в своей области и проверяет полномочия по отправителю подтверждённого update.

Отдельно проверьте двойное нажатие и одновременное решение двух операторов. Ожидается один успешный переход состояния, а не два вызова внешнего действия. Для механики кнопок полезно руководство по callback_query.

Проводим короткую проверку отдельным ботом

После локальных проверок подключите тестовый бот к изолированному webhook. Отправьте /start, нажмите кнопку и загрузите маленький файл, если такой сценарий затронут. Проверьте путь от входящего события до записи в БД и ответа в разрешённый тестовый чат.

Сверьте через getMe, что подключён тестовый бот, и проверьте его webhook URL. Настройки Privacy Mode, права в тестовой группе и способ запуска Mini App должны соответствовать проверяемому сценарию. Успешный fake не подтверждает права в Telegram, TLS, доставку файлов или ограничения клиента.

Для BotGate тестовому окружению нужен отдельный тестовый бот и подходящий ключ доступа. Подмена транспорта проверяет вашу обработку ответа; настоящая интеграция проверяет ещё авторизацию шлюза и его контракт ошибок. В частности, отдельно моделируйте Telegram 429 внутри HTTP 400 и собственный HTTP 429 BotGate.

Что считать готовой проверкой

В отчёте разделите проверенные локальные решения, проверки в тестовом Telegram и ещё не выполненную production-проверку. Укажите сценарии и ожидаемые последствия: одна заявка, один переход состояния, отсутствие повторной отправки при неизвестном исходе. Число зелёных тестов без описания границ не доказывает готовность всей интеграции.

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