@yaebal/test

pnpm add -D @yaebal/test

import { Composer } from "@yaebal/core";
import { createTestEnv } from "@yaebal/test";
import { expect, test } from "vitest"; // or node:test, or whatever you use
import { bot } from "./bot.js";

test("replies to /start", async () => {
  const env = createTestEnv(bot);
  const linia = env.createUser({ firstName: "Linia" });

  await linia.sendCommand("start");

  expect(env.lastApiCall("sendMessage")?.params?.text).toBe("Welcome!");
});

test("clicking a button fires the callback handler", async () => {
  const env = createTestEnv(bot);
  const linia = env.createUser();

  await linia.sendCommand("start");
  const bubble = env.lastBotMessage({ withReplyMarkup: true });
  if (bubble) await linia.on(bubble).clickByText("Next »");
});

await linia.sendMessage("hello");
await linia.sendMessage(group, "hello group");  // ChatActor as the first arg
await linia.sendReply(originalMsg, "thanks!");  // reply_to_message + same chat, inferred
await linia.sendCommand("start");               // text: "/start", bot_command entity
await linia.sendCommand("start", "ref42");      // text: "/start ref42"

import { bold, format } from "@yaebal/core";

// format()/fmt results work too — entities are extracted automatically
await linia.sendMessage(format`Check out ${bold("this")}`);

// every method auto-generates file_id/file_unique_id and Telegram's required fields
await linia.sendPhoto({ caption: "Look!", spoiler: true });
await linia.sendVideo();
await linia.sendDocument();
await linia.sendVoice();
await linia.sendAudio();
await linia.sendAnimation();
await linia.sendVideoNote();
await linia.sendSticker({ emoji: "🔥" });
await linia.sendLocation({ latitude: 48.8566, longitude: 2.3522 });
await linia.sendContact({ phone_number: "+1234567890", first_name: "Bob" });
await linia.sendDice("🎯");

await linia.sendMediaGroup(group, [
  { photo: [{ file_id: "f1", file_unique_id: "u1", width: 800, height: 600 }] },
  { photo: [{ file_id: "f2", file_unique_id: "u2", width: 800, height: 600 }] },
]); // one update per item, all sharing media_group_id

await linia.click("vote:up", msg);          // raw callback_data
await linia.on(msg).click("vote:up");        // same, message pre-bound
await linia.on(msg).clickByText("Next »");   // scans msg's inline_keyboard for the label

await linia.react("👍", msg);   // old_reaction inferred from linia's last react()
await linia.react("❤", msg);    // old: ["👍"], new: ["❤"] — inferred, not passed in
await linia.react([], msg);     // clear all of linia's reactions

await linia.join(group);   // chat.members + a chat_member update + service message
await linia.leave(group);

await linia.sendInlineQuery("cats", group);   // chat_type derived from group.type
await linia.chooseInlineResult("result-1", "cats");

// the full flow: pre_checkout_query → verifies the bot answered { ok: true } → successful_payment.
// throws if the bot never answers, or answers with ok: false — just like real Telegram would
// never deliver successful_payment in that case.
await linia.sendSuccessfulPayment({ invoice_payload: "sub_monthly" });

const group = env.createChat({ type: "group", title: "devs" });

await linia.in(group).sendMessage("morning team");
await linia.in(group).sendCommand("help");
await linia.in(group).join();
await linia.in(group).on(msg).clickByText("yes");

await linia.on(msg).click("action:1");
await linia.on(msg).react("👍");
await linia.on(msg).editMessage("updated");

bot.on("message", (ctx) =>
  ctx.send("Pick:", { reply_markup: { inline_keyboard: [[{ text: "Next", callback_data: "next" }]] } }),
);
bot.callbackQuery("next", async (ctx) => {
  const { chat, message_id } = ctx.callbackQuery.message;
  await ctx.api.call("editMessageText", { chat_id: chat.id, message_id, text: "Done!" });
});

