{"id":13486548,"url":"https://github.com/JosXa/tgintegration","last_synced_at":"2025-03-27T21:30:32.568Z","repository":{"id":32118085,"uuid":"131617892","full_name":"JosXa/tgintegration","owner":"JosXa","description":"Integration test and automation library for Telegram Messenger bots based on Pyrogram.","archived":false,"fork":false,"pushed_at":"2025-02-03T23:20:22.000Z","size":8792,"stargazers_count":120,"open_issues_count":18,"forks_count":18,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-20T09:58:53.533Z","etag":null,"topics":["bots","hacktoberfest","integration","pyrogram","python","telegram","tests"],"latest_commit_sha":null,"homepage":"https://josxa.github.io/tgintegration/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JosXa.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-30T16:11:49.000Z","updated_at":"2025-03-14T14:56:56.000Z","dependencies_parsed_at":"2023-10-03T16:08:30.135Z","dependency_job_id":"d0643d88-ca99-4061-a5da-50377f6fd150","html_url":"https://github.com/JosXa/tgintegration","commit_stats":{"total_commits":252,"total_committers":8,"mean_commits":31.5,"dds":"0.36904761904761907","last_synced_commit":"39dfc82eb5c80bb6845c12edf0c112e2fa7de26f"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JosXa%2Ftgintegration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JosXa%2Ftgintegration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JosXa%2Ftgintegration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JosXa%2Ftgintegration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JosXa","download_url":"https://codeload.github.com/JosXa/tgintegration/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245927096,"owners_count":20695169,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bots","hacktoberfest","integration","pyrogram","python","telegram","tests"],"created_at":"2024-07-31T18:00:48.192Z","updated_at":"2025-03-27T21:30:31.770Z","avatar_url":"https://github.com/JosXa.png","language":"Python","funding_links":[],"categories":["Python","Libraries"],"sub_categories":[],"readme":"TgIntegration\n=============\n\n\u003cins\u003eAn integration test and automation library for [Telegram Bots](https://core.telegram.org/bots) based on [Pyrogram](https://github.com/pyrogram/pyrogram).\u003c/ins\u003e\n\u003cbr /\u003e**Test your bot in realtime scenarios!**\n\n**Are you a user of TgIntegration?** I'm actively looking for feedback and ways to improve the library, come and let me know in the [official group](https://t.me/TgIntegration)!\n\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/tgintegration)](https://pypi.org/project/tgintegration/)\n[![PyPI - Downloads](https://img.shields.io/pypi/dm/tgintegration)](https://pypi.org/project/tgintegration/)\n[![PyPI](https://img.shields.io/pypi/v/tgintegration)](https://pypi.org/project/tgintegration/)\n![GitHub top language](https://img.shields.io/github/languages/top/josxa/tgintegration)\n[![GitHub Workflow Status (branch)](https://img.shields.io/github/workflow/status/josxa/tgintegration/Build/master)](https://github.com/JosXa/tgintegration/actions?query=workflow%3ABuild)\n[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/josxa/tgintegration/Docs?label=docs)](https://josxa.github.io/tgintegration)\n\n[Features](#features) • [Requirements](#prerequisites) • [Installation](#installation) • [**Quick Start Guide**](#quick-start-guide) • [Test Frameworks](#integrating-with-test-frameworks)\n\n- 📖 [Documentation](https://josxa.github.io/tgintegration/)\n- 👥 [Telegram Chat](https://t.me/TgIntegration)\n- 📄 Free software: [MIT License](https://tldrlegal.com/license/mit-license)\n- [\u003cimg src=\"https://raw.githubusercontent.com/JosXa/tgintegration/master/docs/assets/pycharm-logos/icon-pycharm.svg\" width=\"20\" height=\"20\" /\u003e]((https://www.jetbrains.com/?from=tgintegration)) Built with [PyCharm](https://www.jetbrains.com/?from=tgintegration)\n\nFeatures\n--------\n\n▶️ [**See it in action!** 🎬](https://josxa.github.io/tgintegration/#see-it-in-action)\n\n- 👤 Log into a Telegram user account and interact with bots or other users\n- ✅ Write **realtime integration tests** to ensure that your bot works as expected! ▶️ [Pytest examples](https://github.com/JosXa/tgintegration/tree/master/examples/pytest)\n- ⚡️ **Automate any interaction** on Telegram! ▶️ [Automatically play @IdleTownBot](https://github.com/JosXa/tgintegration/blob/master/examples/automation/idletown.py) | [More examples](https://github.com/JosXa/tgintegration/tree/master/examples/automation)\n- 🛡 Fully typed for safety and **autocompletion** with your favorite IDE\n- 🐍 Built for modern Python (3.8+) with high test coverage\n\n\nPrerequisites\n-------------\n\n[Same as Pyrogram](https://github.com/pyrogram/pyrogram#requirements):\n\n- A [Telegram API key](https://docs.pyrogram.ml/start/ProjectSetup#api-keys).\n- A user session (seeing things happen in your own account is great for getting started)\n- But: **Python 3.8** or higher!\n\nA basic understanding of async/await and [asynchronous context managers](https://docs.python.org/3/library/contextlib.html#contextlib.asynccontextmanager) is assumed, as TgIntegration heavily relies on the latter to automate conversations.\n\n\nInstallation\n------------\n\nAll hail pip!\n\n$ `pip install tgintegration --upgrade`\n\n\u003cbr /\u003e\n\u003cdetails\u003e\u003csummary\u003e\u003ci\u003eFeeling adventurous?\u003c/i\u003e\u003c/summary\u003e\u003cp\u003e\n\nFor bleeding edge, install the master branch:\n\n$ `pip install git+https://github.com/JosXa/tgintegration.git`\n\n\u003c/p\u003e\u003c/details\u003e\n\n\nQuick Start Guide\n-----------------\n\n_You can [follow along by running the example](https://github.com/JosXa/tgintegration/blob/master/examples/readme_example/readmeexample.py) ([README](https://github.com/JosXa/tgintegration/blob/master/examples/README.md))_\n\n#### Setup\n\nSuppose we want to write integration tests for [@BotListBot](https://t.me/BotListBot) by sending it a couple of\nmessages and checking that it responds the way it should.\n\nAfter [configuring a Pyrogram **user client**](https://docs.pyrogram.org/start/setup),\nlet's start by creating a `BotController`:\n\n``` python\nfrom tgintegration import BotController\n\ncontroller = BotController(\n    peer=\"@BotListBot\",      # The bot under test is https://t.me/BotListBot 🤖\n    client=client,           # This assumes you already have a Pyrogram user client available\n    max_wait=8,              # Maximum timeout for responses (optional)\n    wait_consecutive=2,      # Minimum time to wait for more/consecutive messages (optional)\n    raise_no_response=True,  # Raise `InvalidResponseError` when no response is received (defaults to True)\n    global_action_delay=2.5  # Choosing a rather high delay so we can observe what's happening (optional)\n)\n\nawait controller.clear_chat()  # Start with a blank screen (⚠️)\n```\n\nNow, let's send `/start` to the bot and wait until exactly three messages have been received by using the asynchronous `collect` context manager:\n\n``` python\nasync with controller.collect(count=3) as response:\n    await controller.send_command(\"start\")\n\nassert response.num_messages == 3  # Three messages received, bundled under a `Response` object\nassert response.messages[0].sticker  # The first message is a sticker\n```\n\nThe result should look like this:\n\n![image](https://raw.githubusercontent.com/JosXa/tgintegration/master/docs/assets/start_botlistbot.png)\n\nExamining the buttons in the response...\n\n``` python\n# Get first (and only) inline keyboard from the replies\ninline_keyboard = response.inline_keyboards[0]\n\n# Three buttons in the first row\nassert len(inline_keyboard.rows[0]) == 3\n```\n\nWe can also press the inline keyboard buttons, for example based on a regular expression:\n\n``` python\nexamples = await inline_keyboard.click(pattern=r\".*Examples\")\n```\n\nAs the bot edits the message, `.click()` automatically listens for \"message edited\" updates and returns\nthe new state as another `Response`.\n\n![image](https://raw.githubusercontent.com/JosXa/tgintegration/master/docs/assets/examples_botlistbot.png)\n\n``` python\nassert \"Examples for contributing to the BotList\" in examples.full_text\n```\n\n#### Error handling\n\nSo what happens when we send an invalid query or the peer fails to respond?\n\nThe following instruction will raise an `InvalidResponseError` after `controller.max_wait` seconds.\nThis is because we passed `raise_no_response=True` during controller initialization.\n\n``` python\ntry:\n    async with controller.collect():\n        await controller.send_command(\"ayylmao\")\nexcept InvalidResponseError:\n    pass  # OK\n```\n\nLet's explicitly set `raise_` to `False` so that no exception occurs:\n\n``` python\nasync with controller.collect(raise_=False) as response:\n    await client.send_message(controller.peer_id, \"Henlo Fren\")\n```\n\nIn this case, _tgintegration_ will simply emit a warning, but you can still assert\nthat no response has been received by using the `is_empty` property:\n\n``` python\nassert response.is_empty\n```\n\n\nIntegrating with Test Frameworks\n--------------------------------\n\n### [pytest](https://docs.pytest.org/en/stable/index.html)\n\nPytest is the recommended test framework for use with _tgintegration_. You can\n[browse through several examples](https://github.com/JosXa/tgintegration/tree/master/examples/pytest)\nand _tgintegration_ also uses pytest for its own test suite.\n\n### unittest\n\nI haven't tried out the builtin `unittest` library in combination with _tgintegration_ yet,\nbut theoretically I don't see any problems with it.\nIf you do decide to try it, it would be awesome if you could tell me about your\nexperience and whether anything could be improved 🙂\nLet us know at 👉 https://t.me/TgIntegration or in an issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJosXa%2Ftgintegration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJosXa%2Ftgintegration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJosXa%2Ftgintegration/lists"}