All jobs

Write Unit Tests for a grammY Telegram Bot

Yes. An agent adds Vitest tests that feed fake updates to a grammY bot and capture its API calls, with no Telegram token or network, and opens a pull request.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent looks for the seam that lets a bot be tested without Telegram, and in a codebase like bot-base/telegram-bot-template it is already there. createBot in src/bot/index.ts takes the token, a { config, logger } pair and an optional grammY BotConfig, so a test can pass botInfo and never call getMe. The features are small composers: welcome.ts answers /start in private chats with ctx.t('welcome'), admin.ts puts /setcommands behind the isAdmin filter, language.ts is registered only when there is more than one locale, and unhandled.ts comes last. The repository has no tests and no test script. .github/workflows/main.yml runs npm ci, npm run lint and npm run typecheck and stops there.

The test runner is decided by the repository's own lint rules. The @antfu/eslint-config this project uses rejects import { test } from 'node:test' with the message to import from vitest instead, and prefers it over test, so the agent adds Vitest. Two things then have to be wired before a first test can load. The #root/* imports resolve through package.json to ./build/src/*, the compiled output, and Vitest fails with Cannot find module '#root/bot/index.js' until vitest.config.ts maps that prefix to the TypeScript sources, as tsconfig.json does for the compiler. And src/config.ts builds the config from the environment at import time, so loading it without BOT_TOKEN and BOT_MODE throws Invalid config; the Vitest config sets both, with a token that matches the schema's pattern and reaches no bot.

Each test builds a bot with createBot, a config from the exported createConfig, and a silent pino logger, then installs an API transformer with bot.api.config.use that records the method and payload and returns { ok: true } without calling through. It hands the bot a hand-built update with bot.handleUpdate and asserts on the recorded calls. Against this template, /start in a private chat produces one sendMessage with the text Welcome!; /setcommands from a user outside BOT_ADMINS falls through to the unhandled reply, Unrecognized command. Try /start, while an admin gets a chat action, six setMyCommands calls and a confirmation; /language is unhandled while locales/ holds only en.ftl; and /start in a group produces no call at all. One detail the agent has to get right: a transformer installed after createBot runs before the parseMode('HTML') transformer inside it, so the recorded payload carries no parse_mode, and the tests assert on chat and text.

The webhook path gets the same treatment through Hono. createServer in src/server/index.ts returns an app whose request method needs no listening port: GET / answers {"status":true}, a POST /webhook without the X-Telegram-Bot-Api-Secret-Token header answers 401, and one with the configured secret answers 200 and reaches the handlers. The agent adds a test script, runs it with npm run lint and npm run typecheck, fixes what the linter says about import order, and adds a test step to the workflow. Since tsconfig.json includes only src/**/*, it also makes sure the test files are type-checked and says which line it changed to do that. It does not edit any file under src/bot/features/.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Write unit tests for this grammY Telegram bot. Read package.json, tsconfig.json, eslint.config.js, src/config.ts, src/logger.ts, src/bot/index.ts, every file under src/bot/features, src/bot/filters, src/bot/handlers and src/bot/middlewares, src/bot/i18n.ts, locales/, src/server/index.ts and .github/workflows/main.yml first. Use the test runner the repository's ESLint config expects; run the linter on a first test file to find out. Tests must not contact Telegram: build the bot with createBot, passing botInfo in the BotConfig argument, record outgoing calls with an API transformer that does not call through, and feed updates with bot.handleUpdate. Make the #root/* imports resolve to the TypeScript sources under the runner, and set the environment src/config.ts needs at import time in the runner's config, not in a committed .env. Cover: /start in a private chat and in a group, /setcommands as an admin and as a non-admin, an unhandled message and an unhandled callback query, the /language command with one locale, the isAdmin filter, and the webhook server through Hono's request method with a missing, a wrong and a correct secret token. Assert on what the bot sends, not on internals. Add a test script and a workflow step, make sure the tests are type-checked, run npm run lint, npm run typecheck and the tests, and do not change production code. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

A pull request that adds Vitest to devDependencies with the lockfile change, a vitest.config.ts holding the alias and the two environment values, a small helper that builds a bot with a recording transformer and makes update objects, the test files, a test script and one new step in .github/workflows/main.yml. Nothing under src/bot/features/ changes. The description lists each behaviour covered, pastes the test, lint and type-check output from the sandbox, and notes anything the tests showed that a maintainer may not expect, such as /language answering as an unknown command while there is one locale.

A reviewer reads the helper first, because every test depends on it: that the transformer never calls the real API, and that the fake updates carry the fields grammY's filters look at, like the bot_command entity and the chat type. They check that the tests assert on user-visible results, the method and the text, so that reordering middleware does not break them for no reason. They confirm the token in the Vitest config is a placeholder in the right shape and not a real one. And they decide whether the admin test's expectation of six setMyCommands calls is a behaviour worth pinning or a detail that should be loosened to "at least one".

Run it on every nightly schedule

A bot grows by features, and each new composer arrives without tests unless something asks for them. In the console, add an automation on the Project that holds the bot with a schedule trigger, a cron for a quiet hour and a timezone, and a saved prompt along these lines: list the files under src/bot/features and src/bot/handlers that no test imports, write tests for one of them using the existing helper, run the suite, and open a pull request. Each night then produces at most one small pull request to read in the morning.

To cover a new feature straight away instead, send this body to POST /o/{org}/sessions with the feature's file named in input. A request_id that is a UUID v5 of the repository's full name and the file path keeps a retried request from starting a second run for the same file.

The use case this job follows, with its automation and trigger: Write the missing tests.

Why run it on Rush?

Bot tests are mostly setup, and the setup is where people stall: which runner the lint config tolerates, why the import alias points at a build directory, why importing the config throws. Each of those is found by running something and reading the error. The agent does that in its own sandbox with the dependencies installed from the lockfile, and the run keeps every command and its output, so the pull request can state what failed first and what fixed it.

The sandbox also guarantees the property the tests claim. It holds no bot token, so a test that passes there did not get its answer from Telegram. A developer running the same suite on a laptop with a real .env cannot be as sure, which is why the agent puts the placeholder values in the runner's config and leaves .env out of it.

Frequently asked questions

Do the tests need a Telegram bot token?

No. The bot is built with botInfo supplied, so it never asks Telegram who it is, and a transformer answers every outgoing API call locally. The token in the test config only has to match the pattern src/config.ts validates, digits, a colon and a string.

How does it test a handler that replies with a translated string?

Through the real i18n middleware. The bot under test loads locales/ from the working directory exactly as in production, so the assertion compares against the text in en.ftl. A test for a second locale sets the language through the bot's own language callback and then checks the next reply.

Can it test conversations or sessions that span several messages?

Yes. One bot instance keeps its session storage for the life of the test, so sending several updates in order exercises state across messages. Each test builds its own bot, which gives it a fresh in-memory store and keeps tests from leaking into each other.

More grammY jobs

The same job on other stacks

Keep reading