await linia.sendMessage("hi");
const bubble = env.lastBotMessage()!;
await linia.on(bubble).clickByText("Next");
bubble.text; // "Done!" — same object, mutated in place, even though we captured it before the edit

env.onApi("getMe", { id: 7, is_bot: true, first_name: "MyBot", username: "my_bot" });

// { times: 1 } is one-shot, then falls back to the next queued/permanent reply —
// perfect for "first call fails, second succeeds":
env.onApi("sendMessage", apiError(429, "Too Many Requests", { retry_after: 1 }), { times: 1 });
env.onApi("sendMessage", { message_id: 1, date: 0, chat: { id: 1, type: "private" } });

import { apiError } from "@yaebal/test";
import { TelegramError } from "@yaebal/core";

env.onApi("sendMessage", apiError(403, "Forbidden: bot was blocked by the user"));

// the bot sees a real TelegramError (TestApiError extends it):
try {
  await ctx.reply("hi");
} catch (error) {
  error instanceof TelegramError; // true
  error.code;                     // 403
  error.parameters;               // response_parameters when Telegram sends them
}

const env = createTestEnv(bot, { strictApi: true });      // throw on an unstubbed method
const env2 = createTestEnv(bot, { strictDispatch: true }); // throw if no handler consumed the update

const env = createTestEnv(bot);
env.useFakeTimers(); // arm it *before* the code under test schedules a timer you want to control

await linia.sendCommand("start"); // handler calls setTimeout(..., 60 * 60 * 1000) internally

await env.advanceTime(60 * 60 * 1000); // fires it instantly
env.shutdown(); // restores real timers — always call this in teardown

import { installTestClock } from "@yaebal/test";

const clock = installTestClock(1_700_000_000_000);
setInterval(() => {/* … */}, 1000);
await clock.advance(3500); // fires 3 times
clock.restore();

import type { TestPack } from "@yaebal/test";

export function myPluginTestPack(options?: MyPluginOptions): TestPack {
  return {
    name: "my-plugin",
    setup(env) {
      installMyPlugin(env.api, options); // wire whatever the plugin needs onto env.api/env
    },
  };
}

const env = createTestEnv(bot, { packs: [myPluginTestPack()] });

import { createUpdate, detectUpdateType, pollUpdate } from "@yaebal/test";

const poll = pollUpdate({ question: "coffee or tea?", options: ["coffee", "tea"] });

// hand-build any update shape; update_id is filled in for you
const update = createUpdate({
  edited_message: { message_id: 1, date: 0, chat: { id: 1, type: "private" } },
});

detectUpdateType(update); // → "edited_message"
await env.dispatch(update); // ship it through the bot directly

import { webhookCallback } from "@yaebal/core";
import { webhookRequest, messageUpdate } from "@yaebal/test";

const handler = webhookCallback(bot, { secretToken: "s3cret" });
const res = await handler(
  webhookRequest(messageUpdate({ text: "hi" }), { secretToken: "s3cret" }),
);
res.status; // → 200

import { collectUpdates, messageUpdate } from "@yaebal/test";

const { sink, updates } = collectUpdates();
await sink.handleUpdate(messageUpdate({ text: "hi" }));
updates.length; // → 1

import { withFetch } from "@yaebal/test";

await withFetch(
  async () =>
    new Response(new Uint8Array([1, 2, 3]), { headers: { "content-type": "image/jpeg" } }),
  async () => {
    const res = await panelHandler(request);
    res.status; // → 200
  },
);

- const { api, calls } = mockApi();
- await runMiddleware(bot, createContext(messageUpdate({ text: "/start" }), api));
- assert.equal(calls[0]?.method, "sendMessage");
+ const env = createTestEnv(bot);
+ await env.createUser().sendCommand("start");
+ assert.equal(env.lastApiCall("sendMessage")?.method, "sendMessage");