No more mocking of every single Bot API object, just test your bot in real-world scenarios.
- Free software: MIT license
- Log into a Telegram user account and interact with bots
- Send messages and wait for the response
- Perform inline queries and match the expected result
- Automate everything about Telegram bots
All hail pip!
$ pip install tgintegration --upgrade
- Python 3.4 or higher.
- A Telegram API key.
Suppose we want to write integration tests for @BotListBot
by sending it a couple of messages and asserting that it responds the way it should.
First, let's create a
from tgintegration import BotIntegrationClient client = BotIntegrationClient( bot_under_test='@BotListBot', session_name='my_account', # Arbitrary file path to the Pyrogram session file api_id=API_ID, # See "Requirements" above, ... api_hash=API_HASH, # alternatively use a `config.ini` file max_wait_response=15, # Maximum timeout for bot responses min_wait_consecutive=2 # Minimum time to wait for consecutive messages ) client.start() client.clear_chat() # Let's start with a blank screen
Now let's send the
/start command to the
bot_under_test and "await" exactly three messages:
response = client.send_command_await("start", num_expected=3) assert response.num_messages == 3 assert response.messages.sticker # First message is a sticker
The result should look like this:
Let's examine these buttons in the response...
# Extract first (and only) inline keyboard from the replies inline_keyboard = response.inline_keyboards # Three buttons in the first row assert len(inline_keyboard.rows) == 3
We can also query and press the inline keyboard buttons:
# Click the first button matching the pattern examples = response.inline_keyboards.press_button_await(pattern=r'.*Examples') assert "Examples for contributing to the BotList" in examples.full_text
As the bot edits the message,
press_button_await automatically listens for
updates and picks up on the edit, returning it as
So what happens when we send an invalid query or the bot fails to respond?
try: # The following instruction will raise an `InvalidResponseError` after # `client.max_wait_response` seconds. This is because we passed `raise_no_response = True` # in the client initialization. client.send_command_await("ayylmao", raise_=True) except InvalidResponseError: print("Raised.") # Ok
BotIntegrationClient is based off a regular Pyrogram
Client, meaning that,
in addition to the
send_*_await methods, all normal Pyro methods still work:
client.send_message(client.bot_under_test, "Hello from Pyrogram") # `send_*_await` methods automatically use the `bot_under_test` as peer: res = client.send_message_await("Hello from TgIntegration", max_wait=2, raise_=False) # If `raise_` is explicitly set to False, no exception is raised: assert res.empty # Note that when no response is expected and no validation thereof is necessary, ... client.send_photo_await("media/photo.jpg", max_wait=0, raise_=False) client.send_voice_await("media/voice.ogg", max_wait=0, raise_=False) # ... it makes more sense to use the "unawaitable" methods: client.send_photo(client.bot_under_test, "media/photo.jpg") client.send_voice(client.bot_under_test, "media/voice.ogg")
Custom awaitable actions
The main logic for the timeout between sending a message and receiving a response from the user
is handled in the
def act_await_response(self, action: AwaitableAction) -> Response: ...
It expects an
AwaitableAction which is a plan for a message to be sent, while the
BotIntegrationClient just makes it easy and removes a lot of the boilerplate code to
create these actions.
After executing the action, the client collects all incoming messages that match the
and adds them to the response. Thus you can think of a
Response object as a collection of
messages returned by the peer in reaction to the executed
from tgintegration import AwaitableAction, Response from pyrogram import Filters peer = '@BotListBot' action = AwaitableAction( func=client.send_message, kwargs=dict( chat_id=peer, text="**Hello World**", parse_mode="markdown" ), # Wait for messages only by the peer we're interacting with filters=Filters.user(peer) & Filters.incoming, # Time out and raise after 15 seconds max_wait=15 ) response = client.act_await_response(action) # type: Response
Integrating with test frameworks