AI导哈

Telegram模拟测试工具

一个用于测试Telegram机器人的模拟API服务器，支持多种框架和语言，无需真实Telegram账户即可进行测试。

  • by azdaev
  • Python
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 azdaev/tgmock

使用说明

tgmock

用于测试机器人的伪造Telegram API服务器-pytest插件+Claude Code MCP服务器。

适用于任何机器人框架（aiogram、python电报机器人、Telegraf、go电报机器人api等）。

太长，读不下去了 --添加市场，安装插件，向您的机器人添加4行，并让Claude进行测试：

/plugin marketplace add azdaev/tgmock
/plugin install tgmock@tgmock

克劳德将指导你完成剩下的工作 /tgmock:setup 和 /tgmock:test.

安装

Claude Code插件（推荐）

自动安装MCP服务器+技能：

/plugin marketplace add azdaev/tgmock
/plugin install tgmock@tgmock

仅限MCP服务器

不使用插件系统手动注册：

claude mcp add tgmock --transport stdio -- python3 -m tgmock.mcp_server

需要 pip install "tgmock[mcp]" 在Claude Code运行的环境中。

仅限pytest插件

pip install tgmock

pytest插件通过以下方式自动注册 pytest11 入口点。

运作原理

tgmock启动一个模仿Telegram Bot API的本地HTTP服务器。你的机器人与它对话，而不是与真正的Telegram对话。您通过测试工具发送消息并单击按钮；机器人对假服务器做出响应。不需要真正的Telegram帐户。

对于Python机器人，tgmock会自动修补HTTP客户端（aiohttp、httpx），因此您的机器人不需要更改任何代码。只需配置即可。

安装

pip install tgmock          # pytest plugin only
pip install "tgmock[mcp]"   # + MCP server for Claude Code

配置您的项目

添加到您的 .env:

TGMOCK_BOT_COMMAND=python main.py
TGMOCK_READY_LOG=Bot starting

对于编译语言（启动前预构建）：

TGMOCK_BUILD_COMMAND=go build -o /tmp/mybot ./cmd/server
TGMOCK_BOT_COMMAND=/tmp/mybot

或在中配置 pyproject.toml:

[tool.tgmock]
bot_command = "python main.py"
ready_log = "Bot starting"
port = 8999
startup_timeout = 15

配置优先级： TGMOCK_* 环境变量> TGMOCK_* 在 .env 文件> [tool.tgmock] 在 pyproject.toml >默认值。

自动补丁（Python机器人——无需更改代码）

对于使用Python的机器人 意图tp （aiogram）或 httpx （python telegram bot v20+），tgmock自动猴子补丁HTTP客户端重定向 api.telegram.org 调用模拟服务器。默认情况下，这是启用的，不需要更改代码。

要禁用：

TGMOCK_AUTO_PATCH=false

手动设置（非Python机器人或auto_patch=false）

对于非Python机器人，或者如果你更喜欢显式控制，请添加 BOT_API_BASE 支持你的bot.tgmock注入 BOT_API_BASE 自动——机器人必须使用它。

图表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电报机器人：

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电报机器人api：

bot, _ := tgbotapi.NewBotAPIWithAPIEndpoint(token, os.Getenv("BOT_API_BASE")+"/bot%s/%s")

pytest插件

pytest插件在以下情况下自动注册 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

看 tests/ 例如。

MCP服务器（克劳德代码）

将tgmock注册为Claude Code MCP服务器：

claude mcp add tgmock --transport stdio -- python3 -m tgmock.mcp_server

或者作为插件安装：

claude plugin install /path/to/tgmock

可用工具

工具 说明
tg_start 启动模拟服务器+机器人。如果 .env 已配置。
tg_send(text) 以测试用户身份发送消息，等待机器人响应。
tg_tap(label) 单击内联键盘按钮（部分标签匹配）。
tg_snapshot 获取当前对话状态。
tg_logs(tail=50) 获取bot stdout/stderr的最后N行。
tg_restart 重启bot+重置模拟状态（保持服务器运行）。
tg_reset 重置用户状态（清除响应/事件）。
tg_events 获取机器人发布的自定义事件
tg_users 列出活动测试用户。
tg_stop 停止一切。

快速会话

tg_start → tg_send("/start") → tg_snapshot → tg_tap("Button") → tg_stop

调试

当机器人无法启动时，错误包括机器人输出的最后30行。 使用 tg_logs() 随时查看机器人正在打印什么。

自定义事件

你的机器人可以将结构化事件发布到tgmock进行断言，而无需解析文本：

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})

然后断言 tg_events(type="tool_call").

许可证

麻省理工学院

相关 MCP