Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import type { Page } from "puppeteer-core";
import type { CaptureSession } from "./frameCapture.js";
import { pollSubCompositionTimelines, recordSubTimelineWarning } from "./frameCapture.js";
function makeSession(overrides: Partial<CaptureSession> = {}): CaptureSession {
return {
scriptLoadFailures: [],
pageErrors: [],
warnings: [],
...overrides,
} as unknown as CaptureSession;
}
describe("recordSubTimelineWarning", () => {
beforeEach(() => {
vi.spyOn(console, "warn").mockImplementation(() => {});
});
afterEach(() => {
vi.restoreAllMocks();
});
it("records nothing when the wait succeeded or never ran", () => {
for (const outcome of ["ready", undefined] as const) {
const session = makeSession({ subTimelineWaitOutcome: outcome });
recordSubTimelineWarning(session, 45_000);
expect(session.warnings).toEqual([]);
}
});
// The remedy used to live only in the stderr line inside the poll. A caller
// reading the structured `warnings` (the render summary, the JSON result)
// got the symptom with no way to act on it.
it("names the data-no-timeline remedy on a timeout", () => {
const session = makeSession({ subTimelineWaitOutcome: "timeout" });
recordSubTimelineWarning(session, 45_000);
expect(session.warnings).toHaveLength(1);
const [warning] = session.warnings;
expect(warning.code).toBe("sub_timeline_readiness_timeout");
expect(warning.message).toContain("45000ms");
expect(warning.message).toContain("data-no-timeline");
expect(warning.message).toContain("window.__timelines[id]");
// Miao's ask: the author must learn the wait can be theirs to switch off,
// not only that something timed out.
expect(warning.message).toContain("can be intentional");
expect(warning.details).toMatchObject({ timeoutMs: 45_000, pendingCompositionIds: [] });
});
it("names the still-unregistered composition ids when the poll reported them", () => {
const session = makeSession({
subTimelineWaitOutcome: "timeout",
pendingTimelineIds: ["scene-2", "scene-5"],
});
recordSubTimelineWarning(session, 45_000);
const [warning] = session.warnings;
expect(warning.message).toContain("still unregistered: scene-2, scene-5");
expect(warning.details).toMatchObject({ pendingCompositionIds: ["scene-2", "scene-5"] });
});
// An empty list must not print an empty parenthetical.
it("omits the id clause when no ids were reported", () => {
const session = makeSession({ subTimelineWaitOutcome: "timeout", pendingTimelineIds: [] });
recordSubTimelineWarning(session, 45_000);
expect(session.warnings[0].message).not.toContain("still unregistered");
});
// The script-failure branch is a different diagnosis: the timeline can never
// arrive, so data-no-timeline is the wrong advice there.
it("leaves the script-failure branch alone", () => {
const session = makeSession({
subTimelineWaitOutcome: "script_failure",
scriptLoadFailures: ["https://example.test/scene.js"],
pendingTimelineIds: ["scene-2"],
});
recordSubTimelineWarning(session, 45_000);
const [warning] = session.warnings;
expect(warning.code).toBe("sub_timeline_script_failure");
expect(warning.message).toContain("https://example.test/scene.js");
expect(warning.message).not.toContain("data-no-timeline");
});
it("turns a timeout with an uncaught page error into a script failure naming data-no-timeline", () => {
const session = makeSession({
subTimelineWaitOutcome: "timeout",
pageErrors: ["runtime-error:ReferenceError: gsap is not defined"],
});
recordSubTimelineWarning(session, 45_000);
expect(session.subTimelineWaitOutcome).toBe("timeout");
const [warning] = session.warnings;
expect(warning.code).toBe("sub_timeline_script_failure");
expect(warning.message).toContain("ReferenceError: gsap is not defined");
expect(warning.message).toContain("data-no-timeline");
expect(warning.details).toMatchObject({
sources: ["runtime-error:ReferenceError: gsap is not defined"],
});
});
it("names the missing script, not the error it caused, when both are present", () => {
const session = makeSession({
subTimelineWaitOutcome: "script_failure",
scriptLoadFailures: ["https://example.test/gsap.js"],
pageErrors: ["runtime-error:ReferenceError: gsap is not defined"],
});
recordSubTimelineWarning(session, 45_000);
expect(session.warnings[0].message).toContain("failed to load");
});
it("names an integrity-blocked script as one that failed to load", () => {
const session = makeSession({
subTimelineWaitOutcome: "script_failure",
scriptLoadFailures: ["runtime-error:subresource-integrity"],
});
recordSubTimelineWarning(session, 45_000);
expect(session.warnings[0].message).toContain("failed to load");
});
// An unrelated error on a page whose timelines did register must not fail the render.
it("ignores an uncaught page error when the timelines registered", () => {
const session = makeSession({
subTimelineWaitOutcome: "ready",
pageErrors: ["runtime-error:Error: third-party widget failed"],
});
recordSubTimelineWarning(session, 45_000);
expect(session.subTimelineWaitOutcome).toBe("ready");
expect(session.warnings).toEqual([]);
});
});
// The warning text is only as good as the ids handed to it, and that handoff
// lives in the poll, not in recordSubTimelineWarning. CI caught a TypeError
// here that this file could not see: the enumerate step used to cast
// page.evaluate's result with `as string[]`, so any caller whose evaluate did
// not return an array crashed the DIAGNOSTIC path.
describe("pollSubCompositionTimelines pending-id reporting", () => {
beforeEach(() => {
vi.spyOn(console, "warn").mockImplementation(() => {});
});
afterEach(() => {
vi.restoreAllMocks();
});
// `data-composition-id` appears in the READINESS expression too, so a stub
// keyed on it answers the readiness poll with the enumerate payload and the
// poll returns "ready" before it ever enumerates. `m.push(` is unique to the
// enumerate step. `matched` then asserts the stub was really reached, so a
// later edit to that expression fails loudly instead of testing nothing.
function pageReturning(enumerateResult: unknown) {
const matched = { count: 0 };
const page = {
evaluate: vi.fn(async (expr: string) => {
if (!expr.includes("m.push(")) return false;
matched.count++;
return enumerateResult;
}),
} as unknown as Page;
return { page, matched };
}
it("reports the still-unregistered ids to onPending", async () => {
const seen: string[][] = [];
const probe = pageReturning(["scene-2", "scene-5"]);
const outcome = await pollSubCompositionTimelines(probe.page, 60, {
intervalMs: 10,
getScriptLoadFailures: () => [],
onPending: (ids) => seen.push([...ids]),
});
expect(outcome).toBe("timeout");
expect(seen).toEqual([["scene-2", "scene-5"]]);
expect(probe.matched.count).toBeGreaterThan(0);
});
// `false` is what a blanket evaluate stub returns, and it is what CI hit: the
// enumerate result used to be cast with `as string[]`, so a non-array threw a
// TypeError on the very path that exists to report a problem.
it("degrades to no ids instead of throwing when the page returns a non-array", async () => {
const seen: string[][] = [];
const probe = pageReturning(false);
const outcome = await pollSubCompositionTimelines(probe.page, 60, {
intervalMs: 10,
getScriptLoadFailures: () => [],
onPending: (ids) => seen.push([...ids]),
});
expect(outcome).toBe("timeout");
expect(seen).toEqual([[]]);
expect(probe.matched.count).toBeGreaterThan(0);
});
});