From 50c21c355aa2e2b5b5e8f203d4c38ce0bde6e6a3 Mon Sep 17 00:00:00 2001 From: Stephanie Date: Sat, 14 Nov 2026 04:30:52 +0000 Subject: [PATCH] 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 --- docs/packages/cli.mdx | 4 +-- packages/cli/src/commands/capture.test.ts | 31 +++++++++++++++++++ packages/cli/src/commands/capture.ts | 7 +++-- .../cli/src/commands/grade-compare.test.ts | 27 ++++++++++++++++ packages/cli/src/commands/grade-compare.ts | 7 +++-- 5 files changed, 70 insertions(+), 6 deletions(-) diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index fad6ea4bd2..092ea058ce 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -363,7 +363,7 @@ thin with counts on it was cut short. | Flag | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `--output, -o` | Output directory. Default `./capture`, then `./capture-2/`, `./capture-3/`, … if that name is taken. | -| `--timeout` | Page load timeout in ms (default 120000) | +| `--timeout` | Page load timeout in ms, or a duration such as `30s` or `2m` (default 120000) | | `--capture-budget` | Budget in ms for everything after the page loads (default 120000). Cooperative — it stops new work, but cannot interrupt work already running. | | `--skip-assets` | Do not download images and SVGs | | `--skip-vision` | Do not run AI image captioning | @@ -1588,7 +1588,7 @@ npx hyperframes grade-compare --for frame.png --luts warm.cube,cool.cube | `--project` | Base directory for relative paths | | `--out` | Output PNG (default `/grade-compare.png`) | | `--baseline` / `--no-baseline` | Include the ungraded frame as an `original` cell (on) | -| `--timeout` | Render-ready timeout (default 5000 ms) | +| `--timeout` | Render-ready timeout in ms, or a duration such as `30s` (default 5000 ms) | | `--json` | Machine-readable results | ### Deprecated: `validate`, `inspect`, and `layout` diff --git a/packages/cli/src/commands/capture.test.ts b/packages/cli/src/commands/capture.test.ts index 16ee6307cf..81c83f02c6 100644 --- a/packages/cli/src/commands/capture.test.ts +++ b/packages/cli/src/commands/capture.test.ts @@ -253,6 +253,37 @@ describe("capture command — vision control", () => { ); }); + 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], diff --git a/packages/cli/src/commands/capture.ts b/packages/cli/src/commands/capture.ts index 9657746c8d..ae3488f7a5 100644 --- a/packages/cli/src/commands/capture.ts +++ b/packages/cli/src/commands/capture.ts @@ -8,8 +8,10 @@ import { diag } from "../ui/diagnostics.js"; import type { CapturePhaseProgress } from "../capture/types.js"; import { parseCaptureDeadline } from "../capture/captureWatchdog.js"; import { jsonFailure } from "../utils/jsonError.js"; +import { parseTimeoutMs } from "../utils/timeoutArg.js"; const CAPTURE_PHASE_PREFIX = "HYPERFRAMES_CAPTURE_PHASE "; +const DEFAULT_CAPTURE_TIMEOUT_MS = 120_000; function emitCapturePhase(event: CapturePhaseProgress): void { diag.notice(`${CAPTURE_PHASE_PREFIX}${JSON.stringify(event)}`); @@ -94,7 +96,8 @@ export default defineCommand({ }, timeout: { type: "string", - description: "Page load timeout in ms (default: 120000)", + description: + "Page load timeout: a number of ms, or a duration such as 30s or 2m (default: 120000)", }, "capture-budget": { type: "string", @@ -236,7 +239,7 @@ export default defineCommand({ skipAssets: args["skip-assets"] as boolean, skipVision: args["skip-vision"] as boolean, maxScreenshots, - timeout: args.timeout ? parseInt(args.timeout as string) : undefined, + timeout: parseTimeoutMs(args.timeout, DEFAULT_CAPTURE_TIMEOUT_MS), postNavigationBudgetMs: captureBudgetMs, captureDeadlineMs: parseCaptureDeadline(process.env.HYPERFRAMES_CAPTURE_DEADLINE_MS), json: isJson, diff --git a/packages/cli/src/commands/grade-compare.test.ts b/packages/cli/src/commands/grade-compare.test.ts index 6aa63a4d4f..85c4a1b871 100644 --- a/packages/cli/src/commands/grade-compare.test.ts +++ b/packages/cli/src/commands/grade-compare.test.ts @@ -121,6 +121,33 @@ describe("parseGradeCompareArgs", () => { parseGradeCompareArgs({ for: "frame.png", grades: "grades.json", luts: "a.cube" }), ).toThrow("Exactly one of --grades or --luts is required"); }); + + it.each([ + ["1s", 1_000], + ["1500ms", 1_500], + ["8000", 8_000], + [undefined, 5_000], + ])("reads --timeout %s as %i ms", (timeout, expectedMs) => { + const parsed = parseGradeCompareArgs({ for: "frame.png", grades: "grades.json", timeout }); + expect(parsed.timeoutMs).toBe(expectedMs); + }); + + it("warns and keeps the 5000 ms default when --timeout is not a duration", () => { + const error = vi.spyOn(console, "error").mockImplementation(() => {}); + try { + const parsed = parseGradeCompareArgs({ + for: "frame.png", + grades: "grades.json", + timeout: "abc", + }); + expect(parsed.timeoutMs).toBe(5_000); + expect(error).toHaveBeenCalledWith( + expect.stringContaining('--timeout "abc" is not a duration'), + ); + } finally { + error.mockRestore(); + } + }); }); describe("buildGradeCompareHtml", () => { diff --git a/packages/cli/src/commands/grade-compare.ts b/packages/cli/src/commands/grade-compare.ts index 446fc64c0a..78bf33ab09 100644 --- a/packages/cli/src/commands/grade-compare.ts +++ b/packages/cli/src/commands/grade-compare.ts @@ -31,6 +31,7 @@ import { serveStaticProjectHtml } from "../utils/staticProjectServer.js"; import { withMeta } from "../utils/updateCheck.js"; import { failCaught } from "../utils/jsonError.js"; import { CliUsageError } from "../utils/commandResult.js"; +import { parseTimeoutMs } from "../utils/timeoutArg.js"; const COMPOSITION_ID = "grade-compare"; const COMPOSITION_DURATION = "1"; @@ -40,6 +41,7 @@ const MAX_COLUMNS = 4; const GRID_PADDING = 16; const LABEL_HEIGHT = 32; const FFMPEG_EXTRACT_TIMEOUT_MS = 30_000; +const DEFAULT_RENDER_READY_TIMEOUT_MS = 5_000; export interface GradeCompareCell { label: string; @@ -289,7 +291,7 @@ export function parseGradeCompareArgs(args: { ? { kind: "grades", path: resolveFromBase(projectDir, gradesArg) } : { kind: "luts", value: lutsArg ?? "" }, json: args.json === true, - timeoutMs: Number.parseInt(readOptionalString(args.timeout) ?? "", 10) || 5000, + timeoutMs: parseTimeoutMs(args.timeout, DEFAULT_RENDER_READY_TIMEOUT_MS), }; } @@ -612,7 +614,8 @@ export default defineCommand({ }, timeout: { type: "string", - description: "Render-ready timeout in ms before capture (default: 5000)", + description: + "Render-ready timeout before capture: a number of ms, or a duration such as 30s (default: 5000)", }, baseline: { type: "boolean",