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 { existsSync, mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
captureFrameToBuffer,
captureFrameToBufferPipelined,
captureFramesBatchPipelined,
createCaptureSession,
} from "./frameCapture.js";
import {
captureDrawElementFrame,
produceDrawElementFrame,
produceDrawElementFrameBatch,
DE_CANVAS_NOT_INITIALIZED_CODE,
} from "./drawElementService.js";
import { pageScreenshotCapture } from "./screenshotService.js";
import { DrawElementCaptureError, isDrawElementCaptureError } from "./drawElementCaptureError.js";
vi.mock("./browserManager.js", async (importOriginal) => ({
...(await importOriginal<typeof import("./browserManager.js")>()),
resolveBrowserGpuMode: async () => "hardware",
acquireBrowser: async () => ({
captureMode: "screenshot",
browser: {
version: async () => "Chrome/150.0.0.0",
newPage: async () => ({
mainFrame: () => ({}),
evaluateOnNewDocument: async () => {},
setViewport: async () => {},
evaluate: async () => undefined,
screenshot: async () => {
throw new Error("diagnostic screenshot unavailable");
},
}),
},
}),
}));
vi.mock("./drawElementService.js", async (importOriginal) => ({
...(await importOriginal<typeof import("./drawElementService.js")>()),
captureDrawElementFrame: vi.fn(),
produceDrawElementFrame: vi.fn(),
produceDrawElementFrameBatch: vi.fn(),
}));
vi.mock("./screenshotService.js", async (importOriginal) => ({
...(await importOriginal<typeof import("./screenshotService.js")>()),
pageScreenshotCapture: vi.fn(),
}));
const dirs: string[] = [];
async function session() {
const dir = mkdtempSync(join(tmpdir(), "hf-fresh-fallback-"));
dirs.push(dir);
const result = await createCaptureSession(
"http://localhost:0",
dir,
{
width: 1920,
height: 1080,
fps: { num: 30, den: 1 },
format: "jpeg",
},
null,
{ forceScreenshot: true },
);
result.isInitialized = true;
result.captureMode = "drawelement";
return result;
}
beforeEach(() => {
vi.clearAllMocks();
vi.stubEnv("HF_FORCE_DRAWELEMENT", "0");
vi.stubEnv("HF_FAST_CAPTURE_BOUNDARY_SS", "false");
});
afterEach(() => {
vi.unstubAllEnvs();
for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
});
describe("fresh screenshot fallback", () => {
for (const [name, capture, produce] of [
["serial", captureFrameToBuffer, captureDrawElementFrame],
["pipelined", captureFrameToBufferPipelined, produceDrawElementFrame],
] as const) {
it.each(["No cached paint record for element", DE_CANVAS_NOT_INITIALIZED_CODE])(
`${name} rejects untrusted capture instead of returning the injected canvas`,
async (message) => {
vi.mocked(produce).mockRejectedValueOnce(new Error(message));
const s = await session();
await expect(capture(s, 7, 7 / 30)).rejects.toBeInstanceOf(DrawElementCaptureError);
expect(pageScreenshotCapture).not.toHaveBeenCalled();
expect(s.deNcprFallbacks).toBe(1);
},
);
it(`${name} routes explicit boundary screenshots through a fresh page`, async () => {
vi.stubEnv("HF_FAST_CAPTURE_BOUNDARY_SS", "true");
const s = await session();
s.clipBoundaryFrames = new Set([7]);
await expect(capture(s, 7, 7 / 30)).rejects.toThrow("boundary screenshot requested");
expect(pageScreenshotCapture).not.toHaveBeenCalled();
expect(produce).not.toHaveBeenCalled();
});
}
// The recoverable-error wrapper used to throw before the diagnostics call,
// so exactly the NCPR/canvas failures worth debugging produced no bundle.
it("still writes per-frame diagnostics when a recoverable pipelined failure aborts the attempt", async () => {
vi.mocked(produceDrawElementFrame).mockRejectedValueOnce(
new Error("No cached paint record for element"),
);
const s = await session();
// The shared mock page fails its diagnostic screenshot; give this one a
// working page so the bundle can actually land on disk.
Object.assign(s.page, {
screenshot: async () => Buffer.alloc(0),
content: async () => "<html></html>",
});
await expect(captureFrameToBufferPipelined(s, 7, 7 / 30)).rejects.toBeInstanceOf(
DrawElementCaptureError,
);
expect(existsSync(join(s.outputDir, "diagnostics", "frame-error-7.json"))).toBe(true);
});
// A BeginFrame page paints only when the engine sends a frame, so a diagnostic
// page.screenshot never resolves there and held the real error until the stall watchdog.
it.each(["beginframe", "drawelement"] as const)(
"rejects a %s capture failure on a BeginFrame launch with its own error, without a page screenshot",
async (captureMode) => {
const s = await session();
s.launchCaptureMode = "beginframe";
s.captureMode = captureMode;
s.onBeforeCapture = async () => {
throw new Error('Video frame for "clip" failed to load (inline frame)');
};
const screenshot = vi.fn(() => new Promise<Buffer>(() => {}));
Object.assign(s.page, { screenshot, content: async () => "<html></html>" });
await expect(captureFrameToBuffer(s, 7, 7 / 30)).rejects.toThrow(
'Video frame for "clip" failed to load',
);
expect(screenshot).not.toHaveBeenCalled();
expect(existsSync(join(s.outputDir, "diagnostics", "frame-error-7.json"))).toBe(true);
},
);
it("rejects a suspect tiny frame without substituting a stale screenshot", async () => {
vi.mocked(captureDrawElementFrame).mockResolvedValueOnce(Buffer.alloc(100));
await expect(captureFrameToBuffer(await session(), 7, 7 / 30)).rejects.toThrow(
"suspect small frame",
);
expect(pageScreenshotCapture).not.toHaveBeenCalled();
});
it("returns a normal drawElement frame unchanged", async () => {
const buffer = Buffer.alloc(30_000);
vi.mocked(captureDrawElementFrame).mockResolvedValueOnce(buffer);
expect((await captureFrameToBuffer(await session(), 7, 7 / 30)).buffer).toBe(buffer);
expect(pageScreenshotCapture).not.toHaveBeenCalled();
});
it.each(["No cached paint record for element", DE_CANVAS_NOT_INITIALIZED_CODE])(
"rejects a failed batch and safely abandons pending prefix encodes",
async (error) => {
let rejectPrefix: (error: Error) => void = () => {};
const prefix = new Promise<Buffer>((_, reject) => {
rejectPrefix = reject;
});
vi.mocked(produceDrawElementFrameBatch).mockResolvedValueOnce({
encodeResults: [prefix],
failedAt: 1,
error,
});
await expect(
captureFramesBatchPipelined(await session(), [6, 7], [6 / 30, 7 / 30]),
).rejects.toThrow("frame 7");
rejectPrefix(new Error("worker closed during fallback"));
await new Promise<void>((resolve) => setImmediate(resolve));
expect(pageScreenshotCapture).not.toHaveBeenCalled();
expect(produceDrawElementFrame).not.toHaveBeenCalled();
},
);
it("recognizes wrapped structural errors without misclassifying generic failures", () => {
expect(isDrawElementCaptureError({ cause: { cause: { deCaptureFailure: true } } })).toBe(true);
expect(isDrawElementCaptureError(new Error("No cached paint record for element"))).toBe(false);
const cycle: { cause?: unknown } = {};
cycle.cause = cycle;
expect(isDrawElementCaptureError(cycle)).toBe(false);
});
});