@yaebal/test 0.0.1 → 0.2.0

package/src/bot-messages.ts

@@ -0,0 +1,117 @@
+import type { Api, Chat, Message } from "@yaebal/core";
+
+/** `Message`'s own `reply_markup` union — reused so a `BotMessage` structurally satisfies `Message`. */
+type ReplyMarkup = NonNullable<Message["reply_markup"]>;
+
+/**
+ * a live mirror of one message the bot sent — built from the outgoing `send*` params (so it's
+ * populated even against the builtin `{ message_id }` stub, no `onApi` override needed) and kept
+ * in sync in place as `editMessageText`/`editMessageCaption`/`editMessageReplyMarkup` calls land,
+ * so a reference captured before an edit still reflects it after.
+ */
+export interface BotMessage {
+	message_id: number;
+	chat: { id: number; type: Chat["type"] };
+	text?: string;
+	caption?: string;
+	reply_markup?: ReplyMarkup;
+	date: number;
+}
+
+export interface LastBotMessageQuery {
+	/** scope to a specific chat (an `{ id }`-shaped value — a `ChatActor` or `pmChat` both qualify). */
+	chat?: { id: number };
+	/** only consider messages currently carrying a non-empty `inline_keyboard`. */
+	withReplyMarkup?: boolean;
+	/** arbitrary predicate over the call that produced (or last touched) the message. */
+	where?: (call: { method: string; params: Record<string, unknown> | undefined }) => boolean;
+}
+
+export interface BotMessageTracker {
+	lastBotMessage(query?: LastBotMessageQuery): BotMessage | undefined;
+	botMessage(chatId: number, messageId: number): BotMessage | undefined;
+	clear(): void;
+}
+
+const SEND_LIKE = (method: string): boolean =>
+	method.startsWith("send") || method === "forwardMessage" || method === "copyMessage";
+
+function hasInlineKeyboard(markup: ReplyMarkup | undefined): boolean {
+	const withRows = markup as { inline_keyboard?: unknown[] } | undefined;
+	const rows = withRows?.inline_keyboard;
+	return Array.isArray(rows) && rows.length > 0;
+}
+
+/** install bot-message tracking on a mock `api` via its `after` hook. */
+export function attachBotMessageTracking(
+	api: Api,
+	resolveChatType: (chatId: number) => Chat["type"],
+): BotMessageTracker {
+	interface Entry extends BotMessage {
+		lastCall: { method: string; params: Record<string, unknown> | undefined };
+	}
+
+	const byKey = new Map<string, Entry>();
+	const order: Entry[] = [];
+	const key = (chatId: number, messageId: number): string => `${chatId}:${messageId}`;
+
+	api.after((method, params, result) => {
+		const p = params ?? {};
+
+		if (method.startsWith("edit")) {
+			const chatId = p.chat_id as number | undefined;
+			const messageId = p.message_id as number | undefined;
+			if (chatId === undefined || messageId === undefined) return;
+
+			const entry = byKey.get(key(chatId, messageId));
+			if (!entry) return;
+
+			if (method === "editMessageText" && typeof p.text === "string") entry.text = p.text;
+			if (method === "editMessageCaption") entry.caption = p.caption as string | undefined;
+			if ("reply_markup" in p) entry.reply_markup = p.reply_markup as ReplyMarkup | undefined;
+
+			entry.lastCall = { method, params: p };
+			return;
+		}
+
+		if (!SEND_LIKE(method)) return;
+		if (!result || typeof result !== "object" || !("message_id" in result)) return;
+
+		const chatId = p.chat_id as number | undefined;
+		if (chatId === undefined) return;
+
+		const messageId = (result as { message_id: number }).message_id;
+		const entry: Entry = {
+			message_id: messageId,
+			chat: { id: chatId, type: resolveChatType(chatId) },
+			text: p.text as string | undefined,
+			caption: p.caption as string | undefined,
+			reply_markup: p.reply_markup as ReplyMarkup | undefined,
+			date: (result as { date?: number }).date ?? Date.now(),
+			lastCall: { method, params: p },
+		};
+
+		byKey.set(key(chatId, messageId), entry);
+		order.push(entry);
+	});
+
+	return {
+		lastBotMessage(query = {}) {
+			for (let i = order.length - 1; i >= 0; i--) {
+				const entry = order[i] as Entry;
+				if (query.chat && entry.chat.id !== query.chat.id) continue;
+				if (query.withReplyMarkup && !hasInlineKeyboard(entry.reply_markup)) continue;
+				if (query.where && !query.where(entry.lastCall)) continue;
+
+				return entry;
+			}
+
+			return undefined;
+		},
+		botMessage: (chatId, messageId) => byKey.get(key(chatId, messageId)),
+		clear() {
+			byKey.clear();
+			order.length = 0;
+		},
+	};
+}

package/src/chat-actor.ts

