@yaebal/test 0.0.1 → 0.2.0

package/src/index.ts

@@ -1,173 +1,83 @@
 /**
- * @yaebal/test — testing utilities for yaebal bots.
+ * @yaebal/test — an actor-driven test framework for yaebal bots, with zero dependency on any
+ * test runner or assertion library. Works with `node:test`, vitest, bun:test, jest, ava —
+ * anything that can `await` a promise and call `assert`.
  *
- * every plugin test used to hand-build fake updates and a mock api. this package
- * extracts that boilerplate: {@link mockApi} records every call, the `*Update`
- * factories produce real {@link Update} shapes, and {@link createContext} wraps
- * one in a core {@link Context}.
- */
-
-import {
-	type Api,
-	type Composer,
-	Context,
-	type Message,
-	type NextFn,
-	type Update,
-	type UpdateName,
-} from "@yaebal/core";
-
-/** a single recorded api call: the method name and the params it was given. */
-export interface RecordedCall {
-	method: string;
-	params: Record<string, unknown> | undefined;
-}
-
-/** result of {@link mockApi}: the fake `api` plus the array it records into. */
-export interface MockApi {
-	api: Api;
-	calls: RecordedCall[];
-}
-
-/** default results for known methods; everything else resolves to `{}`. */
-function defaultResult(method: string): unknown {
-	if (method.startsWith("send") || method === "copyMessage" || method === "forwardMessage") {
-		return { message_id: 1 };
-	}
-
-	if (method === "answerCallbackQuery") return true;
-	if (method === "getMe") return { id: 1, is_bot: true, first_name: "bot", username: "bot" };
-
-	return {};
-}
-
-/**
- * a fake {@link Api} whose every method records `{ method, params }` into `calls`
- * and resolves to a sensible default (`{ message_id: 1 }` for `send*`, `true` for
- * `answerCallbackQuery`, `{}` otherwise). hook registrars (`before`/`after`/
- * `onError`) are no-ops that return the api for chaining.
- */
-export function mockApi(): MockApi {
-	const calls: RecordedCall[] = [];
-
-	const record = (method: string, params?: Record<string, unknown>): Promise<never> => {
-		calls.push({ method, params });
-		return Promise.resolve(defaultResult(method) as never);
-	};
-
-	const registrar: Record<string, unknown> = {
-		call: (method: string, params?: Record<string, unknown>) => record(method, params),
-		fileUrl: (filePath: string) => `https://example.invalid/file/${filePath}`,
-		before: () => api,
-		after: () => api,
-		onError: () => api,
-	};
-
-	const api = new Proxy(registrar, {
-		get(obj, prop: string) {
-			if (prop in obj) return obj[prop];
-
-			const method = (params?: Record<string, unknown>) => record(prop, params);
-			obj[prop] = method;
-
-			return method;
-		},
-	}) as unknown as Api;
-
-	return { api, calls };
-}
-
-let updateIdCounter = 0;
-
-/** build an {@link Update} from a partial, filling in a fresh `update_id`. */
-export function createUpdate(partial: Partial<Update> = {}): Update {
-	return { update_id: ++updateIdCounter, ...partial };
-}
-
-/** options for {@link messageUpdate}. */
-export interface MessageUpdateOptions {
-	text?: string;
-	chatId?: number;
-	fromId?: number;
-	chatType?: "private" | "group" | "supergroup" | "channel";
-}
-
-/** build a message {@link Update}. */
-export function messageUpdate(options: MessageUpdateOptions = {}): Update {
-	const { text = "", chatId = 1, fromId = chatId, chatType = "private" } = options;
-
-	return createUpdate({
-		message: {
-			message_id: 1,
-			date: 0,
-			chat: { id: chatId, type: chatType },
-			from: { id: fromId, is_bot: false, first_name: "u" },
-			text,
-		},
-	});
-}
-
-/** options for {@link callbackUpdate}. */
-export interface CallbackUpdateOptions {
-	data?: string;
-	chatId?: number;
-	fromId?: number;
-}
-
-/** build a callback_query {@link Update}. */
-export function callbackUpdate(options: CallbackUpdateOptions = {}): Update {
-	const { data = "", chatId = 1, fromId = chatId } = options;
-
-	return createUpdate({
-		callback_query: {
-			id: "1",
-			chat_instance: "0",
-			from: { id: fromId, is_bot: false, first_name: "u" },
-			message: {
-				message_id: 1,
-				date: 0,
-				chat: { id: chatId, type: "private" },
-			},
-			data,
-		},
-	});
-}
-
-/** infer which payload key an update carries; defaults to `"message"`. */
-export function detectUpdateType(update: Update): UpdateName {
-	if (update.message) return "message";
-	if (update.edited_message) return "edited_message";
-	if (update.channel_post) return "channel_post";
-	if (update.callback_query) return "callback_query";
-
-	const bag = update as unknown as Record<string, unknown>;
-	for (const key of Object.keys(bag)) {
-		if (key !== "update_id" && bag[key] !== undefined) return key as UpdateName;
-	}
-
-	return "message";
-}
-
-/**
- * wrap an {@link Update} in a core {@link Context}. the api defaults to a fresh
- * {@link mockApi}; pass `updateType` to override the auto-detected one.
+ * {@link createTestEnv} wraps your bot and hands you {@link UserActor}/{@link ChatActor} actors
+ * that send it real updates — messages, commands, media, reactions, button clicks, joins,
+ * payments — the way real Telegram users would. every outgoing api call is intercepted and
+ * recorded (no real HTTP), with sensible auto-stubs, `onApi`/`apiError` overrides for the rest,
+ * a virtual clock for TTL/retry tests, and satellite-plugin test packs.
+ *
+ * fixture builders ({@link messageUpdate} & co.), {@link webhookRequest}/{@link collectUpdates},
+ * and {@link withFetch} remain as the escape hatch beneath the actor api — reach for them when
+ * you need a raw update shape or full control.
  */
