diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index 9e64e74786..bf46e6174e 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -1275,6 +1275,10 @@ and ends a copy that makes no progress for 3 minutes (`HYPERFRAMES_PROXY_STALL_M For a long project, run `hyperframes check --prepare-media` first, then the check itself finds every copy ready. +A Chrome that is not ready 3 minutes after the check begins to start it ends the check with a runtime +finding that says Chrome did not start and how long each step took. On a first run Chrome may still be +downloading: run `hyperframes browser ensure` once, then run check again. + `--caption-zone` and `--frame-check` refuse a ranged check when none of their configured seek samples falls inside `--range`; a requested gate never silently passes without running. diff --git a/packages/cli/src/commands/check.test.ts b/packages/cli/src/commands/check.test.ts index 150242db4a..668ab26950 100644 --- a/packages/cli/src/commands/check.test.ts +++ b/packages/cli/src/commands/check.test.ts @@ -2465,6 +2465,29 @@ describe("check pipeline", () => { } }); + it("a Chrome that never becomes ready ends the whole check with a named finding inside its window", async () => { + vi.useFakeTimers(); + try { + const { deps } = dependencies(fakeDriver()); + deps.runBrowserCheck = (_project, _options, _motion, deadline) => { + deadline!.enter("launch"); + return new Promise((_, reject) => + deadline!.signal.addEventListener("abort", () => reject(deadline!.signal.reason)), + ); + }; + const pending = runCheckPipeline(PROJECT, DEFAULT_CHECK_OPTIONS, deps); + await vi.advanceTimersByTimeAsync(180_000); + const report = await pending; + const failure = report.runtime.findings.find( + (finding) => finding.code === "check_runtime_failure", + ); + expect(failure?.message).toMatch(/^Chrome did not start within 180 s while starting Chrome/); + expect(report.ok).toBe(false); + } finally { + vi.useRealTimers(); + } + }); + it("a check given a long --timeout is not ended as idle after 120 s of waiting for its page", async () => { vi.useFakeTimers(); try { diff --git a/packages/cli/src/utils/checkDeadline.test.ts b/packages/cli/src/utils/checkDeadline.test.ts index 8c3ce9ec81..590777667f 100644 --- a/packages/cli/src/utils/checkDeadline.test.ts +++ b/packages/cli/src/utils/checkDeadline.test.ts @@ -1,5 +1,6 @@ import { afterEach, expect, it, vi } from "vitest"; import { + CheckChromeStartError, CheckDeadline, CheckDeadlineError, CheckStoppedError, @@ -63,7 +64,30 @@ it("cleanup is bounded even when a losing operation ignores cancellation", async await closing; }, 2_000); -it("browser provisioning does not spend the check budget, which starts once when ready", async () => { +it("a Chrome that never becomes ready ends the check with a named error", async () => { + vi.useFakeTimers(); + const deadline = new CheckDeadline(); + const neverReady = deadline + .run(() => rejectOnAbort(deadline.signal)) + .catch((error: unknown) => error); + try { + deadline.enter("launch"); + await vi.advanceTimersByTimeAsync(179_999); + expect(deadline.signal.aborted).toBe(false); + await vi.advanceTimersByTimeAsync(1); + const error = (await neverReady) as Error; + expect(error).toBeInstanceOf(CheckChromeStartError); + expect(error.message).toBe( + "Chrome did not start within 180 s while starting Chrome. Seconds per phase: starting Chrome 180.0. " + + "On a first run it may still be downloading: run `hyperframes browser ensure`, then run check again.", + ); + expect(deadline.signal.aborted).toBe(true); + } finally { + await deadline.close(); + } +}); + +it("the Chrome start window is spent once; a ready Chrome starts the normal idle clock", async () => { vi.useFakeTimers(); const deadline = new CheckDeadline(); let complete!: () => void; @@ -72,12 +96,11 @@ it("browser provisioning does not spend the check budget, which starts once when }); const outcome = deadline.run(() => work).catch((error: unknown) => error); try { - await vi.advanceTimersByTimeAsync(150_000); + deadline.enter("launch"); + await vi.advanceTimersByTimeAsync(170_000); expect(deadline.signal.aborted).toBe(false); deadline.start(); - await vi.advanceTimersByTimeAsync(90_000); - deadline.start(); - await vi.advanceTimersByTimeAsync(29_999); + await vi.advanceTimersByTimeAsync(119_999); expect(deadline.signal.aborted).toBe(false); await vi.advanceTimersByTimeAsync(1); expect(deadline.signal.aborted).toBe(true); @@ -89,6 +112,18 @@ it("browser provisioning does not spend the check budget, which starts once when } }); +it("video copies keep their own budget and do not spend the idle window", async () => { + vi.useFakeTimers(); + const deadline = new CheckDeadline(); + try { + deadline.enter("copies"); + await vi.advanceTimersByTimeAsync(300_000); + expect(deadline.signal.aborted).toBe(false); + } finally { + await deadline.close(); + } +}); + it("closing before browser readiness prevents a later clock from starting", async () => { vi.useFakeTimers(); const deadline = new CheckDeadline(); @@ -121,7 +156,7 @@ it("an expired check names the phase it was in and the seconds each phase took", await vi.advanceTimersByTimeAsync(120_000); expect(((await outcome) as Error).message).toBe( "Check did not finish within its deadline (no progress for 120 s after Chrome was ready), while running the overlap pass. " + - "Seconds per phase: making video copies 247.0 (before the deadline), starting Chrome 2.0 (before the deadline), " + + "Seconds per phase: making video copies 247.0 (before the deadline), starting Chrome 2.0, " + "loading the page 3.0, waiting for the page to be ready 60.0, checking samples 50.0, running the overlap pass 120.0.", ); } finally { diff --git a/packages/cli/src/utils/checkDeadline.ts b/packages/cli/src/utils/checkDeadline.ts index ad373b0f3c..fa291329e3 100644 --- a/packages/cli/src/utils/checkDeadline.ts +++ b/packages/cli/src/utils/checkDeadline.ts @@ -23,7 +23,9 @@ const PHASE_LABELS = { frames: "capturing finding frames", } as const; export type CheckPhase = keyof typeof PHASE_LABELS; -const BEFORE_DEADLINE: ReadonlySet = new Set(["copies", "launch"]); +const BEFORE_DEADLINE: ReadonlySet = new Set(["copies"]); + +const CHROME_START_WINDOW_MS = 180_000; export class CheckDeadlineError extends Error { constructor( @@ -64,6 +66,15 @@ export class CheckStoppedError extends Error { } } +export class CheckChromeStartError extends Error { + constructor(waitedMs: number, where: string) { + super( + `Chrome did not start within ${waitedMs / 1000} s${where || "."} ` + + "On a first run it may still be downloading: run `hyperframes browser ensure`, then run check again.", + ); + } +} + /** Ends a check that makes no progress for its idle window; each phase entered or operation settled restarts it. */ export class CheckDeadline { private readonly abort = new AbortController(); @@ -120,6 +131,7 @@ export class CheckDeadline { if (this.work) this.spend(this.work.phase, now - this.work.since); this.work = { phase, since: now, detail }; this.spend(phase, 0); + this.beat(); this.rearm(); }; @@ -149,6 +161,11 @@ export class CheckDeadline { start = (): void => { if (this.phase !== "waiting") return; this.phase = "started"; + this.enter("load"); + }; + + private beat(): void { + if (this.heartbeat || this.phase === "closed" || this.expired) return; this.heartbeat = setInterval(() => { if (this.work) { const seconds = Math.round((Date.now() - this.work.since) / 1000); @@ -157,15 +174,22 @@ export class CheckDeadline { } }, HEARTBEAT_MS); this.heartbeat.unref(); - this.enter("load"); - }; + } private rearm(): void { - if (this.phase !== "started" || this.expired) return; + if (this.phase === "closed" || this.expired) return; + const launching = this.work?.phase === "launch" && this.phase === "waiting"; + if (this.phase !== "started" && !launching) return; clearTimeout(this.timer); + const window = launching ? Math.max(CHROME_START_WINDOW_MS, this.idleMs) : this.idleMs; this.timer = setTimeout( - () => this.expire(new CheckDeadlineError(this.scripts.at(-1), this.describe())), - this.idleMs, + () => + this.expire( + launching + ? new CheckChromeStartError(window, this.where()) + : new CheckDeadlineError(this.scripts.at(-1), this.describe()), + ), + window, ); }