@@ -0,0 +1,101 @@
+import type { Chat, Message } from "@yaebal/core";
+import type { ActorHost, SendText } from "./internal.js";
+import { resolveSendText } from "./internal.js";
+import { createUpdate } from "./updates.js";
+import type { UserActor } from "./user-actor.js";
+
+export type ChatType = "private" | "group" | "supergroup" | "channel";
+
+export interface CreateChatOptions {
+	type: ChatType;
+	id?: number;
+	title?: string;
+	username?: string;
+}
+
+/** a chat member's tracked status — set via {@link ChatActor.setMembership}. */
+export interface ChatMembership {
+	status: string;
+	since?: number;
+}
+
+let chatIdCounter = -1000;
+
+/**
+ * a passive container actors send into — a group/supergroup/channel/private chat. tracks who's
+ * currently a member (best-effort — nothing enforces it unless you opt into `strictMembership`
+ * via {@link createTestEnv}) and every message dispatched through it.
+ */
+export class ChatActor {
+	readonly id: number;
+	readonly type: ChatType;
+	readonly title?: string;
+	readonly username?: string;
+	readonly members = new Set<UserActor>();
+	readonly messages: unknown[] = [];
+
+	private readonly host: ActorHost;
+	private readonly membership = new Map<number, ChatMembership>();
+
+	constructor(host: ActorHost, options: CreateChatOptions) {
+		this.host = host;
+		this.id = options.id ?? chatIdCounter--;
+		this.type = options.type;
+		this.title = options.title;
+		this.username = options.username;
+	}
+
+	/** reconstruct a `ChatActor` from a raw `Chat` payload seen on an update (e.g. to find the chat a message you didn't create arrived in). not registered with any `TestEnv`. */
+	static fromChat(host: ActorHost, chat: Chat): ChatActor {
+		return new ChatActor(host, {
+			type: chat.type as ChatType,
+			id: chat.id,
+			title: chat.title,
+			username: chat.username,
+		});
+	}
+
+	/** this chat as a plain {@link Chat} payload, ready to embed in an update. */
+	toChat(): Chat {
+		return {
+			id: this.id,
+			type: this.type,
+			...(this.title !== undefined ? { title: this.title } : {}),
+			...(this.username !== undefined ? { username: this.username } : {}),
+		};
+	}
+
+	/** record (or update) a member's status — used by `strictMembership` and `getChatMember`-style assertions. */
+	setMembership(userId: number, membership: ChatMembership): void {
+		this.membership.set(userId, membership);
+	}
+
+	/** the tracked membership for a user, or `undefined` if never set. */
+	membershipOf(user: UserActor): ChatMembership | undefined {
+		return this.membership.get(user.id);
+	}
+
+	/**
+	 * an anonymous channel post — `update.channel_post`, with no `from` (matching real Telegram:
+	 * channel posts aren't attributed to a user). throws on non-channel chats.
+	 */
+	async post(text: SendText): Promise<Message> {
+		if (this.type !== "channel") {
+			throw new Error("ChatActor.post(): only channel chats can post — did you mean a user actor?");
+		}
+
+		const { text: resolvedText, entities } = resolveSendText(text);
+		const message = {
+			message_id: this.host.nextMessageId(),
+			date: this.host.now(),
+			chat: this.toChat(),
+			text: resolvedText,
+			...(entities.length ? { entities } : {}),
+		};
+
+		this.messages.push(message);
+		await this.host.dispatch(createUpdate({ channel_post: message }));
+
+		return message as Message;
+	}
+}

package/src/clock.test.ts

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { installTestClock } from "./clock.js";
+
+test("installTestClock overrides Date.now and advances on demand", async () => {
+	const clock = installTestClock(1_700_000_000_000);
+	try {
+		assert.equal(Date.now(), 1_700_000_000_000);
+		await clock.advance(5000);
+		assert.equal(Date.now(), 1_700_000_005_000);
+	} finally {
+		clock.restore();
+	}
+});
+
+test("advance() fires a setTimeout whose deadline falls inside the window", async () => {
+	const clock = installTestClock();
+	try {
+		let fired = false;
+		setTimeout(
+			() => {
+				fired = true;
+			},
+			60 * 60 * 1000,
+		);
+
+		await clock.advance(30 * 60 * 1000);
+		assert.equal(fired, false);
+
+		await clock.advance(30 * 60 * 1000);
+		assert.equal(fired, true);
+	} finally {
+		clock.restore();
+	}
+});
+
+test("advance() re-arms setInterval and may fire it multiple times", async () => {
+	const clock = installTestClock();
+	try {
+		let count = 0;
+		const id = setInterval(() => count++, 1000);
+
+		await clock.advance(3500);
+		assert.equal(count, 3);
+
+		clearInterval(id);
+		await clock.advance(10_000);
+		assert.equal(count, 3);
+	} finally {
+		clock.restore();
+	}
+});
+
+test("timers scheduled inside a firing callback are picked up by the same advance() call", async () => {
+	const clock = installTestClock();
+	try {
+		const seen: number[] = [];
+
+		setTimeout(() => {
+			seen.push(1);
+			setTimeout(() => seen.push(2), 100);
+		}, 100);
+
+		await clock.advance(500);
+		assert.deepEqual(seen, [1, 2]);
+	} finally {
+		clock.restore();
+	}
+});
+
+test("restore() puts back the real Date.now/setTimeout", () => {
+	const realNow = Date.now;
+	const realSetTimeout = setTimeout;
+
+	const clock = installTestClock();
+	clock.restore();
+
+	assert.equal(Date.now, realNow);
+	assert.equal(setTimeout, realSetTimeout);
+});

