Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { afterEach, describe, expect, it, vi } from "vitest";
import {
lstatSync,
mkdirSync,
mkdtempSync,
readFileSync,
rmSync,
symlinkSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { CliRuntimeError, registerRootExitRequester } from "../utils/commandResult.js";
import { CAPTURE_PHASE_SCHEMA } from "../capture/types.js";
const { captureWebsiteMock } = vi.hoisted(() => ({
captureWebsiteMock: vi.fn(async (options: unknown) => {
if (typeof options === "object" && options !== null) {
const onPhase = Reflect.get(options, "onPhase");
if (typeof onPhase === "function") {
onPhase({
schema: CAPTURE_PHASE_SCHEMA,
phase: "vision",
status: "degraded",
remainingMs: 0,
reason: "budget-exhausted",
});
}
}
return {
ok: true,
projectDir: "/tmp/capture",
url: "https://example.com",
title: "Example",
extracted: {},
screenshots: [],
tokens: { sections: [], fonts: [] },
assets: [],
warnings: [] as string[],
};
}),
}));
vi.mock("../capture/index.js", () => ({ captureWebsite: captureWebsiteMock }));
import captureCommand from "./capture.js";
describe("capture command — vision control", () => {
afterEach(() => {
captureWebsiteMock.mockClear();
vi.restoreAllMocks();
});
it("declares --skip-vision as an opt-in boolean", () => {
const skipVisionArg = captureCommand.args
? Reflect.get(captureCommand.args, "skip-vision")
: undefined;
expect(skipVisionArg).toMatchObject({
type: "boolean",
default: false,
});
});
it("declares --capture-budget separately from navigation --timeout", () => {
const captureBudgetArg = captureCommand.args
? Reflect.get(captureCommand.args, "capture-budget")
: undefined;
expect(captureBudgetArg).toMatchObject({ type: "string" });
const description = captureBudgetArg?.description.toLowerCase();
expect(description).toContain("post-navigation");
expect(description).toContain("cooperative");
expect(description).toContain("not a hard wall-clock timeout");
expect(description).toContain("already-started native/core work");
expect(captureBudgetArg?.description).toContain("--timeout");
});
it("plumbs --skip-vision into capture options", async () => {
vi.spyOn(console, "log").mockImplementation(() => {});
vi.spyOn(console, "error").mockImplementation(() => {});
await captureCommand.run!({
args: {
url: "https://example.com",
output: "/tmp/hf-skip-vision-test",
"skip-assets": false,
"skip-vision": true,
json: true,
},
} as never);
expect(captureWebsiteMock).toHaveBeenCalledWith(
expect.objectContaining({ skipVision: true }),
undefined,
);
});
it("plumbs the optional whole-capture deadline from the environment", async () => {
vi.spyOn(console, "log").mockImplementation(() => {});
vi.spyOn(console, "error").mockImplementation(() => {});
process.env.HYPERFRAMES_CAPTURE_DEADLINE_MS = "240000";
try {
await captureCommand.run!({
args: {
url: "https://example.com",
output: "/tmp/hf-capture-deadline-test",
"skip-assets": false,
"skip-vision": false,
json: true,
},
} as never);
expect(captureWebsiteMock).toHaveBeenCalledWith(
expect.objectContaining({ captureDeadlineMs: 240_000 }),
undefined,
);
} finally {
delete process.env.HYPERFRAMES_CAPTURE_DEADLINE_MS;
}
});
it.each([
["1", 1],
["45000", 45_000],
])(
"plumbs positive integer --capture-budget %s into the post-navigation budget",
async (captureBudget, expectedBudget) => {
vi.spyOn(console, "log").mockImplementation(() => {});
vi.spyOn(console, "error").mockImplementation(() => {});
await captureCommand.run!({
args: {
url: "https://example.com",
output: "/tmp/hf-capture-budget-test",
"skip-assets": false,
"skip-vision": false,
"capture-budget": captureBudget,
json: true,
},
} as never);
expect(captureWebsiteMock).toHaveBeenCalledWith(
expect.objectContaining({ postNavigationBudgetMs: expectedBudget }),
undefined,
);
},
);
it.each(["0", "-1", "0.5", "Infinity", "not-a-number"])(
"rejects invalid --capture-budget %s before capture starts",
async (captureBudget) => {
vi.spyOn(console, "log").mockImplementation(() => {});
vi.spyOn(console, "error").mockImplementation(() => {});
await expect(
captureCommand.run!({
args: {
url: "https://example.com",
output: "/tmp/hf-invalid-capture-budget-test",
"skip-assets": false,
"skip-vision": false,
"capture-budget": captureBudget,
json: true,
},
} as never),
).rejects.toBeInstanceOf(CliRuntimeError);
expect(captureWebsiteMock).not.toHaveBeenCalled();
},
);
it.each(["0", "-1", "1.5", "3junk", "", "Infinity"])(
"rejects invalid --max-screenshots %s before capture starts",
async (value) => {
vi.spyOn(console, "log").mockImplementation(() => {});
const error = vi.spyOn(console, "error").mockImplementation(() => {});
await expect(
captureCommand.run!({
args: {
url: "https://example.com",
output: "/tmp/hf-invalid-count",
"max-screenshots": value,
json: true,
},
} as never),
).rejects.toBeInstanceOf(CliRuntimeError);
expect(error).toHaveBeenCalledWith("--max-screenshots must be a positive integer.");
expect(captureWebsiteMock).not.toHaveBeenCalled();
},
);
it("passes a validated screenshot limit into capture", async () => {
vi.spyOn(console, "log").mockImplementation(() => {});
await captureCommand.run!({
args: {
url: "https://example.com",
output: "/tmp/hf-count",
"max-screenshots": "3",
json: true,
},
} as never);
expect(captureWebsiteMock).toHaveBeenCalledWith(
expect.objectContaining({ maxScreenshots: 3 }),
undefined,
);
});
it.each([
[true, 0],
[false, 1],
])("asks to end the process once its result is out (ok %s)", async (ok, exitCode) => {
vi.useFakeTimers();
const exit = vi.fn();
registerRootExitRequester(exit);
try {
vi.spyOn(console, "log").mockImplementation(() => {});
vi.spyOn(console, "error").mockImplementation(() => {});
captureWebsiteMock.mockResolvedValueOnce({
ok,
projectDir: "/tmp/capture",
url: "https://example.com",
title: "Example",
extracted: {},
screenshots: [],
tokens: { sections: [], fonts: [] },
assets: [],
warnings: [],
});
await captureCommand.run!({
args: { url: "https://example.com", output: "/tmp/hf-exit", json: true },
} as never).catch(() => {});
expect(exit).not.toHaveBeenCalled();
vi.advanceTimersByTime(100);
expect(exit).toHaveBeenCalledWith(exitCode);
} finally {
registerRootExitRequester(() => {});
vi.useRealTimers();
}
});
it("asks to end the process with 1 after a capture that threw", async () => {
vi.useFakeTimers();
const exit = vi.fn();
registerRootExitRequester(exit);
try {
vi.spyOn(console, "log").mockImplementation(() => {});
vi.spyOn(console, "error").mockImplementation(() => {});
captureWebsiteMock.mockRejectedValueOnce(new Error("browser crashed"));
await captureCommand.run!({
args: { url: "https://example.com", output: "/tmp/hf-exit-threw", json: true },
} as never).catch(() => {});
vi.advanceTimersByTime(100);
expect(exit).toHaveBeenCalledWith(1);
} finally {
registerRootExitRequester(() => {});
vi.useRealTimers();
}
});
it("returns a nonzero command result after presenting failed capture JSON once", async () => {
const log = vi.spyOn(console, "log").mockImplementation(() => {});
vi.spyOn(console, "error").mockImplementation(() => {});
captureWebsiteMock.mockResolvedValueOnce({
ok: false,
projectDir: "/tmp/capture",
url: "https://example.com",
title: "Example",
extracted: {},
screenshots: [],
tokens: { sections: [], fonts: [] },
assets: [],
warnings: [
"0/3 requested screenshot files captured: --capture-budget exhausted during lazy scrolling",
],
});
await expect(
captureCommand.run!({
args: {
url: "https://example.com",
output: "/tmp/hf-failed-capture",
json: true,
},
} as never),
).rejects.toMatchObject({ result: { exitCode: 1 } });
expect(log).toHaveBeenCalledTimes(1);
expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toMatchObject({ ok: false, screenshots: 0 });
});
it("emits a versioned phase record without the captured URL", async () => {
vi.spyOn(console, "log").mockImplementation(() => {});
const error = vi.spyOn(console, "error").mockImplementation(() => {});
await captureCommand.run!({
args: {
url: "https://user:[email protected]/private",
output: "/tmp/hf-phase-progress-test",
"skip-assets": false,
"skip-vision": false,
json: true,
},
} as never);
const line = error.mock.calls.find(
([value]) => typeof value === "string" && value.startsWith("HYPERFRAMES_CAPTURE_PHASE "),
)?.[0];
expect(typeof line).toBe("string");
if (typeof line !== "string") throw new Error("Expected capture phase diagnostic");
const event = JSON.parse(line.slice("HYPERFRAMES_CAPTURE_PHASE ".length));
expect(event).toEqual({
schema: CAPTURE_PHASE_SCHEMA,
phase: "vision",
status: "degraded",
remainingMs: 0,
reason: "budget-exhausted",
});
expect(line).not.toContain("secret");
expect(line).not.toContain("/private");
});
it("keeps required capture failures nonzero", async () => {
const dir = mkdtempSync(join(tmpdir(), "hf-capture-failure-"));
const log = vi.spyOn(console, "log").mockImplementation(() => {});
vi.spyOn(console, "error").mockImplementation(() => {});
captureWebsiteMock.mockRejectedValueOnce(new Error("required extraction failed"));
try {
await expect(
captureCommand.run!({
args: {
url: "https://example.com",
output: dir,
"skip-assets": false,
"skip-vision": false,
json: true,
},
} as never),
).rejects.toBeInstanceOf(CliRuntimeError);
const payload = log.mock.calls.at(-1)?.[0];
expect(typeof payload).toBe("string");
if (typeof payload !== "string") throw new Error("Expected JSON failure payload");
expect(JSON.parse(payload)).toMatchObject({ ok: false, error: "required extraction failed" });
} finally {
rmSync(dir, { recursive: true, force: true });
}
});
it.skipIf(process.platform === "win32")(
"writes BLOCKED.md without following a pre-planted symlink",
async () => {
const root = mkdtempSync(join(tmpdir(), "hf-capture-blocked-"));
const dir = join(root, "capture");
const victim = join(root, "victim.txt");
mkdirSync(dir);
writeFileSync(victim, "do not touch");
symlinkSync(victim, join(dir, "BLOCKED.md"));
vi.spyOn(console, "log").mockImplementation(() => {});
vi.spyOn(console, "error").mockImplementation(() => {});
captureWebsiteMock.mockRejectedValueOnce(new Error("blocked by the site"));
try {
await expect(
captureCommand.run!({
args: { url: "https://example.com", output: dir, json: true },
} as never),
).rejects.toBeInstanceOf(CliRuntimeError);
expect(readFileSync(victim, "utf8")).toBe("do not touch");
expect(readFileSync(join(dir, "BLOCKED.md"), "utf8")).toContain("# Capture Failed");
expect(lstatSync(join(dir, "BLOCKED.md")).isSymbolicLink()).toBe(false);
} finally {
rmSync(root, { recursive: true, force: true });
}
},
);
});