telegym

Load testing for Telegram bots โ€” drop-in mock of the Bot API plus a k6 extension for virtual-user scenarios. Works with any bot, any language.

CI Go Reference Go Version Supported Bot API License: MIT Latest Release Docker image Ask DeepWiki

Why

vs telegram-test-api

Node-based mock is great for functional smoke tests, but not designed for thousands of concurrent virtual users.

vs Test DC

Real Telegram infrastructure with Telethon / Pyrogram is accurate but expensive โ€” each VU is a real MTProto session, throttled above a few hundred clients.

vs raw k6

k6 is the industry standard for load, but it speaks HTTP, not Bot API. telegym bridges the gap with an xk6 extension.

Architecture

  k6 scenario โ”€โ”€โ–บ xk6-telegym โ”€โ”€โ–บ POST /debug/inject/update โ”€โ”€โ–บ telegym-mock
                                                                    โ”‚
                                        webhook POST, or the bot's getUpdates
                                                                    โ–ผ
                                                                your bot
                                                                    โ”‚
                                                                    โ–ผ
                                             POST telegym-mock/bot<token>/sendMessage
                                                                    โ”‚
                                                                    โ–ผ
                                                     stored per chat in the mock
                                                                    โ”‚
                                                                    โ–ผ
                         tg.awaitText / awaitButton โ—„โ”€โ”€ GET /debug/messages/:token

Quickstart

From zero to a load test in three commands:

docker run the mock, start a bot, run a k6 scenario: 20 virtual users, all checks pass

No Go needed: run the mock from Docker and grab k6 with the extension from Releases.

docker run --rm -p 5678:5678 ghcr.io/kolomiichenko/telegym-mock
./k6 run your-scenario.js           # k6 + xk6-telegym from the release archive

A bot that polls getUpdates works with the container as is. A webhook bot has to register a URL the container can reach, e.g. http://host.docker.internal:8443/webhook on Docker Desktop, not localhost.

Or build everything from source and smoke-test the full stack against the bundled echobot:

# Optional one-time setup: copies .env.example -> .env and pre-fetches modules.
make init

# Build the mock, proxy, demo echobot, and a custom k6 with the xk6-telegym
# extension. The k6 build takes ~13s the first time.
make build build-examples

# Smoke test the full stack against the bundled echobot example
./examples/echobot/run.sh

# Output:
#   checks_total.......: 10440   258.85/s
#   checks_succeeded...: 100.00% 10440 out of 10440
#   โœ“ welcome arrived
#   โœ“ welcome under 500ms

Point your own bot at the mock โ€” then drive it manually in a browser, or with k6, or even from real Telegram:

# Start the mock and your bot (separate terminals)
./bin/telegym-mock
TELEGRAM_API_URL=http://localhost:5678 \
TELEGRAM_TOKEN=1234567890:telegym_default_mock_token_xxxxxxxx \
./your-bot                          # webhook (setWebhook) or polling (getUpdates), both work

# Then pick a driver:
open http://localhost:5678/debug/chat   # manual click-around in the browser
./bin/k6 run path/to/your-scenario.js   # load test (use ./bin/k6, not `brew install k6` โ€” the bundled binary has the xk6-telegym extension)
make proxy-up                           # real Telegram client โ†’ mock (needs PROXY_TOKEN + MOCK_BOT_TOKEN)

Scenario API

JS scenarios import the extension as k6/x/telegym and get a default export exposing newUser():

import tg from 'k6/x/telegym';

const u = tg.newUser(0);             // 0 = auto-allocate chat ID per VU
u.send('/start');                    // inject a text message
const m = u.awaitText('^Welcome', 5); // wait up to 5s for matching reply
u.click('age_verify');               // inject a callback query

Debug chat

The mock serves a chat UI at /debug/chat: talk to your bot by hand, click its inline buttons, watch replies arrive, all while a load test runs in another terminal.

debug chat: /start, the bot replies with an inline button, clicking it gets an answer

What's in the box