test(ci): implement comprehensive mock testing suite and pytest pipeline

Author: randall-vx

.github/workflows/pytest.yml

@@ -0,0 +1,41 @@
+name: Python Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Run Pytest
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13']
+
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+
+      - name: Install Pytest & Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest pytest-asyncio
+          # Install current package to test domain correctly
+          pip install -e .
+
+      - name: Run Tests
+        env:
+          PYTHONPATH: src
+          TELEGRAM_API_ID: "123456"
+          TELEGRAM_API_HASH: "dummy_hash"
+        run: |
+          pytest tests/

tests/__init__.py

@@ -0,0 +1,34 @@
+import pytest
+from unittest.mock import AsyncMock, patch
+
+
+@pytest.fixture(autouse=True)
+def mock_telegram_client():
+    """
+    Automatically injects an AsyncMock in place of the TelegramClient
+    across all tests. This completely isolates the test suite from
+    the real Telegram API and local session securely.
+    """
+    with patch("telegram_mcp.client.client", new_callable=AsyncMock) as mock_client:
+        # Provide common dummy returns for basic client interactions.
+        mock_client.is_connected = lambda: True
+
+        # When domain modules do `await client.get_entity("123")`
+        async def dummy_get_entity(entity):
+            class DummyEntity:
+                id = 12345
+                title = "DummyEntity"
+                username = "dummy_user"
+                first_name = "Dummy"
+                last_name = "User"
+                phone = "123456789"
+                bot = False
+
+            # If the code tries to access `.id`, it'll work
+            return DummyEntity()
+
+        mock_client.get_entity = AsyncMock(side_effect=dummy_get_entity)
+
+        # We need mock_client to also support standard await responses
+        # Most methods like `send_message` or `__call__` will default to returning another AsyncMock
+        yield mock_client

tests/conftest.py

@@ -0,0 +1,134 @@
+import pytest
+from telegram_mcp import chats
+
+
+@pytest.mark.asyncio
+async def test_get_chats():
+    res = await chats.get_chats()
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_subscribe_public_channel():
+    res = await chats.subscribe_public_channel("test")
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_list_topics():
+    res = await chats.list_topics(123)
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_list_chats():
+    res = await chats.list_chats()
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_get_chat():
+    res = await chats.get_chat(123)
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_get_direct_chat_by_contact():
+    res = await chats.get_direct_chat_by_contact("test")
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_get_contact_chats():
+    res = await chats.get_contact_chats(123)
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_get_last_interaction():
+    res = await chats.get_last_interaction(123)
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_get_message_context():
+    res = await chats.get_message_context(123, 1)
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_create_group():
+    res = await chats.create_group("title", [123])
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_invite_to_group():
+    res = await chats.invite_to_group(123, [456])
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_leave_chat():
+    res = await chats.leave_chat(123)
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_get_participants():
+    res = await chats.get_participants(123)
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_create_channel():
+    res = await chats.create_channel("title")
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_edit_chat_title():
+    res = await chats.edit_chat_title(123, "new")
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_delete_chat_photo():
+    res = await chats.delete_chat_photo(123)
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_get_admins():
+    res = await chats.get_admins(123)
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_get_banned_users():
+    res = await chats.get_banned_users(123)
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_get_invite_link():
+    res = await chats.get_invite_link(123)
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_join_chat_by_link():
+    res = await chats.join_chat_by_link("http://t.me/test")
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_export_chat_invite():
+    res = await chats.export_chat_invite(123)
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_import_chat_invite():
+    res = await chats.import_chat_invite("hash")
+    assert res is not None

tests/test_chats.py

@@ -0,0 +1,92 @@
+import pytest
+from telegram_mcp import contacts
+
+
+@pytest.mark.asyncio
+async def test_list_contacts():
+    res = await contacts.list_contacts()
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_search_contacts():
+    res = await contacts.search_contacts("test")
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_get_contact_ids():
+    res = await contacts.get_contact_ids()
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_add_contact():
+    res = await contacts.add_contact(phone="+1234567890", first_name="test")
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_delete_contact():
+    res = await contacts.delete_contact(123)
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_block_user():
+    res = await contacts.block_user(123)
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_unblock_user():
+    res = await contacts.unblock_user(123)
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_get_me():
+    res = await contacts.get_me()
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_update_profile():
+    res = await contacts.update_profile(first_name="new")
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_delete_profile_photo():
+    res = await contacts.delete_profile_photo()
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_get_privacy_settings():
+    res = await contacts.get_privacy_settings()
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_set_privacy_settings():
+    res = await contacts.set_privacy_settings("status", allow_users=[123])
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_import_contacts():
+    res = await contacts.import_contacts([{"phone": "+123", "first_name": "test"}])
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_export_contacts():
+    res = await contacts.export_contacts()
+    assert res is not None
+
+
+@pytest.mark.asyncio
+async def test_get_blocked_users():
+    res = await contacts.get_blocked_users()
+    assert res is not None