Files
hyperframes/packages/engine/src/services/frameCapture-freshFallback.test.ts
T
Miguel Ángel 73e65e2c78 fix(engine): a background image that never finishes decoding no longer stalls the frame (#6972)
* fix(engine): a background image that never finishes decoding no longer stalls the frame

* fix(engine): capture tolerates a page that returns no list of late background images

* fix(engine): a background decode timeout is reported at every caller, url redacted

* fix(engine): a relative background url keeps only its path in the decode timeout report
2026-11-04 20:41:50 +00:00

280 lines
12 KiB
TypeScript

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();
});
}
// A 21-minute render died here: the worker's encode timeout reached the stage's drain as a plain Error, so
// the whole-render fresh-session recovery that every other drawElement failure gets never ran.
describe("a worker encode that fails after its frame was produced", () => {
const timedOut = (frame: number) =>
new Error(`drawElement worker encode timed out (frame ${frame})`);
it("rejects a pipelined frame as a drawElement capture failure naming the frame", async () => {
vi.mocked(produceDrawElementFrame).mockImplementationOnce(async () => ({
encodeResult: Promise.reject(timedOut(21847)),
}));
const { encodeResult } = await captureFrameToBufferPipelined(await session(), 7, 7 / 30);
const error = await encodeResult.catch((e: unknown) => e);
expect(error).toBeInstanceOf(DrawElementCaptureError);
expect(isDrawElementCaptureError(error)).toBe(true);
expect((error as DrawElementCaptureError).frameIndex).toBe(7);
expect((error as Error).message).toContain("worker encode timed out (frame 21847)");
});
it("rejects every frame of a batch the same way and keeps the frames that encoded", async () => {
vi.mocked(produceDrawElementFrameBatch).mockImplementationOnce(async () => ({
encodeResults: [Promise.resolve(Buffer.from("ok")), Promise.reject(timedOut(8))],
failedAt: null,
lateBackgrounds: [],
}));
const results = await captureFramesBatchPipelined(await session(), [7, 8], [7 / 30, 8 / 30]);
expect((await results[0]!.encodeResult).toString()).toBe("ok");
const error = await results[1]!.encodeResult.catch((e: unknown) => e);
expect(isDrawElementCaptureError(error)).toBe(true);
expect((error as DrawElementCaptureError).frameIndex).toBe(8);
});
});
// 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))
.mockResolvedValueOnce(Buffer.alloc(100, 1));
await expect(captureFrameToBuffer(await session(), 7, 7 / 30)).rejects.toThrow(
"suspect small frame",
);
expect(captureDrawElementFrame).toHaveBeenCalledTimes(2);
expect(pageScreenshotCapture).not.toHaveBeenCalled();
});
// GH #5685: segmented capture reaches only this guard. A flat frame is a small JPEG that redraws
// to the same bytes; the streaming drain guard keeps it, and this guard must keep it too.
describe("a small frame that redraws byte-identically", () => {
const flat = () => Buffer.alloc(13_000, 7);
afterEach(() => vi.mocked(captureDrawElementFrame).mockReset());
it("is kept, and the next identical frame is kept without a redraw", async () => {
vi.mocked(captureDrawElementFrame).mockImplementation(async () => flat());
const s = await session();
expect((await captureFrameToBuffer(s, 465, 465 / 30)).buffer.equals(flat())).toBe(true);
expect(captureDrawElementFrame).toHaveBeenCalledTimes(2);
expect((await captureFrameToBuffer(s, 466, 466 / 30)).buffer.equals(flat())).toBe(true);
expect(captureDrawElementFrame).toHaveBeenCalledTimes(3);
expect(pageScreenshotCapture).not.toHaveBeenCalled();
});
it("lowers the floor to half its size, so a similar flat frame is not redrawn", async () => {
const s = await session();
vi.mocked(captureDrawElementFrame).mockImplementation(async () => flat());
await captureFrameToBuffer(s, 465, 465 / 30);
expect(s.deAbsFloor).toBe(6_500);
vi.mocked(captureDrawElementFrame).mockClear();
vi.mocked(captureDrawElementFrame).mockResolvedValueOnce(Buffer.alloc(12_000, 3));
await captureFrameToBuffer(s, 466, 466 / 30);
expect(captureDrawElementFrame).toHaveBeenCalledTimes(1);
});
it("keeps a full-size redraw in place of a dropped small frame", async () => {
const full = Buffer.alloc(40_000, 9);
vi.mocked(captureDrawElementFrame)
.mockResolvedValueOnce(Buffer.alloc(100))
.mockResolvedValueOnce(full);
const s = await session();
expect((await captureFrameToBuffer(s, 7, 7 / 30)).buffer).toBe(full);
expect(s.deAcceptedSmall).toBeUndefined();
expect(s.deFrameSizes).toEqual([40_000]);
});
it("still throws under BeginFrame control, where a redraw reads the same snapshot", async () => {
vi.mocked(captureDrawElementFrame).mockImplementation(async () => flat());
const s = await session();
s.beginFrameTimeTicks = 1;
const send = vi.fn(async () => ({}));
Object.assign(s.page, {
createCDPSession: async () => ({ send, on: () => {}, off: () => {} }),
});
await expect(captureFrameToBuffer(s, 465, 465 / 30)).rejects.toThrow("suspect small frame");
expect(captureDrawElementFrame).toHaveBeenCalledTimes(1);
});
});
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,
lateBackgrounds: [],
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);
});
});