aiogram-testing 1.1.0__tar.gz → 1.2.0__tar.gz

aiogram_testing-1.2.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: aiogram-testing
+Version: 1.2.0
+Summary: A library for testing your bots on aiogram
+License: MIT
+Author: k0te1ch
+Author-email: khvostov40@gmail.com
+Requires-Python: >=3.12,<3.15
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pytest
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Testing
+Requires-Dist: aiogram (>=3.23,<4)
+Project-URL: Homepage, https://github.com/k0te1ch/aiogram_tests
+Project-URL: Repository, https://github.com/k0te1ch/aiogram_tests
+Description-Content-Type: text/markdown
+
+# Aiogram Tests
+
+***aiogram_tests*** is a testing library for bots written on [aiogram](https://github.com/aiogram/aiogram)
+
+## 📦 Installation
+
+```bash
+pip install aiogram-testing
+```
+
+The import name stays `aiogram_tests`:
+
+```python
+from aiogram_tests import MockedRequester
+```
+
+## 📚 Simple examples
+
+### Simple handler test
+
+#### Simple bot
+
+```python
+from aiogram import Bot, Dispatcher, types
+from aiogram.fsm.context import FSMContext
+
+# Please, keep your bot tokens on environments, this code only example
+bot = Bot('123456789:AABBCCDDEEFFaabbccddeeff-1234567890')
+dp = Dispatcher()
+
+
+@dp.message()
+async def echo(message: types.Message, state: FSMContext) -> None:
+    await message.answer(message.text)
+
+
+if __name__ == '__main__':
+    dp.run_polling(bot)
+
+
+```
+
+#### Test cases
+
+```python
+import pytest
+
+from bot import echo
+
+from aiogram_tests import MockedRequester
+from aiogram_tests.handler import MessageHandler
+from aiogram_tests.types.dataset import MESSAGE
+
+
+@pytest.mark.asyncio
+async def test_echo():
+    request = MockedRequester(MessageHandler(echo))
+    calls = await request.query(message=MESSAGE.as_object(text="Hello, Bot!"))
+    answer_message = calls.send_message.fetchone()
+    assert answer_message.text == "Hello, Bot!"
+
+```
+
+### Checking calls
+
+`query()` returns the Bot API methods the handler called, as aiogram objects (`SendMessage`, `EditMessageText`, ...),
+so fields such as `reply_markup` are typed models, not raw dicts.
+
+```python
+from aiogram.methods import AnswerCallbackQuery, SendMessage
+
+calls = await request.query(message=MESSAGE.as_object(text="Hello, Bot!"))
+
+calls.send_message.fetchone()            # last SendMessage, by snake_case name
+calls.get(SendMessage)                   # all SendMessage calls, typed
+calls.last(SendMessage)                  # last one or None
+calls.assert_called(SendMessage, text="Hello, Bot!")   # fails with the calls that were made
+calls.assert_not_called(AnswerCallbackQuery)
+```
+
+Accessing a method that was not called (`calls.edit_message_text`) raises `MethodIsNotCalledError`, an
+`AttributeError`, so `hasattr(calls, "edit_message_text")` works.
+
+### Testing a whole router: `BotTester`
+
+`MockedRequester` checks one handler function. `BotTester` runs updates through your real router or dispatcher, with
+its filters, middlewares, FSM and injected dependencies, just like production:
+
+```python
+from aiogram.methods import SendMessage
+
+from mybot.handlers import router
+
+
+async def test_survey(bot_tester):  # fixture from the bundled pytest plugin
+    tester = bot_tester(router, db=fake_db)   # keyword arguments reach handlers like dp.start_polling(**kwargs)
+
+    calls = await tester.send_message("/survey")
+    calls.assert_called(SendMessage, text="What is your name?")
+
+    await tester.send_message("Alice")        # FSM state carries over between steps
+    calls = await tester.press("Python")      # presses a button from the last inline keyboard
+
+    calls.assert_called(SendMessage, text="Nice to meet you, Alice!")
+    assert await tester.get_state() is None
+```
+
+- `send_message(text, user=..., chat=...)`, `click(data_or_callback_data, message=..., user=...)`, `press(button_text)`
+  and `feed(event_or_update, event_type=...)` return the calls made while handling that update.
+- `get_state(user)`, `set_state(state, user=..., **data)` and `state(user)` give access to the FSM.
+- A module-level router is detached from the previous test's dispatcher, so each test gets a fresh one.
+- A `Dispatcher` is used as is; its `workflow_data` and middlewares stay in place.
+
+The plugin is registered automatically on install and provides the `bot_tester` (factory), `mocked_bot` and
+`dataset` fixtures. See [examples/test_survey.py](examples/test_survey.py).
+
+### Other update types
+
+Each update type has its handler; pass the event positionally or by its update field name:
+
+```python
+from aiogram_tests.handler import InlineQueryHandler, PreCheckoutQueryHandler, UpdateHandler
+from aiogram_tests.types.dataset import INLINE_QUERY, PRE_CHECKOUT_QUERY
+
+calls = await MockedRequester(InlineQueryHandler(search)).query(INLINE_QUERY.as_object(query="cats"))
+calls = await MockedRequester(PreCheckoutQueryHandler(approve)).query(pre_checkout_query=PRE_CHECKOUT_QUERY.as_object())
+
+# anything else the dispatcher knows, by name
+calls = await MockedRequester(UpdateHandler(on_business, event="business_message")).query(message)
+```
+
+Available: `MessageHandler`, `EditedMessageHandler`, `ChannelPostHandler`, `EditedChannelPostHandler`,
+`CallbackQueryHandler`, `InlineQueryHandler`, `ChosenInlineResultHandler`, `ShippingQueryHandler`,
+`PreCheckoutQueryHandler`, `PollHandler`, `PollAnswerHandler`, `MyChatMemberHandler`, `ChatMemberHandler`,
+`ChatJoinRequestHandler`, `MessageReactionHandler` and `UpdateHandler`.
+
+Middlewares passed as `dp_middlewares` are registered on every event observer except `update` and `error`, whose
+events are `Update` and `ErrorEvent` rather than messages or callbacks.
+
+### [▶️ More](https://github.com/k0te1ch/aiogram_tests/tree/main/examples) examples
+

aiogram_testing-1.2.0/README.md

@@ -0,0 +1,140 @@
+# Aiogram Tests
+
+***aiogram_tests*** is a testing library for bots written on [aiogram](https://github.com/aiogram/aiogram)
+
+## 📦 Installation
+
+```bash
+pip install aiogram-testing
+```
+
+The import name stays `aiogram_tests`:
+
+```python
+from aiogram_tests import MockedRequester
+```
+
+## 📚 Simple examples
+
+### Simple handler test
+
+#### Simple bot
+
+```python
+from aiogram import Bot, Dispatcher, types
+from aiogram.fsm.context import FSMContext
+
+# Please, keep your bot tokens on environments, this code only example
+bot = Bot('123456789:AABBCCDDEEFFaabbccddeeff-1234567890')
+dp = Dispatcher()
+
+
+@dp.message()
+async def echo(message: types.Message, state: FSMContext) -> None:
+    await message.answer(message.text)
+
+
+if __name__ == '__main__':
+    dp.run_polling(bot)
+
+
+```
+
+#### Test cases
+
+```python
+import pytest
+
+from bot import echo
+
+from aiogram_tests import MockedRequester
+from aiogram_tests.handler import MessageHandler
+from aiogram_tests.types.dataset import MESSAGE
+
+
+@pytest.mark.asyncio
+async def test_echo():
+    request = MockedRequester(MessageHandler(echo))
+    calls = await request.query(message=MESSAGE.as_object(text="Hello, Bot!"))
+    answer_message = calls.send_message.fetchone()
+    assert answer_message.text == "Hello, Bot!"
+
+```
+
+### Checking calls
+
+`query()` returns the Bot API methods the handler called, as aiogram objects (`SendMessage`, `EditMessageText`, ...),
+so fields such as `reply_markup` are typed models, not raw dicts.
+
+```python
+from aiogram.methods import AnswerCallbackQuery, SendMessage
+
+calls = await request.query(message=MESSAGE.as_object(text="Hello, Bot!"))
+
+calls.send_message.fetchone()            # last SendMessage, by snake_case name
+calls.get(SendMessage)                   # all SendMessage calls, typed
+calls.last(SendMessage)                  # last one or None
+calls.assert_called(SendMessage, text="Hello, Bot!")   # fails with the calls that were made
+calls.assert_not_called(AnswerCallbackQuery)
+```
+
+Accessing a method that was not called (`calls.edit_message_text`) raises `MethodIsNotCalledError`, an
+`AttributeError`, so `hasattr(calls, "edit_message_text")` works.
+
+### Testing a whole router: `BotTester`
+
+`MockedRequester` checks one handler function. `BotTester` runs updates through your real router or dispatcher, with
+its filters, middlewares, FSM and injected dependencies, just like production:
+
+```python
+from aiogram.methods import SendMessage
+
+from mybot.handlers import router
+
+
+async def test_survey(bot_tester):  # fixture from the bundled pytest plugin
+    tester = bot_tester(router, db=fake_db)   # keyword arguments reach handlers like dp.start_polling(**kwargs)
+
+    calls = await tester.send_message("/survey")
+    calls.assert_called(SendMessage, text="What is your name?")
+
+    await tester.send_message("Alice")        # FSM state carries over between steps
+    calls = await tester.press("Python")      # presses a button from the last inline keyboard
+
+    calls.assert_called(SendMessage, text="Nice to meet you, Alice!")
+    assert await tester.get_state() is None
+```
+
+- `send_message(text, user=..., chat=...)`, `click(data_or_callback_data, message=..., user=...)`, `press(button_text)`
+  and `feed(event_or_update, event_type=...)` return the calls made while handling that update.
+- `get_state(user)`, `set_state(state, user=..., **data)` and `state(user)` give access to the FSM.
+- A module-level router is detached from the previous test's dispatcher, so each test gets a fresh one.
+- A `Dispatcher` is used as is; its `workflow_data` and middlewares stay in place.
+
+The plugin is registered automatically on install and provides the `bot_tester` (factory), `mocked_bot` and
+`dataset` fixtures. See [examples/test_survey.py](examples/test_survey.py).
+
+### Other update types
+
+Each update type has its handler; pass the event positionally or by its update field name:
+
+```python
+from aiogram_tests.handler import InlineQueryHandler, PreCheckoutQueryHandler, UpdateHandler
+from aiogram_tests.types.dataset import INLINE_QUERY, PRE_CHECKOUT_QUERY
+
+calls = await MockedRequester(InlineQueryHandler(search)).query(INLINE_QUERY.as_object(query="cats"))
+calls = await MockedRequester(PreCheckoutQueryHandler(approve)).query(pre_checkout_query=PRE_CHECKOUT_QUERY.as_object())
+
+# anything else the dispatcher knows, by name
+calls = await MockedRequester(UpdateHandler(on_business, event="business_message")).query(message)
+```
+
+Available: `MessageHandler`, `EditedMessageHandler`, `ChannelPostHandler`, `EditedChannelPostHandler`,
+`CallbackQueryHandler`, `InlineQueryHandler`, `ChosenInlineResultHandler`, `ShippingQueryHandler`,
+`PreCheckoutQueryHandler`, `PollHandler`, `PollAnswerHandler`, `MyChatMemberHandler`, `ChatMemberHandler`,
+`ChatJoinRequestHandler`, `MessageReactionHandler` and `UpdateHandler`.
+
+Middlewares passed as `dp_middlewares` are registered on every event observer except `update` and `error`, whose
+events are `Update` and `ErrorEvent` rather than messages or callbacks.
+
+### [▶️ More](https://github.com/k0te1ch/aiogram_tests/tree/main/examples) examples

aiogram_testing-1.2.0/aiogram_tests/__init__.py

@@ -0,0 +1,6 @@
+from .requester import Calls
+from .requester import MockedRequester
+from .tester import BotTester
+
+__all__ = ["BotTester", "Calls", "MockedRequester"]
+__version__ = "1.2.0"  # x-release-please-version

aiogram_testing-1.2.0/aiogram_tests/exceptions.py

@@ -0,0 +1,6 @@
+class MethodIsNotCalledError(AttributeError):
+    pass
+
+
+class MockedResponseMissingError(Exception):
+    pass

aiogram_testing-1.2.0/aiogram_tests/handler/__init__.py

@@ -0,0 +1,39 @@
+from .base import RequestHandler
+from .handler import CallbackQueryHandler
+from .handler import ChannelPostHandler
+from .handler import ChatJoinRequestHandler
+from .handler import ChatMemberHandler
+from .handler import ChosenInlineResultHandler
+from .handler import EditedChannelPostHandler
+from .handler import EditedMessageHandler
+from .handler import InlineQueryHandler
+from .handler import MessageHandler
+from .handler import MessageReactionHandler
+from .handler import MyChatMemberHandler
+from .handler import PollAnswerHandler
+from .handler import PollHandler
+from .handler import PreCheckoutQueryHandler
+from .handler import ShippingQueryHandler
+from .handler import TelegramEventObserverHandler
+from .handler import UpdateHandler
+
+__all__ = [
+    "CallbackQueryHandler",
+    "ChannelPostHandler",
+    "ChatJoinRequestHandler",
+    "ChatMemberHandler",
+    "ChosenInlineResultHandler",
+    "EditedChannelPostHandler",
+    "EditedMessageHandler",
+    "InlineQueryHandler",
+    "MessageHandler",
+    "MessageReactionHandler",
+    "MyChatMemberHandler",
+    "PollAnswerHandler",
+    "PollHandler",
+    "PreCheckoutQueryHandler",
+    "RequestHandler",
+    "ShippingQueryHandler",
+    "TelegramEventObserverHandler",
+    "UpdateHandler",
+]

{aiogram_testing-1.1.0 → aiogram_testing-1.2.0}/aiogram_tests/handler/base.py

@@ -2,7 +2,6 @@ from collections.abc import Iterable
 
 from aiogram import BaseMiddleware
 from aiogram import Dispatcher
-from aiogram.dispatcher.event.telegram import TelegramEventObserver
 from aiogram.fsm.storage.memory import MemoryStorage
 from aiogram.methods import TelegramMethod
 from aiogram.methods.base import Response
@@ -39,14 +38,12 @@ class RequestHandler:
     def _get_dispatcher_event_observers(self) -> list[str]:
         """
         Returns a names for bot event observers, like message, callback_query etc.
-        """
 
-        result = []
-        for name in dir(self.dp):
-            if isinstance(getattr(self.dp, name), TelegramEventObserver):
-                result.append(name)
+        ``update`` and ``error`` are left out: their events are ``Update`` and ``ErrorEvent``, and a middleware
+        written for messages or callbacks breaks on them. Register such middlewares on ``dp`` directly.
+        """
 
-        return result
+        return [name for name in self.dp.observers if name not in ("update", "error")]
 
     def _register_middlewares(self, event_observer: Iterable, middlewares: Iterable) -> None:
         for eo_name in event_observer:

aiogram_testing-1.2.0/aiogram_tests/handler/handler.py

@@ -0,0 +1,178 @@
+import itertools
+from collections.abc import Callable
+from collections.abc import Iterable
+from typing import Any
+
+from aiogram import types
+from aiogram.dispatcher.middlewares.user_context import UserContextMiddleware
+from aiogram.filters import Filter
+from aiogram.filters import StateFilter
+from aiogram.fsm.context import FSMContext
+from aiogram.fsm.state import State
+
+from aiogram_tests.types.dataset import CHAT
+from aiogram_tests.types.dataset import USER
+
+from .base import RequestHandler
+
+
+class TelegramEventObserverHandler(RequestHandler):
+    """
+    Registers ``callback`` on the dispatcher observer ``event`` (``message``, ``inline_query``, ...) and feeds it
+    updates of that type. Subclasses fix ``event``; ``UpdateHandler`` takes it as an argument.
+    """
+
+    event: str | None = None
+
+    def __init__(
+        self,
+        callback: Callable,
+        *filters: Filter,
+        state: State | str | None = None,
+        state_data: dict = None,
+        state_context: FSMContext | None = None,
+        dp_middlewares: Iterable = None,
+        exclude_observer_methods: Iterable = None,
+        **kwargs,
+    ):
+        super().__init__(dp_middlewares, exclude_observer_methods, **kwargs)
+
+        if state_data is None:
+            state_data = {}
+        if not isinstance(state_data, dict):
+            raise ValueError("state_data is not a dict")
+
+        self._callback = callback
+        self._filters: list = list(filters)
+        self._state: State | str | None = state
+        self._state_data: dict = state_data
+        self._state_context: FSMContext | None = state_context
+        self._registered = False
+        self._update_ids = itertools.count(1)
+
+        if self._state:
+            self._filters.append(StateFilter(self._state))
+
+    async def __call__(self, *args, **kwargs):
+        if not self._registered:
+            self.register_handler()
+            self._registered = True
+
+        update = self.build_update(*args, **kwargs)
+
+        if self._state_context or self._state:
+            state = self._get_state_context(update)
+            await state.set_state(self._state)
+            await state.update_data(**self._state_data)
+
+        await self.dp.feed_update(self.bot, update)
+
+    def _get_state_context(self, update: types.Update) -> FSMContext:
+        """
+        FSM context of the user and chat the update comes from, as the dispatcher resolves it
+        """
+
+        context = UserContextMiddleware.resolve_event_context(update)
+        state = self.dp.fsm.resolve_context(
+            bot=self.bot,
+            chat_id=context.chat_id or CHAT["id"],
+            user_id=context.user_id or USER["id"],
+            thread_id=context.thread_id,
+            business_connection_id=context.business_connection_id,
+        )
+        return state
+
+    def register_handler(self) -> None:
+        """
+        Register TelegramEventObserver in dispatcher
+        """
+
+        getattr(self.dp, self.event).register(self._callback, *self._filters)
+
+    def build_update(self, *args, **kwargs) -> types.Update:
+        """
+        Wrap the event, passed positionally or by its update field name, into an update for the dispatcher
+        """
+
+        event = self._pick_event(args, kwargs)
+        return types.Update(update_id=next(self._update_ids), **{self.event: event})
+
+    def _pick_event(self, args: tuple, kwargs: dict) -> Any:
+        if args and not kwargs:
+            return args[0]
+        if not args and list(kwargs) == [self.event]:
+            return kwargs[self.event]
+        passed = [*(type(arg).__name__ for arg in args), *kwargs]
+        raise TypeError(f"{type(self).__name__} takes one '{self.event}' event, got {passed}")
+
+
+class UpdateHandler(TelegramEventObserverHandler):
+    """
+    Handler for any update type by its field name: ``UpdateHandler(callback, event="business_message")``
+    """
+
+    def __init__(self, callback: Callable, *filters: Filter, event: str, **kwargs):
+        self.event = event
+        super().__init__(callback, *filters, **kwargs)
+        if event not in self.dp.observers or event in ("update", "error"):
+            raise ValueError(f"dispatcher has no '{event}' updates")
+
+
+class MessageHandler(TelegramEventObserverHandler):
+    event = "message"
+
+
+class EditedMessageHandler(TelegramEventObserverHandler):
+    event = "edited_message"
+
+
+class ChannelPostHandler(TelegramEventObserverHandler):
+    event = "channel_post"
+
+
+class EditedChannelPostHandler(TelegramEventObserverHandler):
+    event = "edited_channel_post"
+
+
+class CallbackQueryHandler(TelegramEventObserverHandler):
+    event = "callback_query"
+
+
+class InlineQueryHandler(TelegramEventObserverHandler):
+    event = "inline_query"
+
+
+class ChosenInlineResultHandler(TelegramEventObserverHandler):
+    event = "chosen_inline_result"
+
+
+class ShippingQueryHandler(TelegramEventObserverHandler):
+    event = "shipping_query"
+
+
+class PreCheckoutQueryHandler(TelegramEventObserverHandler):
+    event = "pre_checkout_query"
+
+
+class PollHandler(TelegramEventObserverHandler):
+    event = "poll"
+
+
+class PollAnswerHandler(TelegramEventObserverHandler):
+    event = "poll_answer"
+
+
+class MyChatMemberHandler(TelegramEventObserverHandler):
+    event = "my_chat_member"
+
+
+class ChatMemberHandler(TelegramEventObserverHandler):
+    event = "chat_member"
+
+
+class ChatJoinRequestHandler(TelegramEventObserverHandler):
+    event = "chat_join_request"
+
+
+class MessageReactionHandler(TelegramEventObserverHandler):
+    event = "message_reaction"

{aiogram_testing-1.1.0 → aiogram_testing-1.2.0}/aiogram_tests/mocked_bot.py

@@ -11,6 +11,8 @@ from aiogram.types import ResponseParameters
 from aiogram.types import User
 from aiogram.types.base import UNSET_TYPE
 
+from .exceptions import MockedResponseMissingError
+
 DEFAULT_AUTO_MOCK_SUCCESS = True
 
 
@@ -19,6 +21,7 @@ class MockedSession(BaseSession):
         super().__init__()
         self.responses: deque[Response[TelegramType]] = deque()
         self.requests: deque[Request] = deque()
+        self.methods: deque[TelegramMethod] = deque()
         self.closed = True
 
     def add_result(self, response: Response[TelegramType]) -> Response[TelegramType]:
@@ -43,6 +46,12 @@ class MockedSession(BaseSession):
         self.closed = False
         request = Request(method=method.__api_method__, data=method.__dict__, files=None)
         self.requests.append(request)
+        self.methods.append(method)
+        if not self.responses:
+            raise MockedResponseMissingError(
+                f"no mocked response for {method.__api_method__}: call "
+                f"add_result_for({type(method).__name__}, ...) first or enable auto_mock_success"
+            )
         response: Response[TelegramType] = self.responses.pop()
         self.check_response(
             method=method,
@@ -61,7 +70,6 @@ class MockedSession(BaseSession):
 class MockedBot(Bot):
     def __init__(self, auto_mock_success: bool = DEFAULT_AUTO_MOCK_SUCCESS, **kwargs):
         super().__init__(kwargs.pop("token", "42:TEST"), session=MockedSession(), **kwargs)
-        self.session = MockedSession()
         self._me = User(
             id=self.id,
             is_bot=True,

aiogram_testing-1.2.0/aiogram_tests/pytest_plugin.py

@@ -0,0 +1,36 @@
+"""pytest fixtures, loaded automatically through the ``pytest11`` entry point"""
+
+from collections.abc import Callable
+from types import ModuleType
+from typing import Any
+
+import pytest
+from aiogram import Dispatcher
+from aiogram import Router
+
+from .mocked_bot import MockedBot
+from .tester import BotTester
+from .types import dataset as _dataset
+
+
+@pytest.fixture
+def mocked_bot() -> MockedBot:
+    return MockedBot()
+
+
+@pytest.fixture
+def bot_tester(mocked_bot: MockedBot) -> Callable[..., BotTester]:
+    """
+    Factory: ``bot_tester(router_or_dispatcher, **workflow_data)``; every tester in a test shares ``mocked_bot``
+    """
+
+    def make(dispatcher: Dispatcher | Router, **kwargs: Any) -> BotTester:
+        kwargs.setdefault("bot", mocked_bot)
+        return BotTester(dispatcher, **kwargs)
+
+    return make
+
+
+@pytest.fixture
+def dataset() -> ModuleType:
+    return _dataset