Skip to content
Integration Test Library for Telegram Messenger Bots in Python
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Rename project Apr 30, 2018
docs 0.2.1 May 12, 2018
examples Initial async commit May 20, 2018
scripts 0.2.1 May 12, 2018
tests Rename project Apr 30, 2018
tgintegration added forward_messages methods Jun 10, 2018
.editorconfig Rename project Apr 30, 2018
.gitignore 0.2.1 May 12, 2018
.travis.yml Added regions May 6, 2018
AUTHORS.rst Rename project Apr 30, 2018
CONTRIBUTING.rst Rename project Apr 30, 2018
HISTORY.rst Rename project Apr 30, 2018
LICENSE Rename project Apr 30, 2018 Rename project Apr 30, 2018
Makefile bump in makefile May 27, 2018
README.rst Fixed syntax May 27, 2018
requirements.txt .pyi improvements May 18, 2018
requirements_dev.txt Proper code formatting May 9, 2018
setup.cfg Bump version: 0.2.2 → 0.2.3 May 31, 2018 Bump version: 0.2.2 → 0.2.3 May 31, 2018
tox.ini Rename project Apr 30, 2018 Rename project Apr 30, 2018



An Integration Test Framework for Bots on Telegram Messenger on top of Pyrogram.

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


Same as Pyrogram:


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 BotIntegrationClient:

from tgintegration import BotIntegrationClient

client = BotIntegrationClient(
    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.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[0].sticker  # First message is a sticker

The result should look like this:

Sending /start to @BotListBot

Let's examine these buttons in the response...

# Extract first (and only) inline keyboard from the replies
inline_keyboard = response.inline_keyboards[0]

# Three buttons in the first row
assert len(inline_keyboard.rows[0]) == 3

We can also query and press the inline keyboard buttons:

# Click the first button matching the pattern
examples = response.inline_keyboards[0].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 MessageEdited updates and picks up on the edit, returning it as Response.

Get Examples from @BotListBot

So what happens when we send an invalid query or the bot fails to respond?

    # 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

The 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 act_await_response method:

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 filters 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 AwaitableAction.

from tgintegration import AwaitableAction, Response
from pyrogram import Filters

peer = '@BotListBot'

action = AwaitableAction(
        text="**Hello World**",
    # Wait for messages only by the peer we're interacting with
    filters=Filters.user(peer) & Filters.incoming,
    # Time out and raise after 15 seconds

response = client.act_await_response(action)  # type: Response

Integrating with test frameworks


  • py.test
  • unittest


This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

You can’t perform that action at this time.