python-telegram-bot/tests
2024-08-26 20:16:35 +02:00
..
_files Bump ruff and Add New Rules (#4416) 2024-08-07 21:56:46 +02:00
_games Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
_inline Bump ruff and Add New Rules (#4416) 2024-08-07 21:56:46 +02:00
_passport Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
_payment API 7.7 (#4356) 2024-07-09 10:35:18 +02:00
_utils Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
auxil Add Internal Constants for Encodings (#4378) 2024-07-21 21:13:30 +02:00
data Improve Backwards Compatibility of TelegramObjects Pickle Behavior (#3382) 2022-11-24 12:11:37 +01:00
docs Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
ext Remove Surplus Logging from Updater Network Loop (#4432) 2024-08-19 16:40:28 +02:00
request Bump ruff and Add New Rules (#4416) 2024-08-07 21:56:46 +02:00
test_official Add Parameter read_file_handle to InputFile (#4388) 2024-08-02 22:28:38 +02:00
__init__.py Fix travis 2015-09-07 16:33:00 -03:00
conftest.py Bump ruff and Add New Rules (#4416) 2024-08-07 21:56:46 +02:00
README.rst Drop python-telegram-bot-raw And Switch to pyproject.toml Based Packaging (#4288) 2024-06-15 10:29:19 +02:00
test_birthdate.py Make Birthdate.to_date Return a datetime.date Object (#4251) 2024-05-10 22:23:19 +02:00
test_bot.py Update Test Suite to New Test Channel Setup (#4435) 2024-08-26 20:16:35 +02:00
test_botcommand.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_botcommandscope.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_botdescription.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_botname.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_business.py API 7.2 (#4180, #4181) 2024-04-12 11:58:25 +02:00
test_callbackquery.py API 7.8 (#4408) 2024-08-02 13:43:27 +02:00
test_chat.py API 7.6 (#4333, #4341, #4342, #4334, #4335, #4344, #4348, #4351) 2024-07-07 13:08:52 +02:00
test_chatadministratorrights.py Make ChatAdministratorRights.can_*_stories Required (API 7.1) (#4192) 2024-04-06 17:13:43 +02:00
test_chatbackground.py Bump ruff and Add New Rules (#4416) 2024-08-07 21:56:46 +02:00
test_chatboost.py Bump ruff and Add New Rules (#4416) 2024-08-07 21:56:46 +02:00
test_chatfullinfo.py API 7.6 (#4333, #4341, #4342, #4334, #4335, #4344, #4348, #4351) 2024-07-07 13:08:52 +02:00
test_chatinvitelink.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_chatjoinrequest.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_chatlocation.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_chatmember.py Bump ruff and Add New Rules (#4416) 2024-08-07 21:56:46 +02:00
test_chatmemberupdated.py API 7.3 (#4243, #4248, #4247, #4242, #4246, #4260) 2024-05-20 15:25:25 +02:00
test_chatpermissions.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_choseninlineresult.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_constants.py Stabilize Some Concurrency Usages in Test Suite (#4360) 2024-07-10 17:11:22 +02:00
test_dice.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_enum_types.py Add Internal Constants for Encodings (#4378) 2024-07-21 21:13:30 +02:00
test_error.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_forcereply.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_forum.py Bump ruff and Add New Rules (#4416) 2024-08-07 21:56:46 +02:00
test_giveaway.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_helpers.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_inlinequeryresultsbutton.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_keyboardbutton.py Remove Functionality Deprecated in API 7.0 (#4114) 2024-02-25 10:34:47 +01:00
test_keyboardbuttonpolltype.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_keyboardbuttonrequest.py API 7.1 (#4118) 2024-03-02 10:56:15 +01:00
test_linkpreviewoptions.py API 7.0 (#4034, #4038) 2024-02-08 17:12:00 +01:00
test_loginurl.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_maybeinaccessiblemessage.py Remove Functionality Deprecated in API 7.0 (#4114) 2024-02-25 10:34:47 +01:00
test_menubutton.py Add a Test Case for MenuButton (#4363) 2024-07-10 17:10:33 +02:00
test_message.py Improve Fixture Usage in test_message.py (#4431) 2024-08-19 16:14:01 +02:00
test_messageautodeletetimerchanged.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_messageentity.py Add MessageEntity.adjust_message_entities_to_utf_16 Utility Function (#4323) 2024-07-06 16:08:29 +02:00
test_messageid.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_messageorigin.py Bump ruff and Add New Rules (#4416) 2024-08-07 21:56:46 +02:00
test_meta.py Drop python-telegram-bot-raw And Switch to pyproject.toml Based Packaging (#4288) 2024-06-15 10:29:19 +02:00
test_modules.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_paidmedia.py API 7.6 (#4333, #4341, #4342, #4334, #4335, #4344, #4348, #4351) 2024-07-07 13:08:52 +02:00
test_poll.py API 7.3 (#4243, #4248, #4247, #4242, #4246, #4260) 2024-05-20 15:25:25 +02:00
test_pollhandler.py Bump ruff and Add New Rules (#4416) 2024-08-07 21:56:46 +02:00
test_proximityalerttriggered.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_reaction.py Bump ruff and Add New Rules (#4416) 2024-08-07 21:56:46 +02:00
test_reply.py API 7.6 (#4333, #4341, #4342, #4334, #4335, #4344, #4348, #4351) 2024-07-07 13:08:52 +02:00
test_replykeyboardmarkup.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_replykeyboardremove.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_sentwebappmessage.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_shared.py Remove Functionality Deprecated by Bot API 7.2 (#4245) 2024-05-10 17:42:22 +02:00
test_slots.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_stars.py Bump ruff and Add New Rules (#4416) 2024-08-07 21:56:46 +02:00
test_story.py API 7.1 (#4118) 2024-03-02 10:56:15 +01:00
test_switchinlinequerychosenchat.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_telegramobject.py Make Argument bot of TelegramObject.de_json Optional (#4320) 2024-07-01 19:59:54 +02:00
test_update.py API 7.2 (#4180, #4181) 2024-04-12 11:58:25 +02:00
test_user.py Bump ruff and Add New Rules (#4416) 2024-08-07 21:56:46 +02:00
test_userprofilephotos.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_version.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_videochat.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_warnings.py Add Version to PTBDeprecationWarning (#4262) 2024-05-20 16:12:34 +02:00
test_webappdata.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_webappinfo.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_webhookinfo.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00
test_writeaccessallowed.py Update Copyright to 2024 (#4121) 2024-02-19 20:06:25 +01:00

==============
Testing in PTB
==============

PTB uses `pytest`_ for testing. To run the tests, you need to
have pytest installed along with a few other dependencies. You can find the list of dependencies
in the ``pyproject.toml`` file in the root of the repository.

Running tests
=============

To run the entire test suite, you can use the following command:

.. code-block:: bash

    $ pytest

This will run all the tests, including the ones which make a request to the Telegram servers, which
may take a long time (total > 13 mins). To run only the tests that don't require a connection, you
can run the following command:

.. code-block:: bash

    $ pytest -m no_req

Or alternatively, you can run the following command to run only the tests that require a connection:

.. code-block:: bash

    $ pytest -m req

To further speed up the tests, you can run them in parallel using the ``-n`` flag (requires `pytest-xdist`_). But beware that
this will use multiple CPU cores on your machine. The ``--dist`` flag is used to specify how the
tests will be distributed across the cores. The ``loadgroup`` option is used to distribute the tests
such that tests marked with ``@pytest.mark.xdist_group("name")`` are run on the same core — important if you want avoid race conditions in some tests:

.. code-block:: bash

    $ pytest -n auto --dist=loadgroup

This will result in a significant speedup, but may cause some tests to fail. If you want to run
the failed tests in isolation, you can use the ``--lf`` flag:

.. code-block:: bash

    $ pytest --lf


Writing tests
=============

PTB has a separate test file for every file in the ``telegram.*`` namespace. Further, the tests for
the ``telegram`` module are split into two classes, based on whether the test methods in them make a
request or not. When writing tests, make sure to split them into these two classes, and make sure
to name the test class as: ``TestXXXWithoutRequest`` for tests that don't make a request, and ``TestXXXWithRequest`` for tests that do.

Writing tests is a creative process; allowing you to design your test however you'd like, but there
are a few conventions that you should follow:

- Each new test class needs a ``test_slot_behaviour``, ``test_to_dict``, ``test_de_json`` and
  ``test_equality`` (in most cases).

- Make use of pytest's fixtures and parametrize wherever possible. Having knowledge of pytest's
  tooling can help you as well. You can look at the existing tests for examples and inspiration.

- New fixtures should go into ``conftest.py``. New auxiliary functions and classes, used either directly in the tests or in the fixtures, should go into the ``tests/auxil`` directory.

If you have made some API changes, you may want to run ``test_official`` to validate that the changes are
complete and correct. To run it, export an environment variable first:

.. code-block:: bash

    $ export TEST_OFFICIAL=true

and then run ``pytest tests/test_official.py``. Note: You need py 3.10+ to run this test.

We also have another marker, ``@pytest.mark.dev``, which you can add to tests that you want to run selectively.
Use as follows:

.. code-block:: bash

    $ pytest -m dev


Debugging tests
===============

Writing tests can be challenging, and fixing failing tests can be even more so. To help with this,
PTB has started to adopt the use of ``logging`` in the test suite. You can insert debug logging 
statements in your tests to help you understand what's going on. To enable these logs, you can set 
``log_level = DEBUG`` in ``setup.cfg`` or use the ``--log-level=INFO`` flag when running the tests.
If a test is large and complicated, it is recommended to leave the debug logs for others to use as 
well.


Bots used in tests
==================

If you run the tests locally, the test setup will use one of the two public bots available. Which
bot of the two gets chosen for the test session is random. Whereas when the tests on the
Github Actions CI are run, the test setup allocates a different, but same bot is for every combination of Python version and
OS. The operating systems and Python versions the CI runs the tests on can be viewed in the `corresponding workflow`_.


That's it! If you have any questions, feel free to ask them in the `PTB dev
group`_.

.. _pytest: https://docs.pytest.org/en/stable/
.. _pytest-xdist: https://pypi.org/project/pytest-xdist/
.. _PTB dev group: https://t.me/pythontelegrambotgroup
.. _corresponding workflow: https://github.com/python-telegram-bot/python-telegram-bot/blob/master/.github/workflows/unit_tests.yml