tgmock
Fake Telegram API server for testing bots — pytest plugin + Claude Code MCP server.
Works with any bot framework (aiogram, python-telegram-bot, Telegraf, go-telegram-bot-api, etc.).
TL;DR — add the marketplace, install the plugin, add 4 lines to your bot, and ask Claude to test it:
/plugin marketplace add azdaev/tgmock
/plugin install tgmock@tgmock
Claude will guide you through the rest with /tgmock:setup and /tgmock:test.
Installation
Claude Code plugin (recommended)
Installs the MCP server + skills automatically:
/plugin marketplace add azdaev/tgmock
/plugin install tgmock@tgmock
MCP server only
Register manually without the plugin system:
claude mcp add tgmock --transport stdio -- python3 -m tgmock.mcp_server
Requires pip install "tgmock[mcp]" in the environment where Claude Code runs.
pytest plugin only
pip install tgmock
The pytest plugin registers automatically via pytest11 entry point.
How it works
tgmock starts a local HTTP server that mimics the Telegram Bot API. Your bot talks to it instead of the real Telegram. You send messages and click buttons via test utilities; the bot responds to the fake server. No real Telegram account needed.
For Python bots, tgmock automatically patches HTTP clients (aiohttp, httpx) so your bot needs zero code changes. Just configure and go.
Install
pip install tgmock # pytest plugin only
pip install "tgmock[mcp]" # + MCP server for Claude Code
Configure your project
Add to your .env:
TGMOCK_BOT_COMMAND=python main.py
TGMOCK_READY_LOG=Bot starting
For compiled languages (pre-build before starting):
TGMOCK_BUILD_COMMAND=go build -o /tmp/mybot ./cmd/server
TGMOCK_BOT_COMMAND=/tmp/mybot
Or configure in pyproject.toml:
[tool.tgmock]
bot_command = "python main.py"
ready_log = "Bot starting"
port = 8999
startup_timeout = 15
Config priority: TGMOCK_* env vars > TGMOCK_* in .env file > [tool.tgmock] in pyproject.toml > defaults.
Auto-patch (Python bots — no code changes needed)
For Python bots using aiohttp (aiogram) or httpx (python-telegram-bot v20+), tgmock automatically monkey-patches HTTP clients to redirect api.telegram.org calls to the mock server. This is enabled by default — no code changes needed.
To disable:
TGMOCK_AUTO_PATCH=false
Manual setup (non-Python bots or auto_patch=false)
For non-Python bots or if you prefer explicit control, add BOT_API_BASE support to your bot. tgmock injects BOT_API_BASE automatically — the bot must use it.
aiogram 3.x:
import os
from aiogram.client.session.aiohttp import AiohttpSession
from aiogram.client.telegram import TelegramAPIServer
api_base = os.environ.get("BOT_API_BASE")
if api_base:
session = AiohttpSession(api=TelegramAPIServer.from_base(api_base))
bot = Bot(token=config.bot_token, session=session)
else:
bot = Bot(token=config.bot_token)
python-telegram-bot:
base_url = os.environ.get("BOT_API_BASE", "https://api.telegram.org/bot")
app = Application.builder().token(TOKEN).base_url(base_url).build()
Telegraf (Node.js):
const bot = new Telegraf(token, {
telegram: { apiRoot: process.env.BOT_API_BASE || 'https://api.telegram.org' }
})
go-telegram-bot-api:
bot, _ := tgbotapi.NewBotAPIWithAPIEndpoint(token, os.Getenv("BOT_API_BASE")+"/bot%s/%s")
pytest plugin
The pytest plugin is registered automatically after pip install tgmock.
import pytest
@pytest.fixture(scope="session")
async def bot(tgmock_server, tgmock_bot):
yield tgmock_bot
async def test_start(bot):
await bot.send("/start")
snap = await bot.snapshot()
assert "Welcome" in snap
See tests/ for examples.
MCP server (Claude Code)
Register tgmock as a Claude Code MCP server:
claude mcp add tgmock --transport stdio -- python3 -m tgmock.mcp_server
Or install as a plugin:
claude plugin install /path/to/tgmock
Available tools
Quick session
tg_start → tg_send("/start") → tg_snapshot → tg_tap("Button") → tg_stop
Debugging
When the bot fails to start, the error includes the last 30 lines of bot output.
Use tg_logs() anytime to see what the bot is printing.
Custom events
Your bot can post structured events to tgmock for assertion without parsing text:
import aiohttp, os
async def post_event(type: str, data: dict):
base = os.environ.get("BOT_API_BASE", "")
if base:
async with aiohttp.ClientSession() as s:
await s.post(f"{base}/test/event", json={"type": type, **data})
Then assert with tg_events(type="tool_call").
License
MIT