Тестирование модулей (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)
})
Значения внедряются через слой конфигурации в памяти; префикс команд и т. п. вступают в силу немедленно, как при горячем обновлении. Два замечания:
- Запись на диск: переопределения согласно стратегии отложенной записи фреймворка (по умолчанию около 5 секунд) попадают в
config/config.tomlв cwd — добавьтеconfig/в.gitignoreрепозитория тестируемого проекта; - Конфликт с записью конфигурации модулем во время выполнения (известное ограничение): когда тестируемый модуль записывает конфигурацию целыми секциями
(
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()).
Что дальше
Тесты выявили проблемы типа «команда не сработала»
Тесты пройдены, готовимся к публикации
- Основные концепции модулей — восполнить детали архитектуры модулей и объявления конфигурации
- Руководство по публикации и магазину модулей — полный процесс публикации на PyPI и в магазине модулей