aiogram_bot_tester

Your missing test toolkit for Telegram bots.

[!WARNING] This library is under active development. Its API is unstable and may contain frequent breaking changes between releases.

• English tutorial
• Русский туториал

Installation

Stable version:

pip install aiogram_bot_tester

Latest development version:

pip install git+https://github.com/samedit66/aiogram-bot-tester.git

What's that?

aiogram_bot_tester is a lightweight way to test aiogram bots offline, without real Telegram API calls. It helps you simulate updates, check bot responses, and keep tests deterministic, so bot logic can be covered with confidence even when the conversation flow is complex.

Features

• Fully offline testing — run bot scenarios without a Telegram token, network requests, or real API calls.
• Real aiogram pipeline — updates pass through the actual dispatcher, routers, filters, middleware, and FSM machinery.
• Conversation-first API — send messages and commands, start the bot, and tap reply or callback buttons by their visible labels.
• Readable assertions — check message text, regular expressions, buttons, callback data, URLs, and complete keyboard layouts.
• FSM support — assert the current state and inspect FSM data across multi-step conversation flows.
• Flexible test setup — build a tester from reusable routers or an existing dispatcher, pass fake dependencies directly, and attach middleware when needed.

Quick example

import pytest
import aiogram
from aiogram import F
from aiogram.types import CallbackQuery, InlineKeyboardButton, InlineKeyboardMarkup, Message

from aiogram_bot_tester import BotTester

router = aiogram.Router()


@router.message(aiogram.filters.CommandStart())
async def cmd_start(message: Message) -> None:
    await message.answer(
        "Hello! Press Continue or send me your name.",
        reply_markup=InlineKeyboardMarkup(
            inline_keyboard=[
                [InlineKeyboardButton(text="Continue", callback_data="continue")]
            ]
        ),
    )


@router.message(F.text)
async def echo_name(message: Message) -> None:
    await message.answer(f"Nice to meet you, {message.text}!")


@router.callback_query(F.data == "continue")
async def on_continue(callback: CallbackQuery) -> None:
    await callback.message.answer("Please send your name.")


@pytest.mark.asyncio
async def test_flow() -> None:
    tester = BotTester.from_routers(router)

    response = await tester.start()
    response.assert_contains("Hello")
    response.assert_button("Continue")

    response = await tester.tap_button("Continue")
    response.assert_contains("Please send your name.")

    response = await tester.send_message("Bob")
    response.assert_contains("Nice to meet you, Bob!")