-export function createContext(update: Update, api?: Api, updateType?: UpdateName): Context {
-	return new Context({
-		api: api ?? mockApi().api,
-		update,
-		updateType: updateType ?? detectUpdateType(update),
-	});
-}
-
-const noop: NextFn = async () => {};
-
-/** run a composer's middleware against a context. resolves when the chain settles. */
-export async function runMiddleware<C extends Context>(
-	composer: Composer<C>,
-	ctx: C,
-): Promise<void> {
-	await composer.toMiddleware()(ctx, noop);
-}
 
-export type { Message };
+export { type MockApi, type MockApiOptions, mockApi } from "./api.js";
+export {
+	type ApiErrorSentinel,
+	apiError,
+	type BotMessage,
+	ChatActor,
+	type ChatMembership,
+	type ChatType,
+	type CreateChatOptions,
+	createTestEnv,
+	installTestClock,
+	isApiErrorSentinel,
+	type LastBotMessageQuery,
+	type MediaOptions,
+	type MessageOptions,
+	type MockResult,
+	type OnApiOptions,
+	type RecordedCall,
+	TestApiError,
+	type TestClock,
+	TestEnv,
+	type TestEnvOptions,
+	type TestPack,
+	UserActor,
+	UserInChatScope,
+	UserOnMessageScope,
+} from "./env.js";
+export { withFetch } from "./fetch.js";
+
+export { type FoundButton, findButton } from "./keyboard.js";
+export { toPlain } from "./normalize.js";
+export {
+	type BuildUserOptions,
+	buildUser,
+	type CallbackUpdateOptions,
+	type ChatJoinRequestUpdateOptions,
+	type ChatMemberUpdateOptions,
+	type ChosenInlineResultUpdateOptions,
+	callbackUpdate,
+	channelPostUpdate,
+	chatJoinRequestUpdate,
+	chatMemberUpdate,
+	chosenInlineResultUpdate,
+	createUpdate,
+	detectUpdateType,
+	editedChannelPostUpdate,
+	editedMessageUpdate,
+	type InlineQueryUpdateOptions,
+	inlineQueryUpdate,
+	type MessageUpdateOptions,
+	messageUpdate,
+	myChatMemberUpdate,
+	type PollAnswerUpdateOptions,
+	type PollUpdateOptions,
+	type PreCheckoutQueryUpdateOptions,
+	pollAnswerUpdate,
+	pollUpdate,
+	preCheckoutQueryUpdate,
+	type ShippingQueryUpdateOptions,
+	shippingQueryUpdate,
+} from "./updates.js";
+export {
+	collectUpdates,
+	type UpdateCollector,
+	type WebhookRequestOptions,
+	webhookRequest,
+} from "./webhook.js";

