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 tgmockpytest插件通过以下方式自动注册 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").
许可证
麻省理工学院