Production-grade testing infrastructure for grammY bots.

docs. npm. examples.

Why

Testing a Telegram bot used to mean spinning up a real token, sending live messages, and hoping the Telegram API behaved. grammY ships no testing tools itself, and existing community solutions are either unmaintained, Deno-only, or too low-level to be ergonomic.

grammy-testing drives your real bot in-process. No token. No network. No sleep timers. Dispatch a synthetic update, the bot handles it exactly as it would in production, and you assert on the captured replies.

Quick Start

npm install --save-dev grammy-testing

// bot.ts
bot.command('start', async (ctx) => {
  await ctx.reply('Welcome! Use /help to see available commands.');
});

// bot.spec.ts
import { prepareBot } from 'grammy-testing';

const { chats } = await prepareBot(createBot());
const user = chats.newUser();

await user.sendCommand('/start');

expect(user.replies.lastOrThrow().text).toContain('Welcome');

Features

Actors & chat types

• Create users and admins with custom profiles (chats.newUser(), chats.newAdmin())
• Create groups, supergroups, and channels (chats.newGroup(), chats.newSupergroup(), chats.newChannel())
• Place users into group contexts (group.own(user))

Dispatch — send anything a real user can send

• Text messages, commands, photos, documents, stickers, polls, dice, locations, contacts
• Callback queries, inline queries, reactions, media groups
• Member join/leave events, chat member status changes
• Channel posts, forwarded messages, business account messages

Reply & request assertions

• user.replies.lastOrThrow() — the last reply sent to this user
• group.messages.last — the latest message in a group context
• chats.outgoing.requests — every raw Telegram API call the bot made

Session & state injection

• mockSession(initial) — seed a pre-set session state for unit testing
• mockChatSession(initial) — per-chat session injection
• mockState(initial) — conversations and state machine testing

Isolation utilities

• prepareMiddleware(fn) — test a single middleware without a full bot
• prepareComposer(Composer) — test a composer class in isolation

Ecosystem

• Works with Vitest and Jest
• TypeScript-first — all types exported
• Low-level API available for advanced and custom scenarios

Plugin interop

| Plugin | How it installs | Supported since | | --------------------------------- | ----------------------------------------------------------------------- | ----------------- | | @grammyjs/conversations | bot.use(conversations()) | v0.21.0 | | @grammyjs/menu | bot.use(menu) | v0.21.0 | | @grammyjs/parse-mode | formatting utilities, no transformer | v0.21.0 | | @grammyjs/chat-members | bot.use(chatMembers(...)) / bot.api.config.use(hydrateChatMember()) | v0.21.0 / v0.23.0 | | grammy-media-groups | bot.api.config.use(mediaGroupTransformer(...)) | v0.24.0 | | @grammyjs/files | bot.api.config.use(hydrateFiles(...)) | v0.23.0 | | @grammyjs/hydrate | bot.api.config.use(hydrateApi()) + bot.use(hydrate()) | v0.23.0 | | @grammyjs/auto-retry | bot.api.config.use(autoRetry(...)) | v0.23.0 | | @grammyjs/transformer-throttler | bot.api.config.use(throttler(...)) | v0.23.0 |

Examples

26 self-contained bots with matching test files live in examples/:

| # | Scenario | | --- | -------------------------------------------------------------------------------------------------------- | | 01 | Echo bot — simplest text-echo handler | | 02 | Command bot — /start and /help | | 03 | Greeting bot — per-user name with fallback | | 04 | Chat-type filter — private vs. group routing | | 05 | Inline keyboard — regex handler with keyboard | | 06 | Callback query — inline keyboard responses | | 07 | Session counter — persistent per-user state | | 08 | Chat settings — mockChatSession usage | | 09 | Photo bot — caption extraction | | 10 | Document bot — file-ID and MIME type reply | | 11 | Poll bot — quiz creation and answer scoring | | 12 | Group welcome — new_chat_members service event | | 13 | Admin guard — getChatMember status check | | 14 | Moderation bot — banChatMember / restrictChatMember | | 15 | Channel post bot — channel_post handler | | 16 | Reactions bot — message_reaction handler | | 17 | Dice game — incoming dice value evaluation | | 18 | Middleware test — isolation with prepareMiddleware | | 19 | Composer test — isolation with prepareComposer | | 20 | Multi-chat scenario — cross-chat summary posting | | 21 | Files bot — @grammyjs/files — file.getUrl() from ctx.getFile() | | 22 | Hydrate bot — @grammyjs/hydrate — hydrated replies with delete() | | 23 | Auto-retry bot — @grammyjs/auto-retry — broadcast with error handling | | 24 | Guest mode bot — answerGuestQuery for guest_message updates | | 25 | Rich message bot — sendRichMessage with a draft preview | | 26 | Reaction removal bot — deleteMessageReaction via /clearreactions |

Documentation

Full API reference, step-by-step guides, and recipes are available at drsmile444.github.io/grammy-testing/.

The examples/ directory also covers a wide range of real-world patterns — from the simplest echo bot to multi-chat scenarios with sessions and admin guards.

Credits

grammy-testing stands on the shoulders of:

• grammy_tests by dcdunkan — the original testing concept for grammY bots that inspired this library's design
• ua-anti-spam-bot by MoC-OSS — a real-world bot whose test patterns shaped the high-level API

License

MIT — see LICENSE.