package/src/internal.ts

@@ -0,0 +1,43 @@
+import type { FormatResult, MessageEntity, Update } from "@yaebal/core";
+
+/**
+ * the sliver of {@link TestEnv} actors need — kept as a separate interface (rather than a
+ * circular import of the class) so `chat-actor.ts`/`user-actor.ts` don't depend on `env.ts`.
+ */
+export interface ActorHost {
+	dispatch(update: Update): Promise<void>;
+	nextMessageId(): number;
+	now(): number;
+	/** did the bot answer `answerPreCheckoutQuery` for `preCheckoutQueryId` with `ok: true`? */
+	answeredPreCheckoutQuery(preCheckoutQueryId: string): boolean;
+}
+
+/** text an actor method accepts: a plain string, or a `format`/`fmt` result carrying entities. */
+export type SendText = string | FormatResult;
+
+function isFormatResult(value: unknown): value is FormatResult {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"text" in value &&
+		"entities" in value &&
+		Array.isArray((value as FormatResult).entities)
+	);
+}
+
+/** resolve a `SendText` into `{ text, entities }`, merging in any `extraEntities`. */
+export function resolveSendText(
+	text: SendText,
+	extraEntities: MessageEntity[] = [],
+): { text: string; entities: MessageEntity[] } {
+	const resolved = isFormatResult(text) ? text : { text, entities: [] };
+	return { text: resolved.text, entities: [...resolved.entities, ...extraEntities] };
+}
+
+let fileCounter = 0;
+
+/** a fake `{ file_id, file_unique_id }` pair — good enough for tests, never a real download. */
+export function fakeFile(prefix: string): { file_id: string; file_unique_id: string } {
+	const n = ++fileCounter;
+	return { file_id: `${prefix}_${n}`, file_unique_id: `u${prefix}${n}` };
+}

package/src/keyboard.test.ts

@@ -0,0 +1,35 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { findButton } from "./keyboard.js";
+
+test("findButton locates a button by text and reports its position", () => {
+	const markup = {
+		inline_keyboard: [
+			[{ text: "a", callback_data: "a" }],
+			[
+				{ text: "b", callback_data: "b" },
+				{ text: "Next", callback_data: "page:2" },
+			],
+		],
+	};
+
+	const found = findButton(markup, "Next");
+	assert.equal(found?.callback_data, "page:2");
+	assert.equal(found?.row, 1);
+	assert.equal(found?.col, 1);
+
+	assert.equal(findButton(markup, /^n/i)?.text, "Next");
+	assert.equal(findButton(markup, "missing"), undefined);
+	assert.equal(findButton(undefined, "missing"), undefined);
+});
+
+test("findButton unwraps a builder instance via toJSON()", () => {
+	class FakeInlineKeyboard {
+		toJSON() {
+			return { inline_keyboard: [[{ text: "Restart", callback_data: "restart" }]] };
+		}
+	}
+
+	const found = findButton(new FakeInlineKeyboard(), "Restart");
+	assert.equal(found?.callback_data, "restart");
+});

package/src/keyboard.ts

