Files
hyperframes/packages/cli/src/commands/capture.test.ts
T
Stephanie 50c21c355a fix(cli): parse capture and grade-compare --timeout as a duration (#7715)
capture read --timeout with parseInt, so `--timeout 1s` became a 1 ms
page-load timeout. grade-compare dropped an invalid value without a
warning. Both now use the shared parseTimeoutMs helper that check and
snapshot already use, keeping their defaults of 120000 ms and 5000 ms.

Fixes #7671
2026-11-14 04:30:52 +00:00

458 lines
15 KiB
TypeScript

import { afterEach, describe, expect, it, vi } from "vitest";
import {
lstatSync,
mkdirSync,
mkdtempSync,
realpathSync,
readFileSync,
rmSync,
symlinkSync,
writeFileSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { pathToFileURL } from "node:url";
import {
CliRuntimeError,
CliUsageError,
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(CliUsageError);
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(CliUsageError);
expect(error).toHaveBeenCalledWith("--max-screenshots must be a positive integer.");
expect(captureWebsiteMock).not.toHaveBeenCalled();
},
);
it("passes a local HTML file and its root into capture", async () => {
vi.spyOn(console, "log").mockImplementation(() => {});
const site = mkdtempSync(join(tmpdir(), "hf-capture-local-cmd-"));
try {
mkdirSync(join(site, "pages"));
writeFileSync(join(site, "pages", "about.html"), "<h1>about</h1>");
await captureCommand.run!({
args: {
"local-file": join(site, "pages", "about.html"),
"local-root": site,
output: "/tmp/hf-local-cmd",
json: true,
},
} as never);
expect(captureWebsiteMock).toHaveBeenCalledWith(
expect.objectContaining({
url: pathToFileURL(realpathSync.native(join(site, "pages", "about.html"))).href,
localFile: join(site, "pages", "about.html"),
localRoot: site,
}),
undefined,
);
} finally {
rmSync(site, { recursive: true, force: true });
}
});
it.each([
[{ "local-file": "/definitely/missing/page.html" }, "Local file not found"],
[{ url: "https://example.com", "local-file": "/tmp" }, "either a URL or --local-file"],
[{ url: "https://example.com", "local-root": "/tmp" }, "--local-root requires --local-file"],
])("refuses %o before capturing", async (target, message) => {
const error = vi.spyOn(console, "error").mockImplementation(() => {});
await expect(
captureCommand.run!({
args: { ...target, output: "/tmp/hf-local-refused", json: true },
} as never),
).rejects.toThrow("url" in target ? CliUsageError : CliRuntimeError);
expect(error.mock.calls.flat().join("\n")).toContain(message);
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([
["1s", 1_000],
["2m", 120_000],
["45000", 45_000],
[undefined, 120_000],
])("passes --timeout %s into capture as %i ms", async (timeout, expectedMs) => {
vi.spyOn(console, "log").mockImplementation(() => {});
await captureCommand.run!({
args: { url: "https://example.com", output: "/tmp/hf-timeout", timeout, json: true },
} as never);
expect(captureWebsiteMock).toHaveBeenCalledWith(
expect.objectContaining({ timeout: expectedMs }),
undefined,
);
});
it("warns and keeps the default page-load timeout when --timeout is not a duration", async () => {
vi.spyOn(console, "log").mockImplementation(() => {});
const error = vi.spyOn(console, "error").mockImplementation(() => {});
await captureCommand.run!({
args: { url: "https://example.com", output: "/tmp/hf-timeout", timeout: "abc", json: true },
} as never);
expect(captureWebsiteMock).toHaveBeenCalledWith(
expect.objectContaining({ timeout: 120_000 }),
undefined,
);
expect(error).toHaveBeenCalledWith(
expect.stringContaining('--timeout "abc" is not a duration'),
);
});
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:secret@example.com/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: expect.objectContaining({ message: "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 });
}
},
);
});