Testing API reference

Assert a roundtrip decoded `ok` and reconstructed a payload deep-equal to `expected`. Throws a descriptive `Error` on any other decode outcome or a value mismatch.

<TPayload extends Record<string, unknown>>(roundtrip: CallbackRoundtrip<TPayload>, expected: TPayload): void

Assert one payload survives the COMPACT path and another survives the SPILLOVER (pointer) path — both decoding `ok` and equal to their input. The caller supplies a small payload known to fit inline and a large payload known to overflow the 64-byte budget; this proves both codec branches are lossless. A mis-sized payload (compact that spills, or spillover that fits) throws, surfacing the test's wrong assumption rather than passing silently.

<TPayload extends Record<string, unknown>, TActions extends Record<string, AnyActionDef>>(namespace: CallbackNamespace<TActions>, actionKey: keyof TActions & string, payloads: { readonly compact: TPayload; readonly spillover: TPayload; }, deps: CallbackTestDeps): Promise<void>

Classify a `callback_data` string by its version prefix.

callbackWireFormat(callbackData: string): CallbackWireFormat

Build a deterministic {@link CallbackTestDeps}: fresh fake store + fixed secret + fixed clock + default TTL. Any field can be overridden.

createCallbackTestDeps(overrides?: Partial<CallbackTestDeps>): CallbackTestDeps

Create a fresh in-memory {@link FakePointerStore}.

createFakePointerStore(): FakePointerStore

Human-readable one-line description of any decode result (exhaustive).

<TPayload>(result: CallbackDecodeResult<TPayload>): string

A constant clock returning `ms` (defaults to {@link FIXED_NOW_MS}).

fixedNow(ms?: number): () => number

Recursive structural equality over JSON values (key-order-insensitive).

jsonDeepEqual(a: unknown, b: unknown): boolean

Encode `payload` for `actionKey` in `namespace`, then decode the resulting `callback_data` back — returning the wire string, the format it used, and the `CallbackDecodeResult` for assertion.

<TPayload extends Record<string, unknown>, TActions extends Record<string, AnyActionDef>>(namespace: CallbackNamespace<TActions>, actionKey: keyof TActions & string, payload: TPayload, deps: CallbackTestDeps): Promise<CallbackRoundtrip<TPayload>>

Derive the decode-side deps (single-secret list) from the test deps.

toDecodeDeps(deps: CallbackTestDeps): CallbackDecodeDeps

Snapshot the DEFAULT `{ text, entities }` render of a message, with entities sorted into a stable order. Prefer this over snapshotting `toEntities` directly so snapshots don't churn on walk-order changes.

snapshotEntities(message: MessageText | CaptionText): EntitiesSnapshot

Snapshot the Telegram-HTML render of a message (a stable string).

snapshotHtml(message: MessageText | CaptionText): string

Snapshot the MarkdownV2 (fallback) render of a message (a stable string).

snapshotMarkdown(message: MessageText | CaptionText): string

Assert the UTF-16 rendered length of `nodes` equals `expected`. Throws a descriptive `Error` on mismatch (framework-agnostic — no vitest import), so it works under any runner or a bare `node`.

assertUtf16Length(nodes: readonly RichTextNode[], expected: number): void

Wrap a fixture's raw string in a single text node for renderer input.

fixtureNodes(fixture: UnicodeFixture): readonly RichTextNode[]

The Unicode fixture bank (function form, for parameterized-test ergonomics).

unicodeFixtures(): readonly UnicodeFixture[]

The combined encode-side deps a roundtrip needs. Structurally identical to core's `CallbackEncodeDeps`; {@link toDecodeDeps} derives the decode-side shape (a single-secret list) from it.

type CallbackTestDeps = CallbackEncodeDeps

Which of the codec's two wire formats a `callback_data` string uses.

type CallbackWireFormat = "compact" | "pointer" | "unknown"

The full result of encoding then decoding a payload.

interface CallbackRoundtrip

callbackData: string

wireFormat: CallbackWireFormat

result: CallbackDecodeResult<TPayload>

An in-memory {@link PointerStore} with test-only inspection (`size`, `has`). Non-durable, non-evicting — the same caveats as core's in-memory store.

interface FakePointerStore

size: () => number

has: (token: CallbackToken) => boolean

A stable, JSON-serializable projection of `toEntities` output.

interface EntitiesSnapshot

text: string

entities: readonly MessageEntity[]

A single Unicode edge case with its documented lengths in both units.

interface UnicodeFixture

label: string

text: string

utf16Length: number

codePointLength: number

const moduleId: "testing"

Default pointer TTL used by {@link createCallbackTestDeps} (24h).

const DEFAULT_CALLBACK_TTL_MS: number

A fixed 32-byte HMAC secret — deterministic pointer signatures across runs.

const FIXED_HMAC_SECRET: Uint8Array<ArrayBufferLike>

A fixed wall-clock instant (epoch ms) for reproducible TTL/expiry tests.

const FIXED_NOW_MS: number

A cross-section of Unicode length hazards: plain ASCII, BMP CJK, an astral emoji (surrogate pair), an emoji + skin-tone modifier, a ZWJ family sequence, decomposed combining marks, and a regional-indicator flag pair.

const UNICODE_FIXTURES: readonly UnicodeFixture[]