@@ -0,0 +1,38 @@
+import { toPlain } from "./normalize.js";
+
+/** an inline keyboard button found by {@link findButton}, with its position. */
+export interface FoundButton {
+	text: string;
+	row: number;
+	col: number;
+	[key: string]: unknown;
+}
+
+/**
+ * search an inline keyboard (a `reply_markup`-shaped object — or an `InlineKeyboard`/`Keyboard`
+ * builder instance, unwrapped via `toJSON()` automatically — e.g. from a recorded call's params,
+ * or a {@link BotMessage}'s `reply_markup`) for a button whose text matches a string or regex.
+ * returns the button (plus its `row`/`col`) or `undefined`.
+ */
+export function findButton(markup: unknown, match: string | RegExp): FoundButton | undefined {
+	const plain = toPlain<{ inline_keyboard?: Array<Array<Record<string, unknown>>> } | undefined>(
+		markup,
+	);
+	const rows = plain?.inline_keyboard ?? [];
+
+	for (let row = 0; row < rows.length; row++) {
+		const cols = rows[row] ?? [];
+
+		for (let col = 0; col < cols.length; col++) {
+			const button = cols[col];
+			if (!button) continue;
+
+			const text = typeof button.text === "string" ? button.text : "";
+			const matches = typeof match === "string" ? text === match : match.test(text);
+
+			if (matches) return { ...button, text, row, col };
+		}
+	}
+
+	return undefined;
+}

package/src/normalize.ts

@@ -0,0 +1,34 @@
+/**
+ * builder instances (e.g. `InlineKeyboard`/`Keyboard` from `@yaebal/keyboard`) expose a
+ * `toJSON()` the same way `Date`/`Map`-like classes do. unwrap them so recorded calls and
+ * assertions see plain JSON, never a class instance — no `@yaebal/keyboard` dependency needed,
+ * this is just duck typing on the standard `toJSON` convention.
+ */
+export function toPlain<T = unknown>(value: unknown): T {
+	if (value && typeof (value as { toJSON?: unknown }).toJSON === "function") {
+		return (value as { toJSON(): T }).toJSON();
+	}
+
+	return value as T;
+}
+
+/** shallow-clone `params`, normalizing `reply_markup` (and, for `answerInlineQuery`, each `results[].reply_markup`) via {@link toPlain}. */
+export function normalizeParams(
+	params: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+	if (!params) return params;
+
+	const out = { ...params };
+
+	if ("reply_markup" in out) out.reply_markup = toPlain(out.reply_markup);
+
+	if (Array.isArray(out.results)) {
+		out.results = out.results.map((item) =>
+			item && typeof item === "object" && "reply_markup" in item
+				? { ...item, reply_markup: toPlain((item as Record<string, unknown>).reply_markup) }
+				: item,
+		);
+	}
+
+	return out;
+}

package/src/reactions.ts

@@ -0,0 +1,18 @@
+/**
+ * per-message reaction state, so {@link UserActor.react} never needs `oldReaction` spelled out
+ * by hand — it's inferred from whatever that user's last `react()` on this message left behind.
+ * keyed by the `Message` object's identity (a `WeakMap`, so it costs nothing once a message is
+ * no longer referenced) rather than `message_id`, since ids aren't guaranteed unique across chats.
+ */
+const store = new WeakMap<object, Map<number, string[]>>();
+
+/** the emojis a given user currently has on `message` (per-message, per-user reaction state). */
+export function reactionsOf(message: object): Map<number, string[]> {
+	let state = store.get(message);
+	if (!state) {
+		state = new Map();
+		store.set(message, state);
+	}
+
+	return state;
+}

package/src/updates.test.ts

