ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Тестирование модулей (ErisPulse-Testing)

Tip

Когда стоит читать этот документ: при написании автоматических тестов для собственного модуля. Если это не нужно, пропустите — на использование остальных функций это не влияет.

ErisPulse-Testing — официальный набор инструментов для тестирования: предоставляет TestBot, фабрику тестовых событий, перехват исходящих сообщений и интерфейс утверждений, благодаря чему тестирование модулей так же просто, как написание обычного pytest.

pip install ErisPulse-Testing

Инструмент этапа разработки с односторонней зависимостью от фреймворка, во время выполнения не вмешивается в работу вовсе. Для smoke-тестов с реальным подключением к платформе адаптеров используйте tests/devs/test_adapter.py из репозитория фреймворка.

Быстрый старт

import pytest
from ErisPulse.Core.Event.command import command
from ErisPulse_Testing import TestBot, create_command_event

async def test_daily(make_testbot):
    async with make_testbot(prefix="/") as bot:
        @command("daily", cooldown="1d", cooldown_reply="Вы уже отмечались сегодня")
        async def daily(event):
            await event.reply("Вы успешно отметились!")

        await bot.dispatch(create_command_event("daily", user_id="123"))
        assert bot.last_reply.text == "Вы успешно отметились!"

        await bot.dispatch(create_command_event("daily", user_id="123"))
        bot.assert_reply_contains("Вы успешно отметились")   # второй вызов попадает в кулдаун

TestBot рекомендуется использовать через async with: при запуске регистрируется MockAdapter (перехватывает все исходящие сообщения), отключается дедупликация событий, применяются переопределения конфигурации; при выходе автоматически очищается глобальное состояние фреймворка, что исключает взаимное загрязнение тестовых случаев.

Поставляемые pytest-фикстуры (доступны автоматически после установки):

  • testbot: стандартный TestBot уровня function (platform=test, префикс /)
  • make_testbot(**kwargs): фабрика с настраиваемыми параметрами (prefix / config / platform / bot_id ...)

Рекомендуется настроить asyncio_mode = "auto" в конфигурации тестового проекта ([tool.pytest.ini_options]) или добавлять к тестам @pytest.mark.asyncio.

Фабрика событий

Функция Описание
create_message_event(text, user_id=..., group_id=None, ...) Событие сообщения; если group_id пуст — личный чат
create_command_event("roll 3", prefix="/") Сообщение-команда (префикс добавляется автоматически; если он уже есть, повторно не добавляется)
create_notice_event(type, ...) Событие уведомления (например, friend_add)
create_request_event(type, ...) Событие запроса (например, заявка в друзья)
create_meta_event("connect", ...) Мета-событие (connect переводит бота в онлайн)

Все события используют уникальный id на основе uuid, что естественным образом обходит дедупликацию событий во фреймворке.

Примечание: синтетические события не содержат исходных данных платформы (event.get_raw() возвращает пустой dict). Для определения сценария (групповой или личный чат и т. п.) используйте аксессоры event.is_group_message() / event.get_detail_type() / event.get_group_id() и подобные, не читайте raw.

TestBot API

Диспетчеризация

trace = await bot.dispatch(event)          # диспетчеризует и ждёт завершения обработчиков, возвращает цепочку решений
await bot.dispatch(event, drain=False)     # первое сообщение интеракции: без ожидания (обработчик wait_reply остаётся активным)
await bot.send_message("Привет")           # быстрый способ диспетчеризации сообщения
await bot.reply_as("18", user_id="u1")     # имитирует ответ пользователя в wait_reply (автоматически ждёт готовности waiter)

dispatch() после emit собирает (gather) все находящиеся в полёте задачи обработчиков; возврат означает завершение обработки — в тестах не нужен sleep.

Утверждения для исходящих сообщений

bot.replies                # все исходящие (список SentMessage)
bot.last_reply.text        # текст последнего ответа
bot.replies_to("123")      # фильтрация по адресату
bot.clear_replies()        # изоляция утверждений между этапами
bot.assert_replied()                       # исходящие есть
bot.assert_replied(contains="отметились", to="123")
bot.assert_not_replied()                   # нет ни одного исходящего
bot.assert_reply_contains("Вы успешно отметились")   # есть исходящее, содержащее указанный текст
await bot.wait_for_reply(timeout=2)        # дождаться появления асинхронного ответа

