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:
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.
What's in the box
- Mock Bot API server โ every method of the current Bot API accepted, about 20 with real side effects (messages, media, edits, forum topics, rich messages), the rest answered from the official spec. Webhook and
getUpdatespolling, per-chatmessage_ids like Telegram. - Realistic failures โ opt-in Telegram flood limits (
429+retry_after, paid broadcasts), added latency and random500s, to see how the bot copes before production does it for you. - Request journal โ every Bot API call the bot made, with parameters and status, at
/debug/requests. - xk6 extension โ virtual Telegram users from k6 scenarios with
send,click,awaitText,findButton. - User pools โ two-phase scenarios (register-then-replay) via NDJSON files, with
TAG/OFFSET/LIMIT/SHUFFLEenv knobs. - HTMX debug chat โ browser UI for manual testing, served by the mock itself, no real Telegram.
- Real-Telegram relay (
telegym-proxy) โ drive the bot-under-test from a real Telegram client through a throwaway proxy bot. - Metrics & dashboards โ Prometheus + Grafana stack with a pre-provisioned dashboard correlating k6 load and mock-side latency.
- Prebuilt releases โ binaries for Linux, macOS and Windows, k6 with the extension, and a multi-arch Docker image.