@@ -0,0 +1,107 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+	buildUser,
+	callbackUpdate,
+	channelPostUpdate,
+	chatJoinRequestUpdate,
+	chatMemberUpdate,
+	chosenInlineResultUpdate,
+	createUpdate,
+	detectUpdateType,
+	editedMessageUpdate,
+	inlineQueryUpdate,
+	messageUpdate,
+	myChatMemberUpdate,
+	pollAnswerUpdate,
+	pollUpdate,
+	preCheckoutQueryUpdate,
+	shippingQueryUpdate,
+} from "./updates.js";
+
+test("messageUpdate produces a valid message update", () => {
+	const update = messageUpdate({ text: "hello", chatId: 42, chatType: "group" });
+
+	assert.ok(update.update_id > 0);
+	assert.equal(update.message?.text, "hello");
+	assert.equal(update.message?.chat.id, 42);
+	assert.equal(update.message?.chat.type, "group");
+	assert.equal(update.message?.from?.id, 42);
+});
+
+test("callbackUpdate produces a valid callback_query update", () => {
+	const update = callbackUpdate({ data: "click", chatId: 7, fromId: 9 });
+
+	assert.equal(update.callback_query?.data, "click");
+	assert.equal(update.callback_query?.from.id, 9);
+	assert.equal(update.callback_query?.message?.chat.id, 7);
+});
+
+test("createUpdate fills a fresh update_id", () => {
+	const a = createUpdate();
+	const b = createUpdate();
+
+	assert.notEqual(a.update_id, b.update_id);
+});
+
+test("buildUser auto-allocates distinct ids and fills defaults", () => {
+	const a = buildUser();
+	const b = buildUser({ firstName: "Linia", username: "linia" });
+
+	assert.notEqual(a.id, b.id);
+	assert.equal(b.first_name, "Linia");
+	assert.equal(b.username, "linia");
+	assert.equal(b.is_bot, false);
+});
+
+test("channelPostUpdate / editedMessageUpdate build the right update key", () => {
+	assert.equal(channelPostUpdate({ text: "hi" }).channel_post?.text, "hi");
+	assert.equal(channelPostUpdate().channel_post?.chat.type, "channel");
+	assert.equal(editedMessageUpdate({ text: "hi" }).edited_message?.text, "hi");
+});
+
+test("inlineQueryUpdate / chosenInlineResultUpdate build their payloads", () => {
+	const iq = inlineQueryUpdate({ query: "cats", fromId: 5 });
+	assert.equal(iq.inline_query?.query, "cats");
+	assert.equal(iq.inline_query?.from.id, 5);
+
+	const cir = chosenInlineResultUpdate({ resultId: "r1", query: "cats" });
+	assert.equal(cir.chosen_inline_result?.result_id, "r1");
+});
+
+test("shippingQueryUpdate / preCheckoutQueryUpdate build valid payloads", () => {
+	const sq = shippingQueryUpdate({ shippingAddress: { city: "Berlin" } });
+	assert.equal(sq.shipping_query?.shipping_address.city, "Berlin");
+
+	const pcq = preCheckoutQueryUpdate({ currency: "EUR", totalAmount: 500 });
+	assert.equal(pcq.pre_checkout_query?.currency, "EUR");
+	assert.equal(pcq.pre_checkout_query?.total_amount, 500);
+});
+
+test("pollUpdate / pollAnswerUpdate build valid payloads", () => {
+	const poll = pollUpdate({ question: "?", options: ["a", "b", "c"] });
+	assert.equal(poll.poll?.options.length, 3);
+	assert.equal(poll.poll?.options[1]?.text, "b");
+
+	const answer = pollAnswerUpdate({ optionIds: [1] });
+	assert.deepEqual(answer.poll_answer?.option_ids, [1]);
+});
+
+test("myChatMemberUpdate / chatMemberUpdate / chatJoinRequestUpdate build valid payloads", () => {
+	const my = myChatMemberUpdate({ oldStatus: "left", newStatus: "member" });
+	assert.equal(my.my_chat_member?.old_chat_member.status, "left");
+	assert.equal(my.my_chat_member?.new_chat_member.status, "member");
+
+	const other = chatMemberUpdate({ userId: 7 });
+	assert.equal(other.chat_member?.new_chat_member.user.id, 7);
+
+	const join = chatJoinRequestUpdate({ chatId: 3, fromId: 4, bio: "hi" });
+	assert.equal(join.chat_join_request?.chat.id, 3);
+	assert.equal(join.chat_join_request?.bio, "hi");
+});
+
+test("detectUpdateType infers the payload key", () => {
+	assert.equal(detectUpdateType(messageUpdate()), "message");
+	assert.equal(detectUpdateType(callbackUpdate()), "callback_query");
+	assert.equal(detectUpdateType(pollUpdate()), "poll");
+});