Поля SentMessage: text (первый сегмент типа text), segments (полные сегменты сообщения), target_type / target_id / bot_id (контекст отправки), has_modifier("at") и др.

Загрузка модулей

await bot.load_module("MyModule")   # имя уже зарегистрированного модуля (нужно, чтобы фреймворк выполнил sdk.init() и завершил обнаружение entry-point)
await bot.load_module(MyModule)     # или подкласс BaseModule (автоматические register + load, рекомендуется)
await bot.unload_module("MyModule")

Команды / обработчики событий, зарегистрированные внутри on_load, принадлежат модулю и автоматически очищаются при выгрузке — можно напрямую проверять утверждение «после выгрузки команда перестаёт работать». Примечание: строковая форма не выполняет сканирование entry-point (TestBot не инициализирует процесс обнаружения фреймворка); для тестирования модулей с мягкой зависимостью передавайте непосредственно объект класса (или после самостоятельного module.register передавайте имя).

Подмена зависимостей (требуется EP>=2.9.0-dev)

with bot.patch_dependency(get_session, fake_session) as mock:
    await bot.dispatch(create_command_event("query"))
    assert mock.called

Заменяется функция, на которую ссылается объявление Depends(get_session) в реестре команд; при выходе из with всё автоматически восстанавливается.

Переопределение конфигурации

bot = TestBot(prefix="//", config={
    "ErisPulse.event.command.case_sensitive": False,
    "MyModule.api_key": "test-key",     # конфигурация модуля (доступна через self.cfg)
})

Значения внедряются через слой конфигурации в памяти; префикс команд и т. п. вступают в силу немедленно, как при горячем обновлении. Два замечания:

  1. Запись на диск: переопределения согласно стратегии отложенной записи фреймворка (по умолчанию около 5 секунд) попадают в config/config.toml в cwd — добавьте config/ в .gitignore репозитория тестируемого проекта;
  2. Конфликт с записью конфигурации модулем во время выполнения (известное ограничение): когда тестируемый модуль записывает конфигурацию целыми секциями (self.cfg = ..., например список подписок) одновременно с точечными переопределениями здесь, возникает проблема согласованности чтения/записи в ConfigManager — при чтении целой секции модуль может не увидеть значения переопределений, а переопределения могут быть затёрты записью целой секции при сохранении на диск (исправлено в ErisPulse 2.9.0-dev.2, версии 2.8.x всё ещё затронуты). Для тестов, связанных с «записью конфигурации во время выполнения», в 2.8.x рекомендуется сбрасывать соответствующие секции конфигурации в fixture путём записи целой секции.

Цепочка решений диспетчеризации (диагностика «почему команда не сработала»; требуется EP>=2.9.0-dev)

dispatch() возвращает DispatchTrace — причинно-следственную цепочку каждой точки проверки, пройденной при данной диспетчеризации:

trace = await bot.dispatch(create_command_event("dailyx", user_id="123"))

trace.verdict        # executed / rejected / dropped / failed / no_match / passed
trace.explain()      # построчное причинно-следственное пояснение (на текущем языке)
trace.command        # имя совпавшей команды (None, если совпадения нет)
trace.steps("cooldown")  # фильтрация записей решений по этапам

trace.assert_executed("daily")  # утверждение выполнения (при ошибке прикладывается полная цепочка)
trace.assert_rejected()         # утверждение отклонения по решению, связанному с правами
trace.assert_dropped()          # утверждение тихого отбрасывания (кулдаун и т. п.)
trace.assert_no_match()         # утверждение отсутствия совпадения с командой

Покрытие решений: проверка текста команды, совпадение команды (при несовпадении даются подсказки по написанию), область действия, ACL пользователя, проверка владельца, функции прав, тихое отбрасывание при кулдауне, разбор аргументов, результат выполнения, вето middleware.

В производственной среде для сбора и отображения цепочки решений также можно использовать встроенный в фреймворк ErisPulse.Core.Event.trace (start_dispatch_trace() / format_dispatch_trace()).

Что дальше

Тесты выявили проблемы типа «команда не сработала»

Тесты пройдены, готовимся к публикации