package/src/clock.ts

@@ -0,0 +1,118 @@
+/**
+ * a virtual clock: overrides `Date.now`, `setTimeout`/`clearTimeout`, and
+ * `setInterval`/`clearInterval` so TTL / retry-delay / debounce code under test
+ * can be advanced instantly instead of waited on for real. installs globally
+ * for the lifetime of the clock; always `.restore()` when done (or let
+ * {@link TestEnv.shutdown} do it for you).
+ */
+export interface TestClock {
+	/** the clock's current virtual time, in ms since epoch. */
+	now(): number;
+	/** advance the clock by `ms`, firing every timer whose deadline falls inside the window (in deadline order). intervals re-arm and may fire multiple times. */
+	advance(ms: number): Promise<void>;
+	/** uninstall — restores the real `Date.now`/`setTimeout`/`setInterval`. */
+	restore(): void;
+}
+
+interface Timer {
+	id: number;
+	due: number;
+	interval: number | undefined; // undefined = one-shot (setTimeout)
+	fn: (...args: unknown[]) => void;
+	args: unknown[];
+	cancelled: boolean;
+}
+
+/**
+ * install a virtual clock, overriding the global timer functions. `startAt`
+ * defaults to the real current time so unrelated `Date.now()` reads (e.g. log
+ * timestamps) stay plausible.
+ */
+export function installTestClock(startAt: number = Date.now()): TestClock {
+	const realDateNow = Date.now;
+	const realSetTimeout = globalThis.setTimeout;
+	const realClearTimeout = globalThis.clearTimeout;
+	const realSetInterval = globalThis.setInterval;
+	const realClearInterval = globalThis.clearInterval;
+
+	let now = startAt;
+	let nextId = 1;
+	const timers = new Map<number, Timer>();
+
+	const schedule = (
+		fn: (...args: unknown[]) => void,
+		delay: number,
+		interval: number | undefined,
+		args: unknown[],
+	): number => {
+		const id = nextId++;
+		timers.set(id, {
+			id,
+			due: now + Math.max(0, delay || 0),
+			interval,
+			fn,
+			args,
+			cancelled: false,
+		});
+		return id;
+	};
+
+	Date.now = () => now;
+
+	globalThis.setTimeout = ((fn: (...args: unknown[]) => void, delay?: number, ...args: unknown[]) =>
+		schedule(fn, delay ?? 0, undefined, args)) as unknown as typeof setTimeout;
+
+	globalThis.clearTimeout = ((id?: number | ReturnType<typeof setTimeout>) => {
+		if (typeof id === "number") timers.delete(id);
+	}) as unknown as typeof clearTimeout;
+
+	globalThis.setInterval = ((
+		fn: (...args: unknown[]) => void,
+		delay?: number,
+		...args: unknown[]
+	) => schedule(fn, delay ?? 0, delay ?? 0, args)) as unknown as typeof setInterval;
+
+	globalThis.clearInterval = ((id?: number | ReturnType<typeof setInterval>) => {
+		if (typeof id === "number") timers.delete(id);
+	}) as unknown as typeof clearInterval;
+
+	async function advance(ms: number): Promise<void> {
+		const target = now + ms;
+
+		for (;;) {
+			let next: Timer | undefined;
+
+			for (const timer of timers.values()) {
+				if (timer.due > target) continue;
+				if (!next || timer.due < next.due || (timer.due === next.due && timer.id < next.id)) {
+					next = timer;
+				}
+			}
+
+			if (!next) break;
+
+			now = next.due;
+
+			if (next.interval === undefined) {
+				timers.delete(next.id);
+			} else {
+				next.due = now + Math.max(1, next.interval);
+			}
+
+			await next.fn(...next.args);
+		}
+
+		now = target;
+	}
+
+	function restore(): void {
+		Date.now = realDateNow;
+		globalThis.setTimeout = realSetTimeout;
+		globalThis.clearTimeout = realClearTimeout;
+		globalThis.setInterval = realSetInterval;
+		globalThis.clearInterval = realClearInterval;
+		timers.clear();
+	}
+
+	return { now: () => now, advance, restore };
+}