aiogram_bot_tester 0.1.0__tar.gz

aiogram_bot_tester-0.1.0/PKG-INFO

@@ -0,0 +1,511 @@
+Metadata-Version: 2.3
+Name: aiogram_bot_tester
+Version: 0.1.0
+Summary: Test your Telegram bots easily
+Requires-Dist: aiogram>=3.28.2
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# aiogram_bot_tester
+
+![aiogram](https://img.shields.io/badge/aiogram-3.x-blue?logo=telegram)
+![telegram](https://img.shields.io/badge/telegram-bot-blue?logo=telegram)
+![status](https://img.shields.io/badge/status-WIP-orange)
+![python](https://img.shields.io/badge/python-3.10+-blue?logo=python)
+
+**Navigation / Навигация** - [English version](#english-version) -
+[Русская версия](#русская-версия)
+
+A lightweight testing utility for **offline testing of aiogram bots without real Telegram API calls**.
+
+Its goal is to make it easy to test bot logic deterministically by simulating Telegram updates, intercepting bot API calls, and exposing a clean assertion-friendly response layer.
+
+---
+
+# English Version
+
+## Installation
+
+With pip:
+
+```bash
+pip install git+https://github.com/samedit66/aiogram-bot-tester.git
+```
+
+With poetry:
+
+```bash
+poetry add git+https://github.com/samedit66/aiogram-bot-tester.git
+```
+
+With uv:
+
+```bash
+uv add git+https://github.com/samedit66/aiogram-bot-tester.git
+```
+
+---
+
+## What is this?
+
+`aiogram_bot_tester` is a testing framework for bots built with `aiogram`.
+
+Instead of running a real Telegram bot, it:
+
+- simulates incoming Telegram updates (`Message`, `CallbackQuery`)
+- intercepts outgoing bot API calls (`send_message`, etc.)
+- captures state changes (`FSM`)
+- provides a clean assertion API
+
+#### Goal
+
+Enable fast, deterministic, offline testing of Telegram bots without network, tokens, or Telegram API dependency.
+
+---
+
+## Quick example
+
+```python
+from aiogram_bot_tester import BotTester
+
+tester = BotTester.from_routers(router)
+
+response = await tester.send_message("/start")
+
+assert response.text == "Hello"
+assert response.has_inline_button("Press")
+```
+
+---
+
+## Core API
+
+### BotTester.from_routers(*routers)
+
+Construct a `BotTester` instance from a sequence of `Routers`s.
+
+```python
+tester = BotTester.from_routers(router)
+```
+
+### send_message(text, **kwargs)
+
+Send a message to the bot. Returns a special `Response` object described below.
+
+```python
+response = await tester.send_message("/start")
+assert response.text == "Hello"
+```
+
+### click_reply_button(text, **kwargs)
+
+Simulates clicking a reply button. Actually, it's just another way of calling `send_message`. Exists just to clarify intention.
+
+```python
+response = await tester.click_reply_button("Option A")
+```
+
+### click_inline_button(label)
+
+Simulates clicking an inline button.
+
+```python
+response = await tester.click_inline_button("Press")
+```
+
+---
+
+## Response object
+
+Each interaction with a `BotTester` returns a `Response` object.
+
+```python
+@dataclass
+class Response:
+    text: str | None
+    state: State | None
+    message: object | None
+```
+
+### Response.text
+
+Last bot message text.
+
+### Response.state
+
+FSM state.
+
+Example:
+
+```python
+class Form(StatesGroup):
+    name = State()
+    surname = State()
+    age = State()
+
+# Inside a test:
+
+response = await tester.send_message("/start")
+assert response.state == Form.name # in_state() method does the same
+```
+
+### Response.contains(substring)
+
+Returns `True` if this response text contains the given `substring`, `False` otherwise.
+
+Example:
+
+```python
+assert response.contains("Hello")
+```
+
+### Response.matches(regex)
+
+Returns `True` if this response text matches the given `regex`, `False` otherwise.
+
+Example:
+
+```python
+assert response.matches("\d+")
+```
+
+### Response.has_inline_button(label)
+
+Returns `True` if this response has an inline button with `label`, `False` otherwise.
+
+Example:
+
+```python
+assert response.has_inline_button("Click me!")
+```
+
+### Response.has_reply_button(label)
+
+Returns `True` if this response has a button with `label`, `False` otherwise.
+
+Example:
+
+```python
+assert response.has_reply_button("Click me!")
+```
+
+### Response.has_inline_keyboard_like(keyboard)
+
+Returns `True` if this response has the specified inline `keyboard`, `False` otherwise.
+
+Example:
+
+```python
+assert response.has_inline_keyboard_like([
+    ["Yes", "No"],
+    ["Cancel"],
+])
+```
+
+### Response.has_reply_keyboard_like(keyboard)
+
+Returns `True` if this response has the specified reply `keyboard`, `False` otherwise.
+
+Example:
+
+```python
+assert response.has_reply_keyboard_like([
+    ["1", "2", "3"],
+    ["4", "5", "6"],
+])
+```
+
+### Response.in_state(state)
+
+Returns `True` if after this response the state is `state`, `False` otherwise.
+
+Example:
+
+```python
+assert response.in_state(Form.name)
+```
+
+---
+
+## 🚀 Full example
+
+```python
+import pytest
+from aiogram import Router, F
+from aiogram.types import Message, CallbackQuery
+from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup
+
+from aiogram_bot_tester import BotTester
+
+router = Router()
+
+@router.message()
+async def echo(message: Message):
+    await message.answer(
+        f"Echo: {message.text}",
+        reply_markup=InlineKeyboardMarkup(
+            inline_keyboard=[
+                [InlineKeyboardButton(text="Press me", callback_data="press")]
+            ]
+        ),
+    )
+
+@router.callback_query(F.data == "press")
+async def on_press(callback: CallbackQuery):
+    await callback.message.answer("Button clicked!")
+
+@pytest.mark.asyncio
+async def test_full_flow():
+    tester = BotTester.from_routers(router)
+
+    response = await tester.send_message("Hello")
+    assert response.text == "Echo: Hello"
+
+    response = await tester.click_inline_button("Press me")
+    assert response.text == "Button clicked!"
+```
+
+------------------------------------------------------------------------
+
+# Русская версия
+
+## Установка
+
+Через pip:
+
+```bash
+pip install git+https://github.com/samedit66/aiogram-bot-tester.git
+```
+
+Через poetry:
+
+```bash
+poetry add git+https://github.com/samedit66/aiogram-bot-tester.git
+```
+
+Через uv:
+
+```bash
+uv add git+https://github.com/samedit66/aiogram-bot-tester.git
+```
+
+---
+
+## Что это?
+
+`aiogram_bot_tester` это тестировочный фреймворк для Telegram-ботов, написанных на `aiogram`.
+
+Он:
+
+- симулирует отправку различных Telegram-апдейтов (`Message`, `CallbackQuery`)
+- предоставляет знакомый интерфейс для работы с ботом (`send_message` и т.д.)
+- хранит информацию о состоянии (`FSM`)
+- предоставляет чистый и красивый API
+
+#### Цель
+
+Предоставить быстрое, детерменированное и оффлайн тестирование функционала Telegram-бота.
+
+---
+
+## Пример
+
+```python
+from aiogram_bot_tester import BotTester
+
+tester = BotTester.from_routers(router)
+
+response = await tester.send_message("/start")
+
+assert response.text == "Привет"
+assert response.has_inline_button("Нажми меня!")
+```
+
+---
+
+## Core API
+
+### BotTester.from_routers(*routers)
+
+Создает объект `BotTester` из набора роутеров.
+
+```python
+tester = BotTester.from_routers(router1, router2, router3)
+```
+
+### send_message(text, **kwargs)
+
+Симулирует отправку сообщения боту. Возвращает специальный объект `Response`, рассматриваемый далее.
+
+```python
+response = await tester.send_message("/start")
+assert response.text == "Привет"
+```
+
+### click_reply_button(text, **kwargs)
+
+Симулирует нажатие на reply-кнопку. На самом деле, это просто синоним для метода `send_message`, но с названием отражающим суть.
+
+```python
+response = await tester.click_reply_button("Вариант А")
+```
+
+### click_inline_button(label)
+
+Симулирует нажатие на inline-кнопку.
+
+```python
+response = await tester.click_inline_button("Нажми")
+```
+
+---
+
+## Response object
+
+В результате любого взаимодействия с `BotTester`, возвращается объект-ответ `Response`.s
+
+```python
+@dataclass
+class Response:
+    text: str | None
+    state: State | None
+    message: object | None
+```
+
+### Response.text
+
+Последнее сообщение бота.
+
+### Response.state
+
+Состояние.
+
+Пример:
+
+```python
+class Form(StatesGroup):
+    name = State()
+    surname = State()
+    age = State()
+
+# Внутри теста:
+
+response = await tester.send_message("/start")
+assert response.state == Form.name # in_state() делает аналогичное действие
+```
+
+### Response.contains(substring)
+
+Возвращает `True`, если текст ответа содержит указанную подстроку, иначе `False`.
+
+Пример:
+
+```python
+assert response.contains("Привет")
+```
+
+### Response.matches(regex)
+
+Возвращает `True`, если текст ответа соответствует регулярному выражению, иначе `False`.
+
+Пример:
+
+```python
+assert response.matches("\d+")
+```
+
+### Response.has_inline_button(label)
+
+Возвращает `True`, если в ответе есть inline-кнопка с указанным текстом.
+
+Привет:
+
+```python
+assert response.has_inline_button("Нажми меня!")
+```
+
+### Response.has_reply_button(label)
+
+Возвращает `True`, если в ответе есть reply-кнопка с указанным текстом.
+
+Example:
+
+```python
+assert response.has_reply_button("Нажми меня!")
+```
+
+### Response.has_inline_keyboard_like(keyboard)
+
+Возвращает `True`, если inline-клавиатура совпадает с заданной структурой.
+
+Example:
+
+```python
+assert response.has_inline_keyboard_like([
+    ["Да", "Нет"],
+    ["Отмена"],
+])
+```
+
+### Response.has_reply_keyboard_like(keyboard)
+
+Возвращает `True`, если reply-клавиатура совпадает с заданной структурой.
+
+Example:
+
+```python
+assert response.has_reply_keyboard_like([
+    ["1", "2", "3"],
+    ["4", "5", "6"],
+])
+```
+
+### Response.in_state(state)
+
+Возвращает `True`, если бот находится в заданном состоянии.
+
+Пример:
+
+```python
+assert response.in_state(Form.name)
+```
+
+---
+
+## 🚀 Полный пример теста
+
+```python
+import pytest
+from aiogram import Router, F
+from aiogram.types import Message, CallbackQuery
+from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup
+
+from aiogram_bot_tester import BotTester
+
+router = Router()
+
+@router.message()
+async def echo(message: Message):
+    await message.answer(
+        f"Echo: {message.text}",
+        reply_markup=InlineKeyboardMarkup(
+            inline_keyboard=[
+                [InlineKeyboardButton(text="Нажми меня!", callback_data="press")]
+            ]
+        ),
+    )
+
+@router.callback_query(F.data == "press")
+async def on_press(callback: CallbackQuery):
+    await callback.message.answer("Кнопка нажата!")
+
+@pytest.mark.asyncio
+async def test_full_flow():
+    tester = BotTester.from_routers(router)
+
+    response = await tester.send_message("Hello")
+    assert response.text == "Echo: Hello"
+
+    response = await tester.click_inline_button("Нажми меня!")
+    assert response.text == "Кнопка нажата!"
+```

aiogram_bot_tester-0.1.0/README.md

@@ -0,0 +1,503 @@
+# aiogram_bot_tester
+
+![aiogram](https://img.shields.io/badge/aiogram-3.x-blue?logo=telegram)
+![telegram](https://img.shields.io/badge/telegram-bot-blue?logo=telegram)
+![status](https://img.shields.io/badge/status-WIP-orange)
+![python](https://img.shields.io/badge/python-3.10+-blue?logo=python)
+
+**Navigation / Навигация** - [English version](#english-version) -
+[Русская версия](#русская-версия)
+
+A lightweight testing utility for **offline testing of aiogram bots without real Telegram API calls**.
+
+Its goal is to make it easy to test bot logic deterministically by simulating Telegram updates, intercepting bot API calls, and exposing a clean assertion-friendly response layer.
+
+---
+
+# English Version
+
+## Installation
+
+With pip:
+
+```bash
+pip install git+https://github.com/samedit66/aiogram-bot-tester.git
+```
+
+With poetry:
+
+```bash
+poetry add git+https://github.com/samedit66/aiogram-bot-tester.git
+```
+
+With uv:
+
+```bash
+uv add git+https://github.com/samedit66/aiogram-bot-tester.git
+```
+
+---
+
+## What is this?
+
+`aiogram_bot_tester` is a testing framework for bots built with `aiogram`.
+
+Instead of running a real Telegram bot, it:
+
+- simulates incoming Telegram updates (`Message`, `CallbackQuery`)
+- intercepts outgoing bot API calls (`send_message`, etc.)
+- captures state changes (`FSM`)
+- provides a clean assertion API
+
+#### Goal
+
+Enable fast, deterministic, offline testing of Telegram bots without network, tokens, or Telegram API dependency.
+
+---
+
+## Quick example
+
+```python
+from aiogram_bot_tester import BotTester
+
+tester = BotTester.from_routers(router)
+
+response = await tester.send_message("/start")
+
+assert response.text == "Hello"
+assert response.has_inline_button("Press")
+```
+
+---
+
+## Core API
+
+### BotTester.from_routers(*routers)
+
+Construct a `BotTester` instance from a sequence of `Routers`s.
+
+```python
+tester = BotTester.from_routers(router)
+```
+
+### send_message(text, **kwargs)
+
+Send a message to the bot. Returns a special `Response` object described below.
+
+```python
+response = await tester.send_message("/start")
+assert response.text == "Hello"
+```
+
+### click_reply_button(text, **kwargs)
+
+Simulates clicking a reply button. Actually, it's just another way of calling `send_message`. Exists just to clarify intention.
+
+```python
+response = await tester.click_reply_button("Option A")
+```
+
+### click_inline_button(label)
+
+Simulates clicking an inline button.
+
+```python
+response = await tester.click_inline_button("Press")
+```
+
+---
+
+## Response object
+
+Each interaction with a `BotTester` returns a `Response` object.
+
+```python
+@dataclass
+class Response:
+    text: str | None
+    state: State | None
+    message: object | None
+```
+
+### Response.text
+
+Last bot message text.
+
+### Response.state
+
+FSM state.
+
+Example:
+
+```python
+class Form(StatesGroup):
+    name = State()
+    surname = State()
+    age = State()
+
+# Inside a test:
+
+response = await tester.send_message("/start")
+assert response.state == Form.name # in_state() method does the same
+```
+
+### Response.contains(substring)
+
+Returns `True` if this response text contains the given `substring`, `False` otherwise.
+
+Example:
+
+```python
+assert response.contains("Hello")
+```
+
+### Response.matches(regex)
+
+Returns `True` if this response text matches the given `regex`, `False` otherwise.
+
+Example:
+
+```python
+assert response.matches("\d+")
+```
+
+### Response.has_inline_button(label)
+
+Returns `True` if this response has an inline button with `label`, `False` otherwise.
+
+Example:
+
+```python
+assert response.has_inline_button("Click me!")
+```
+
+### Response.has_reply_button(label)
+
+Returns `True` if this response has a button with `label`, `False` otherwise.
+
+Example:
+
+```python
+assert response.has_reply_button("Click me!")
+```
+
+### Response.has_inline_keyboard_like(keyboard)
+
+Returns `True` if this response has the specified inline `keyboard`, `False` otherwise.
+
+Example:
+
+```python
+assert response.has_inline_keyboard_like([
+    ["Yes", "No"],
+    ["Cancel"],
+])
+```
+
+### Response.has_reply_keyboard_like(keyboard)
+
+Returns `True` if this response has the specified reply `keyboard`, `False` otherwise.
+
+Example:
+
+```python
+assert response.has_reply_keyboard_like([
+    ["1", "2", "3"],
+    ["4", "5", "6"],
+])
+```
+
+### Response.in_state(state)
+
+Returns `True` if after this response the state is `state`, `False` otherwise.
+
+Example:
+
+```python
+assert response.in_state(Form.name)
+```
+
+---
+
+## 🚀 Full example
+
+```python
+import pytest
+from aiogram import Router, F
+from aiogram.types import Message, CallbackQuery
+from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup
+
+from aiogram_bot_tester import BotTester
+
+router = Router()
+
+@router.message()
+async def echo(message: Message):
+    await message.answer(
+        f"Echo: {message.text}",
+        reply_markup=InlineKeyboardMarkup(
+            inline_keyboard=[
+                [InlineKeyboardButton(text="Press me", callback_data="press")]
+            ]
+        ),
+    )
+
+@router.callback_query(F.data == "press")
+async def on_press(callback: CallbackQuery):
+    await callback.message.answer("Button clicked!")
+
+@pytest.mark.asyncio
+async def test_full_flow():
+    tester = BotTester.from_routers(router)
+
+    response = await tester.send_message("Hello")
+    assert response.text == "Echo: Hello"
+
+    response = await tester.click_inline_button("Press me")
+    assert response.text == "Button clicked!"
+```
+
+------------------------------------------------------------------------
+
+# Русская версия
+
+## Установка
+
+Через pip:
+
+```bash
+pip install git+https://github.com/samedit66/aiogram-bot-tester.git
+```
+
+Через poetry:
+
+```bash
+poetry add git+https://github.com/samedit66/aiogram-bot-tester.git
+```
+
+Через uv:
+
+```bash
+uv add git+https://github.com/samedit66/aiogram-bot-tester.git
+```
+
+---
+
+## Что это?
+
+`aiogram_bot_tester` это тестировочный фреймворк для Telegram-ботов, написанных на `aiogram`.
+
+Он:
+
+- симулирует отправку различных Telegram-апдейтов (`Message`, `CallbackQuery`)
+- предоставляет знакомый интерфейс для работы с ботом (`send_message` и т.д.)
+- хранит информацию о состоянии (`FSM`)
+- предоставляет чистый и красивый API
+
+#### Цель
+
+Предоставить быстрое, детерменированное и оффлайн тестирование функционала Telegram-бота.
+
+---
+
+## Пример
+
+```python
+from aiogram_bot_tester import BotTester
+
+tester = BotTester.from_routers(router)
+
+response = await tester.send_message("/start")
+
+assert response.text == "Привет"
+assert response.has_inline_button("Нажми меня!")
+```
+
+---
+
+## Core API
+
+### BotTester.from_routers(*routers)
+
+Создает объект `BotTester` из набора роутеров.
+
+```python
+tester = BotTester.from_routers(router1, router2, router3)
+```
+
+### send_message(text, **kwargs)
+
+Симулирует отправку сообщения боту. Возвращает специальный объект `Response`, рассматриваемый далее.
+
+```python
+response = await tester.send_message("/start")
+assert response.text == "Привет"
+```
+
+### click_reply_button(text, **kwargs)
+
+Симулирует нажатие на reply-кнопку. На самом деле, это просто синоним для метода `send_message`, но с названием отражающим суть.
+
+```python
+response = await tester.click_reply_button("Вариант А")
+```
+
+### click_inline_button(label)
+
+Симулирует нажатие на inline-кнопку.
+
+```python
+response = await tester.click_inline_button("Нажми")
+```
+
+---
+
+## Response object
+
+В результате любого взаимодействия с `BotTester`, возвращается объект-ответ `Response`.s
+
+```python
+@dataclass
+class Response:
+    text: str | None
+    state: State | None
+    message: object | None
+```
+
+### Response.text
+
+Последнее сообщение бота.
+
+### Response.state
+
+Состояние.
+
+Пример:
+
+```python
+class Form(StatesGroup):
+    name = State()
+    surname = State()
+    age = State()
+
+# Внутри теста:
+
+response = await tester.send_message("/start")
+assert response.state == Form.name # in_state() делает аналогичное действие
+```
+
+### Response.contains(substring)
+
+Возвращает `True`, если текст ответа содержит указанную подстроку, иначе `False`.
+
+Пример:
+
+```python
+assert response.contains("Привет")
+```
+
+### Response.matches(regex)
+
+Возвращает `True`, если текст ответа соответствует регулярному выражению, иначе `False`.
+
+Пример:
+
+```python
+assert response.matches("\d+")
+```
+
+### Response.has_inline_button(label)
+
+Возвращает `True`, если в ответе есть inline-кнопка с указанным текстом.
+
+Привет:
+
+```python
+assert response.has_inline_button("Нажми меня!")
+```
+
+### Response.has_reply_button(label)
+
+Возвращает `True`, если в ответе есть reply-кнопка с указанным текстом.
+
+Example:
+
+```python
+assert response.has_reply_button("Нажми меня!")
+```
+
+### Response.has_inline_keyboard_like(keyboard)
+
+Возвращает `True`, если inline-клавиатура совпадает с заданной структурой.
+
+Example:
+
+```python
+assert response.has_inline_keyboard_like([
+    ["Да", "Нет"],
+    ["Отмена"],
+])
+```
+
+### Response.has_reply_keyboard_like(keyboard)
+
+Возвращает `True`, если reply-клавиатура совпадает с заданной структурой.
+
+Example:
+
+```python
+assert response.has_reply_keyboard_like([
+    ["1", "2", "3"],
+    ["4", "5", "6"],
+])
+```
+
+### Response.in_state(state)
+
+Возвращает `True`, если бот находится в заданном состоянии.
+
+Пример:
+
+```python
+assert response.in_state(Form.name)
+```
+
+---
+
+## 🚀 Полный пример теста
+
+```python
+import pytest
+from aiogram import Router, F
+from aiogram.types import Message, CallbackQuery
+from aiogram.types import InlineKeyboardButton, InlineKeyboardMarkup
+
+from aiogram_bot_tester import BotTester
+
+router = Router()
+
+@router.message()
+async def echo(message: Message):
+    await message.answer(
+        f"Echo: {message.text}",
+        reply_markup=InlineKeyboardMarkup(
+            inline_keyboard=[
+                [InlineKeyboardButton(text="Нажми меня!", callback_data="press")]
+            ]
+        ),
+    )
+
+@router.callback_query(F.data == "press")
+async def on_press(callback: CallbackQuery):
+    await callback.message.answer("Кнопка нажата!")
+
+@pytest.mark.asyncio
+async def test_full_flow():
+    tester = BotTester.from_routers(router)
+
+    response = await tester.send_message("Hello")
+    assert response.text == "Echo: Hello"
+
+    response = await tester.click_inline_button("Нажми меня!")
+    assert response.text == "Кнопка нажата!"
+```

aiogram_bot_tester-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "aiogram_bot_tester"
+version = "0.1.0"
+description = "Test your Telegram bots easily"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "aiogram>=3.28.2",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.15.13",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.14,<0.12"]
+build-backend = "uv_build"

aiogram_bot_tester-0.1.0/src/aiogram_bot_tester/__init__.py

@@ -0,0 +1,7 @@
+from .bot_tester import (
+    BotTester,
+)
+
+__all__ = [
+    "BotTester",
+]

aiogram_bot_tester-0.1.0/src/aiogram_bot_tester/bot_tester.py

@@ -0,0 +1,329 @@
+from __future__ import annotations
+
+import copy
+import dataclasses as dc
+import datetime as dt
+import re
+import typing as t
+import unittest.mock as mock
+from typing import ClassVar
+
+import aiogram as aio
+import aiogram.fsm.state as fsm_state
+import aiogram.fsm.storage.memory as fsm_memory
+import aiogram.methods as methods
+import aiogram.types as types
+
+
+@dc.dataclass(frozen=True, slots=True)
+class InlineButton:
+    """Snapshot of an inline keyboard button."""
+
+    text: str
+    """Visible label on the button."""
+
+    callback_data: str | None
+    """Callback payload attached to the button, or ``None`` if absent."""
+
+
+@dc.dataclass(frozen=True, slots=True)
+class CapturedMessage:
+    """Snapshot of a message sent by the bot."""
+
+    text: str | None
+    """Message text, or ``None`` when the bot sent no text."""
+
+    inline_keyboard: list[list[InlineButton]]
+    """Inline keyboard layout captured from the message."""
+
+    reply_keyboard: list[list[str]]
+    """Reply keyboard layout captured from the message."""
+
+
+@dc.dataclass(frozen=True, slots=True)
+class Response:
+    """Result of a synthetic interaction with the bot."""
+
+    text: str | None
+    """Bot text response, or ``None`` when the bot sent no text."""
+
+    state: fsm_state.State | None
+    """FSM state after handling the update, or ``None`` when inactive."""
+
+    message: CapturedMessage | None
+    """
+    Captured outgoing message, if any.
+
+    This includes the message text and any inline or reply keyboards.
+    """
+
+    def contains(self, text: str) -> bool:
+        """Return ``True`` when the response text contains ``text``."""
+        return self.text is not None and text in self.text
+
+    def matches(self, regex: str | re.Pattern[str]) -> bool:
+        """Return ``True`` when the response text matches ``regex``."""
+        pattern = regex if isinstance(regex, re.Pattern) else re.compile(regex)
+        return bool(pattern.match(self.text or ""))
+
+    def has_inline_button(self, label: str) -> bool:
+        """Return ``True`` when an inline button with ``label`` exists."""
+        if self.message is None:
+            return False
+
+        return any(
+            button.text == label
+            for row in self.message.inline_keyboard
+            for button in row
+        )
+
+    def has_reply_button(self, label: str) -> bool:
+        """Return ``True`` when a reply button with ``label`` exists."""
+        if self.message is None:
+            return False
+
+        return any(label in row for row in self.message.reply_keyboard)
+
+    def has_inline_keyboard_like(
+        self,
+        keyboard: list[list[str]],
+    ) -> bool:
+        """Return ``True`` when the inline keyboard matches ``keyboard``."""
+        if self.message is None:
+            return False
+
+        return [
+            [button.text for button in row] for row in self.message.inline_keyboard
+        ] == keyboard
+
+    def has_reply_keyboard_like(
+        self,
+        keyboard: list[list[str]],
+    ) -> bool:
+        """Return ``True`` when the reply keyboard matches ``keyboard``."""
+        if self.message is None:
+            return False
+
+        return self.message.reply_keyboard == keyboard
+
+    def in_state(self, state: fsm_state.State | None) -> bool:
+        """Return ``True`` when the response FSM state equals ``state``."""
+        return self.state == state
+
+
+@dc.dataclass(slots=True)
+class BotTester:
+    """Helper for driving a bot through synthetic updates in tests."""
+
+    bot: aio.Bot
+    """Attached bot instance."""
+
+    dispatcher: aio.Dispatcher
+    """Attached dispatcher instance."""
+
+    messages: list[CapturedMessage] = dc.field(default_factory=list)
+    """Captured outgoing messages in send order."""
+
+    CHAT_ID: ClassVar[int] = 1
+    """Synthetic chat identifier used for generated updates."""
+
+    USER_ID: ClassVar[int] = 1
+    """Synthetic user identifier used for generated updates."""
+
+    def __post_init__(self) -> None:
+        """Attach a mocked transport layer used for capturing bot responses."""
+        self.bot.session.make_request = mock.AsyncMock(
+            side_effect=self._capture_request,
+        )
+
+    @classmethod
+    def from_routers(
+        cls,
+        *routers: aio.Router,
+        token: str = "42:TEST",
+    ) -> BotTester:
+        """Create a tester instance with the provided routers registered."""
+        bot = aio.Bot(token=token)
+
+        dispatcher = aio.Dispatcher(storage=fsm_memory.MemoryStorage())
+        # We perform deepcopy because of the fact, that a single router cannot
+        # be attached to multiple dispatchers
+        dispatcher.include_routers(*[copy.deepcopy(r) for r in routers])
+
+        return cls(bot, dispatcher)
+
+    async def send_message(
+        self,
+        text: str,
+        **message_kwargs: t.Any,
+    ) -> Response:
+        """Send a synthetic message and return the resulting response snapshot."""
+        message = self._create_message(
+            text=text,
+            **message_kwargs,
+        )
+
+        update = types.Update(
+            update_id=1,
+            message=message,
+        )
+
+        await self.dispatcher.feed_update(
+            self.bot,
+            update,
+        )
+
+        return await self._build_response()
+
+    async def click_reply_button(
+        self,
+        text: str,
+        **message_kwargs: t.Any,
+    ) -> Response:
+        """Simulate a reply-keyboard click by sending the button text."""
+        return await self.send_message(
+            text=text,
+            **message_kwargs,
+        )
+
+    async def click_inline_button(
+        self,
+        label: str,
+    ) -> Response:
+        """Simulate clicking an inline button with the given label."""
+        callback_data = self._find_callback_data(label)
+
+        telegram_message = self._create_message(
+            text=self.messages[-1].text or "",
+        )
+
+        callback_query = types.CallbackQuery(
+            id="test-callback-query",
+            from_user=telegram_message.from_user,
+            chat_instance="test-chat-instance",
+            data=callback_data,
+            message=telegram_message,
+            bot=self.bot,
+        )
+
+        update = types.Update(
+            update_id=1,
+            callback_query=callback_query,
+        )
+
+        await self.dispatcher.feed_update(
+            self.bot,
+            update,
+        )
+
+        return await self._build_response()
+
+    def _find_callback_data(
+        self,
+        label: str,
+    ) -> str:
+        """Return callback data associated with the inline button label."""
+        if not self.messages:
+            raise ValueError("No messages available")
+
+        for row in self.messages[-1].inline_keyboard:
+            for button in row:
+                if button.text == label:
+                    if button.callback_data is None:
+                        raise ValueError(
+                            f"Inline button '{label}' has no callback_data"
+                        )
+
+                    return button.callback_data
+
+        raise ValueError(f"Inline button '{label}' not found")
+
+    def _create_message(
+        self,
+        text: str,
+        **message_kwargs: t.Any,
+    ) -> types.Message:
+        """Create a synthetic Telegram message object."""
+        return types.Message(
+            message_id=1,
+            date=dt.datetime.now(),
+            chat=types.Chat(
+                id=self.CHAT_ID,
+                type="private",
+            ),
+            from_user=types.User(
+                id=self.USER_ID,
+                is_bot=False,
+                first_name="Test",
+            ),
+            text=text,
+            bot=self.bot,
+            **message_kwargs,
+        )
+
+    async def _capture_request(
+        self,
+        bot: aio.Bot,
+        method: t.Any,
+        timeout: int | None = None,
+    ) -> mock.MagicMock:
+        """Capture outgoing bot requests for later inspection."""
+        if isinstance(method, methods.SendMessage):
+            self.messages.append(
+                CapturedMessage(
+                    text=method.text,
+                    inline_keyboard=self._extract_inline_keyboard(
+                        method.reply_markup,
+                    ),
+                    reply_keyboard=self._extract_reply_keyboard(
+                        method.reply_markup,
+                    ),
+                )
+            )
+
+        return mock.MagicMock()
+
+    def _extract_inline_keyboard(
+        self,
+        markup: t.Any,
+    ) -> list[list[InlineButton]]:
+        """Extract inline keyboard data from Telegram markup."""
+        if not isinstance(markup, types.InlineKeyboardMarkup):
+            return []
+
+        return [
+            [
+                InlineButton(
+                    text=button.text,
+                    callback_data=button.callback_data,
+                )
+                for button in row
+            ]
+            for row in markup.inline_keyboard
+        ]
+
+    def _extract_reply_keyboard(
+        self,
+        markup: t.Any,
+    ) -> list[list[str]]:
+        """Extract reply keyboard data from Telegram markup."""
+        if not isinstance(markup, types.ReplyKeyboardMarkup):
+            return []
+
+        return [[button.text for button in row] for row in markup.keyboard]
+
+    async def _build_response(self) -> Response:
+        """Build a response snapshot from captured bot state."""
+        state = await self.dispatcher.fsm.get_context(
+            bot=self.bot,
+            chat_id=self.CHAT_ID,
+            user_id=self.USER_ID,
+        ).get_state()
+
+        message = self.messages[-1] if self.messages else None
+
+        return Response(
+            text=message.text if message else None,
+            state=state,
+            message=message,
+        )