// fallow-ignore-file code-duplication /** * Browser-binary resolution tests for `findBrowser()`. * * The CLI's `ensureBrowser` is responsible for picking the Chrome binary the * engine will be launched with. There are two real-world failure modes this * suite guards against: * * 1. `chrome-headless-shell` is installed in the puppeteer cache (the * directory the engine itself reads), but the CLI used to only scan its * own `~/.cache/hyperframes/chrome` cache — leaving the engine without a * headless-shell binary and silently disabling the BeginFrame capture * path. * 2. The CLI falls back to system Chrome (`/usr/bin/google-chrome`) on * Linux, which still launches successfully but has dropped * `HeadlessExperimental.enable` — again disabling the BeginFrame path * with no user-visible signal. * * Each test stubs filesystem + `@puppeteer/browsers` access using `vi.doMock` * + dynamic import (the same pattern other modules in this package use, e.g. * `background-removal/manager.test.ts`) so we don't touch the real * `HOME` cache. */ import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync, } from "node:fs"; import { tmpdir } from "node:os"; import { basename, dirname, join, relative, sep } from "node:path"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import { managedChromeVersion } from "./manager.js"; const CHROME_VERSION = managedChromeVersion(); // Use `path.join` so the fake paths line up with whatever separator Node's // real `path.join` produces in `manager.ts` on the host running the test // (forward slashes on Linux/macOS, backslashes on Windows CI). Hardcoded // `/fake/home/...` literals would fail on Windows because the set lookup // would never match the `\\`-joined real paths. const FAKE_HOME = join("/", "fake", "home"); const CACHE_ROOT = join(FAKE_HOME, ".cache", "hyperframes"); const HF_CACHE = join(FAKE_HOME, ".cache", "hyperframes", "chrome"); const HF_LOCK = join(CACHE_ROOT, ".chrome.install.lock"); const HF_RECLAIM_LOCK = join(CACHE_ROOT, ".chrome.install.reclaim.lock"); const PUPPETEER_CACHE = join(FAKE_HOME, ".cache", "puppeteer", "chrome-headless-shell"); const PUPPETEER_BINARY = join( PUPPETEER_CACHE, `linux-${CHROME_VERSION}`, "chrome-headless-shell-linux64", "chrome-headless-shell", ); const HF_BINARY = join( HF_CACHE, "chrome-headless-shell", "linux-131.0.6778.85", "chrome-headless-shell-linux64", "chrome-headless-shell", ); const SYSTEM_CHROME = "/usr/bin/google-chrome"; const TEST_LOCK_TIMINGS = { staleMs: 50, pollMs: 5, heartbeatMs: 10, waitNoticeMs: 1_000, }; // Points node:os homedir at a fresh temp dir so the manager runs against the real filesystem. function useRealCacheHome(): string { const home = mkdtempSync(join(tmpdir(), "hf-browser-cache-")); vi.doMock("node:os", async (importOriginal) => ({ ...(await importOriginal()), homedir: () => home, })); return home; } function stagedVersionDir(cacheDir: string, buildId: string): string { return join(cacheDir, "chrome-headless-shell", `linux-${buildId}`); } function writeStagedInstall(cacheDir: string, buildId: string, content: string) { const path = stagedVersionDir(cacheDir, buildId); const executablePath = join(path, "chrome-headless-shell-linux64", "chrome-headless-shell"); mkdirSync(dirname(executablePath), { recursive: true }); writeFileSync(executablePath, content); return { executablePath, path }; } // The mocked fs path set of the current test, so the install mock can stage files into it. let mockedPaths: Set | undefined; interface FsMockOptions { existing: ReadonlySet; /** map of dir path -> entries returned by readdirSync */ dirs?: Record; touchError?: Error; initialMtimeMs?: number; /** what node:os reports; defaults to a Linux host */ osHost?: { platform: string; release: string }; /** paths whose stat reports 0 bytes */ emptyFiles?: ReadonlySet; } function installFsMocks({ existing, dirs, touchError, initialMtimeMs = 0, osHost = { platform: "linux", release: "24.0.0" }, emptyFiles, }: FsMockOptions) { // Mutable, and returned, so tests can pre-seed a "lock already held" path or // assert the lock dir doesn't leak after ensureBrowser resolves. const paths = new Set(existing); mockedPaths = paths; const mtimes = new Map([...existing].map((p) => [p, initialMtimeMs])); const contents = new Map(); vi.doMock("node:fs", () => ({ existsSync: (p: string) => paths.has(p), readdirSync: (p: string) => { const entries = dirs?.[p]; if (!entries) { const err = new Error(`ENOENT: readdirSync mock had no entry for ${p}`); (err as NodeJS.ErrnoException).code = "ENOENT"; throw err; } return entries; }, mkdirSync: (p: string, opts?: { recursive?: boolean }) => { if (!opts?.recursive && paths.has(p)) { const err = new Error(`EEXIST: file already exists, mkdir '${p}'`); (err as NodeJS.ErrnoException).code = "EEXIST"; throw err; } paths.add(p); mtimes.set(p, Date.now()); }, rmSync: (p: string) => { // Real rmSync({recursive:true}) removes the target AND everything under // it; the mock's flat path Set has no real tree structure, so simulate // that by also dropping any tracked path nested under `p`. for (const existingPath of [...paths]) { if (existingPath === p || existingPath.startsWith(p + sep)) { paths.delete(existingPath); mtimes.delete(existingPath); contents.delete(existingPath); } } }, renameSync: (from: string, to: string) => { const moved = [...paths].filter((p) => p === from || p.startsWith(from + sep)); if (moved.length === 0) { const err = new Error(`ENOENT: no such file or directory, rename '${from}'`); (err as NodeJS.ErrnoException).code = "ENOENT"; throw err; } for (const p of moved) { paths.delete(p); paths.add(to + p.slice(from.length)); } }, statSync: (p: string, opts?: { throwIfNoEntry?: boolean }) => { if (!paths.has(p)) { if (opts?.throwIfNoEntry === false) return undefined; const err = new Error(`ENOENT: no such file or directory, stat '${p}'`); (err as NodeJS.ErrnoException).code = "ENOENT"; throw err; } return { mtimeMs: mtimes.get(p) ?? 0, size: emptyFiles?.has(p) ? 0 : 1, isFile: () => true }; }, utimesSync: (p: string, _atime: Date, mtime: Date) => { if (touchError) throw touchError; if (!paths.has(p)) { const err = new Error(`ENOENT: no such file or directory, utimes '${p}'`); (err as NodeJS.ErrnoException).code = "ENOENT"; throw err; } mtimes.set(p, mtime.getTime()); }, writeFileSync: (p: string, value: string) => { paths.add(p); contents.set(p, value); }, readFileSync: (p: string) => { const value = contents.get(p); if (value === undefined) { const err = new Error(`ENOENT: no such file or directory, read '${p}'`); (err as NodeJS.ErrnoException).code = "ENOENT"; throw err; } return value; }, })); vi.doMock("node:os", () => ({ homedir: () => FAKE_HOME, platform: () => osHost.platform, release: () => osHost.release, arch: () => "x64", })); return paths; } interface InstallMockOptions { buildId: string; cacheDir: string; unpack?: boolean; logger?: (prefix: string) => ((...args: unknown[]) => void) | undefined; } function installPuppeteerBrowsersMock( opts: { installedInHfCache?: Array<{ browser: string; executablePath: string; path?: string; buildId?: string; platform?: string; }>; browserPlatform?: string; installedInHfCacheError?: Error; installResult?: { executablePath: string; path?: string }; installImpl?: ( options: InstallMockOptions, ) => Promise<{ executablePath: string; path?: string }>; unzip?: (archivePath: string, folderPath: string) => Promise; } = {}, ) { const impl = opts.installImpl ?? (async () => opts.installResult ?? { executablePath: HF_BINARY }); // Fixtures name the binary where it lands in HF_CACHE; install() really writes it under its own cacheDir. const stagedInstall = async (options: InstallMockOptions) => { if (options.unpack === false) return join(options.cacheDir, "archive.zip"); const result = await impl(options); if (result.path || !result.executablePath.startsWith(HF_CACHE + sep)) return result; const rel = relative(HF_CACHE, result.executablePath); const executablePath = join(options.cacheDir, rel); const path = join(options.cacheDir, ...rel.split(sep).slice(0, 2)); mockedPaths?.add(path).add(executablePath); return { executablePath, path }; }; vi.doMock("./installInChild.js", async () => { const { install } = await import("@puppeteer/browsers"); return { BrowserDownloadStalledError: class extends Error {}, installInChild: ( input: object, hooks: { onProgress?: (downloaded: number, total: number) => void; onLog: (line: string) => void; }, ) => install({ ...input, downloadProgressCallback: hooks.onProgress, logger: (prefix: string) => prefix === "puppeteer:browsers:fileUtil" ? (...args: unknown[]) => hooks.onLog(args.join(" ")) : undefined, } as never), }; }); vi.doMock("./unzipArchive.js", () => ({ unzipArchive: opts.unzip ?? vi.fn(async () => true) })); vi.doMock("@puppeteer/browsers", () => ({ Browser: { CHROMEHEADLESSSHELL: "chrome-headless-shell" }, Cache: class { constructor(private readonly dir: string) {} installationDir(browser: string, platform: string, buildId: string) { return join(this.dir, browser, `${platform}-${buildId}`); } }, detectBrowserPlatform: () => opts.browserPlatform ?? "linux", getInstalledBrowsers: opts.installedInHfCacheError ? vi.fn().mockRejectedValue(opts.installedInHfCacheError) : vi.fn().mockResolvedValue( (opts.installedInHfCache ?? []).map((browser) => ({ platform: opts.browserPlatform ?? "linux", ...browser, })), ), install: vi.fn().mockImplementation(stagedInstall), })); } function installChildProcessMocks() { vi.doMock("node:child_process", () => ({ execSync: vi.fn(() => { throw new Error("not found"); }), spawnSync: vi.fn(), })); } describe("findBrowser — cache resolution", () => { const origPlatform = process.platform; const origArch = process.arch; beforeEach(() => { vi.resetModules(); // Force Linux for the system-fallback warning assertions. The // `Object.defineProperty` dance is needed because `process.platform` is a // getter on Node — direct assignment is silently a no-op. Object.defineProperty(process, "platform", { value: "linux", configurable: true, }); Object.defineProperty(process, "arch", { value: "x64", configurable: true, }); delete process.env["HYPERFRAMES_BROWSER_PATH"]; delete process.env["PRODUCER_HEADLESS_SHELL_PATH"]; installChildProcessMocks(); }); afterEach(() => { vi.useRealTimers(); Object.defineProperty(process, "platform", { value: origPlatform, configurable: true, }); Object.defineProperty(process, "arch", { value: origArch, configurable: true, }); vi.restoreAllMocks(); vi.doUnmock("node:fs"); vi.doUnmock("node:os"); vi.doUnmock("node:child_process"); vi.doUnmock("@puppeteer/browsers"); }); it("resolves to the hyperframes-managed cache when puppeteer cache is empty", async () => { // Only HF cache populated. Puppeteer cache is the higher-priority path // (see "prefers puppeteer cache" test below), so this exercises the // last-resort fallback. installFsMocks({ existing: new Set([HF_CACHE, HF_BINARY]) }); installPuppeteerBrowsersMock({ installedInHfCache: [ { browser: "chrome-headless-shell", executablePath: HF_BINARY, buildId: CHROME_VERSION, }, ], }); const { findBrowser } = await import("./manager.js"); const result = await findBrowser(); expect(result).toEqual({ executablePath: HF_BINARY, source: "cache" }); }); it("hides the Windows console used by the where lookup", async () => { Object.defineProperty(process, "platform", { value: "win32", configurable: true, }); installFsMocks({ existing: new Set() }); installPuppeteerBrowsersMock(); const execSync = vi.fn((command: string) => command === "where google-chrome" ? "C:\\Chrome\\chrome.exe\n" : "", ); vi.doMock("node:child_process", () => ({ execSync, spawnSync: vi.fn() })); const { findBrowser } = await import("./manager.js"); const result = await findBrowser(); expect(result).toEqual({ executablePath: "C:\\Chrome\\chrome.exe", source: "system", }); expect(execSync).toHaveBeenCalledWith( "where google-chrome", expect.objectContaining({ windowsHide: true }), ); }); it("finds Chrome in the standard Windows Program Files location", async () => { Object.defineProperty(process, "platform", { value: "win32", configurable: true, }); const windowsChrome = join( "C:\\Program Files", "Google", "Chrome", "Application", "chrome.exe", ); installFsMocks({ existing: new Set([windowsChrome]) }); installPuppeteerBrowsersMock(); const { findSystemBrowser } = await import("./manager.js"); expect(findSystemBrowser()).toEqual({ executablePath: windowsChrome, source: "system", }); }); it("does not resolve to a hyperframes-cache build from an older CHROME_VERSION pin", async () => { // A build downloaded by a prior hyperframes version (this pin has moved // 131 -> 151 -> 152 across releases) must not satisfy resolution, or an // upgrade silently keeps running a stale build forever instead of ever // fetching the version the new release actually needs (HF#2060 review). installFsMocks({ existing: new Set([HF_CACHE, HF_BINARY, SYSTEM_CHROME]) }); installPuppeteerBrowsersMock({ installedInHfCache: [ { browser: "chrome-headless-shell", executablePath: HF_BINARY, buildId: "131.0.6778.85", }, ], }); const { findBrowser } = await import("./manager.js"); const result = await findBrowser(); expect(result?.executablePath).not.toBe(HF_BINARY); expect(result).toEqual({ executablePath: SYSTEM_CHROME, source: "system" }); }); it("ignores a current-version HyperFrames cache entry for another platform", async () => { Object.defineProperty(process, "platform", { value: "darwin", configurable: true, }); Object.defineProperty(process, "arch", { value: "arm64", configurable: true, }); const macArm64Binary = join( HF_CACHE, "chrome-headless-shell", "mac_arm-131.0.6778.85", "chrome-headless-shell-mac-arm64", "chrome-headless-shell", ); installFsMocks({ existing: new Set([HF_CACHE, HF_BINARY, macArm64Binary]), }); installPuppeteerBrowsersMock({ browserPlatform: "mac_arm", installedInHfCache: [ { browser: "chrome-headless-shell", executablePath: HF_BINARY, buildId: CHROME_VERSION, platform: "linux", }, { browser: "chrome-headless-shell", executablePath: macArm64Binary, buildId: CHROME_VERSION, platform: "mac_arm", }, ], }); const { findBrowser } = await import("./manager.js"); const result = await findBrowser(); expect(result).toEqual({ executablePath: macArm64Binary, source: "cache" }); }); it("re-downloads when the hyperframes cache manifest points at a missing binary", async () => { const redownloadedBinary = join( HF_CACHE, "chrome-headless-shell", "linux-131.0.6778.85", "chrome-headless-shell-linux64", "redownloaded-chrome-headless-shell", ); const staleInstallDir = stagedVersionDir(HF_CACHE, "131.0.6778.85"); // The stale install DIR is present (extraction got partway through, e.g. an // ABOUT/LICENSE-only extract) even though the exe itself is missing — // exercises the purge-before-redownload fix, not just the redownload path. const staleLeftover = join(staleInstallDir, "ABOUT"); const paths = installFsMocks({ existing: new Set([HF_CACHE, staleInstallDir, staleLeftover]), }); installPuppeteerBrowsersMock({ installedInHfCache: [ { browser: "chrome-headless-shell", executablePath: HF_BINARY, path: staleInstallDir, buildId: CHROME_VERSION, }, ], installResult: { executablePath: redownloadedBinary }, }); const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); const { findBrowser } = await import("./manager.js"); const result = await findBrowser(); expect(result).toEqual({ executablePath: redownloadedBinary, source: "download", }); expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("Cached binary unusable")); // The partial extract is replaced wholesale, not merged into (install() would // otherwise throw "folder exists but exe missing", the bug both feedback reports hit). expect(paths.has(staleLeftover)).toBe(false); expect(paths.has(redownloadedBinary)).toBe(true); }); it("ensureBrowser({force: true}) re-downloads without purging the cache, bypassing any cache/system shortcut", async () => { const staleInstallDir = stagedVersionDir(HF_CACHE, "131.0.6778.85"); const downloadedBinary = join(HF_CACHE, "chrome-headless-shell", "force-downloaded"); // A HEALTHY cached binary AND system Chrome are both present — force must // ignore both shortcuts and always re-download, which is the whole point // of the flag (the reported bug: --force did nothing, a stale dir kept // winning over every retry). const paths = installFsMocks({ existing: new Set([HF_CACHE, HF_BINARY, staleInstallDir, SYSTEM_CHROME]), }); installPuppeteerBrowsersMock({ installedInHfCache: [ { browser: "chrome-headless-shell", executablePath: HF_BINARY, path: staleInstallDir, }, ], installResult: { executablePath: downloadedBinary }, }); const { ensureBrowser } = await import("./manager.js"); const result = await ensureBrowser({ force: true }); expect(result).toEqual({ executablePath: downloadedBinary, source: "download", }); // Only the downloaded version dir is swapped in; other cache entries stay. expect(paths.has(downloadedBinary)).toBe(true); expect(paths.has(HF_BINARY)).toBe(true); }); it("keeps a live reader's binary valid while a concurrent --force re-downloads it", async () => { const home = useRealCacheHome(); let label = "old"; let seenMidInstall: string | undefined; let liveBinary: string | undefined; installPuppeteerBrowsersMock({ installImpl: async ({ cacheDir, buildId }) => { if (liveBinary) seenMidInstall = readFileSync(liveBinary, "utf8"); return writeStagedInstall(cacheDir, buildId, label); }, }); try { const { ensureBrowser, CACHE_DIR } = await import("./manager.js"); const otherVersion = join(stagedVersionDir(CACHE_DIR, "1.0.0"), "marker"); mkdirSync(dirname(otherVersion), { recursive: true }); writeFileSync(otherVersion, "other"); liveBinary = (await ensureBrowser({ force: true })).executablePath; label = "new"; const forced = await ensureBrowser({ force: true }); expect(seenMidInstall).toBe("old"); expect(forced.executablePath).toBe(liveBinary); expect(readFileSync(liveBinary, "utf8")).toBe("new"); expect(readFileSync(otherVersion, "utf8")).toBe("other"); } finally { rmSync(home, { recursive: true, force: true }); } }); it("installs again instead of reusing an empty cached executable", async () => { const home = useRealCacheHome(); installPuppeteerBrowsersMock({ installImpl: async ({ cacheDir, buildId }) => writeStagedInstall(cacheDir, buildId, "fresh"), }); try { const { ensureBrowser } = await import("./manager.js"); const cached = await ensureBrowser({ force: true }); writeFileSync(cached.executablePath, ""); const { getInstalledBrowsers } = await import("@puppeteer/browsers"); vi.mocked(getInstalledBrowsers).mockResolvedValue([ { browser: "chrome-headless-shell", buildId: CHROME_VERSION, platform: "linux", executablePath: cached.executablePath, } as never, ]); vi.spyOn(console, "warn").mockImplementation(() => {}); const again = await ensureBrowser({ preferManagedChrome: true }); expect(again.source).toBe("download"); expect(readFileSync(again.executablePath, "utf8")).toBe("fresh"); } finally { rmSync(home, { recursive: true, force: true }); } }); it("restores the previous version when the staged install cannot be moved in", async () => { const home = useRealCacheHome(); let stageNothing = false; installPuppeteerBrowsersMock({ installImpl: async ({ cacheDir, buildId, logger }) => { if (!stageNothing) return writeStagedInstall(cacheDir, buildId, "old"); logger?.("puppeteer:browsers:fileUtil")?.( "tar.exe extraction failed: before PowerShell worked", ); // A real executable passes the unzip check, but its version dir is gone, so only the move fails. const elsewhere = writeStagedInstall(join(cacheDir, "elsewhere"), buildId, "new"); return { executablePath: elsewhere.executablePath, path: stagedVersionDir(cacheDir, buildId), }; }, }); try { const { ensureBrowser } = await import("./manager.js"); const liveBinary = (await ensureBrowser({ force: true })).executablePath; stageNothing = true; const failure = await ensureBrowser({ force: true }).catch((err: unknown) => String(err)); expect(failure).toContain("HYPERFRAMES_BROWSER_PATH"); expect(failure).not.toContain("Unzip errors"); expect(readFileSync(liveBinary, "utf8")).toBe("old"); } finally { rmSync(home, { recursive: true, force: true }); } }); it.each([ { label: "missing", unpacked: "none", state: "is missing" }, { label: "empty", unpacked: "file", state: "is empty" }, { label: "a folder", unpacked: "folder", state: "is not a file" }, ])("fails instead of reporting a browser the unzip left $label", async ({ unpacked, state }) => { const home = useRealCacheHome(); installPuppeteerBrowsersMock({ installImpl: async ({ cacheDir, buildId, logger }) => { const staged = writeStagedInstall(cacheDir, buildId, ""); rmSync(staged.executablePath); if (unpacked === "file") writeFileSync(staged.executablePath, ""); if (unpacked === "folder") mkdirSync(join(staged.executablePath, "inside"), { recursive: true }); logger?.("puppeteer:browsers:fileUtil")?.("tar.exe extraction failed: Error: boom"); return staged; }, }); try { const { ensureBrowser, CACHE_DIR } = await import("./manager.js"); const ensured = ensureBrowser({ preferManagedChrome: true }); await expect(ensured).rejects.toThrow(`chrome-headless-shell ${state} after unzipping`); await expect(ensured).rejects.toThrow("tar.exe extraction failed: Error: boom"); expect(existsSync(CACHE_DIR)).toBe(false); } finally { rmSync(home, { recursive: true, force: true }); } }); it("names the unzip errors when every unzip tool failed", async () => { const home = useRealCacheHome(); installPuppeteerBrowsersMock({ installImpl: async ({ logger }) => { logger?.("puppeteer:browsers:fileUtil")?.("tar.exe extraction failed: Error: tar boom"); logger?.("puppeteer:browsers:fileUtil")?.( "powershell.exe extraction failed: Error: ps boom", ); throw new Error("Extraction failed: no zip archiver is available."); }, }); try { const { ensureBrowser } = await import("./manager.js"); const ensured = ensureBrowser({ force: true }); await expect(ensured).rejects.toThrow( "no zip archiver is available. Unzip errors: tar.exe extraction failed: Error: tar boom; powershell.exe extraction failed: Error: ps boom", ); } finally { rmSync(home, { recursive: true, force: true }); } }); it("reports only the last attempt's unzip errors after a corrupt-archive retry", async () => { const home = useRealCacheHome(); let attempt = 0; installPuppeteerBrowsersMock({ installImpl: async ({ cacheDir, buildId, logger }) => { attempt += 1; logger?.("puppeteer:browsers:fileUtil")?.(`tar.exe extraction failed: attempt ${attempt}`); if (attempt === 1) throw new Error("invalid end of central directory"); const staged = writeStagedInstall(cacheDir, buildId, ""); rmSync(staged.executablePath); return staged; }, }); vi.spyOn(console, "warn").mockImplementation(() => {}); try { const { ensureBrowser } = await import("./manager.js"); const error = await ensureBrowser({ force: true }).catch((err: unknown) => err); expect(String(error)).toContain("tar.exe extraction failed: attempt 2"); expect(String(error)).not.toContain("attempt 1"); } finally { rmSync(home, { recursive: true, force: true }); } }); it("sweeps dirs leaked by a killed install on the next install and on clear", async () => { const home = useRealCacheHome(); installPuppeteerBrowsersMock({ installImpl: async ({ cacheDir, buildId }) => writeStagedInstall(cacheDir, buildId, "fresh"), }); const root = join(home, ".cache", "hyperframes"); const leftovers = [join(root, ".chrome-staging-dead"), join(root, ".chrome-replaced-dead")]; const seedLeftovers = () => { for (const dir of leftovers) mkdirSync(join(dir, "partial"), { recursive: true }); }; try { const { ensureBrowser, clearBrowser } = await import("./manager.js"); seedLeftovers(); await ensureBrowser({ force: true }); expect(leftovers.filter((dir) => existsSync(dir))).toEqual([]); seedLeftovers(); expect(clearBrowser()).toBe(true); expect(leftovers.filter((dir) => existsSync(dir))).toEqual([]); } finally { rmSync(home, { recursive: true, force: true }); } }); it("serializes concurrent force downloads so they never install at the same time", async () => { const downloadedBinary = join(HF_CACHE, "chrome-headless-shell", "force-downloaded"); const paths = installFsMocks({ existing: new Set([CACHE_ROOT, HF_CACHE, HF_BINARY]), }); let activeInstalls = 0; let maxActiveInstalls = 0; installPuppeteerBrowsersMock({ installedInHfCache: [{ browser: "chrome-headless-shell", executablePath: HF_BINARY }], installImpl: async () => { activeInstalls += 1; maxActiveInstalls = Math.max(maxActiveInstalls, activeInstalls); expect(paths.has(HF_LOCK)).toBe(true); await new Promise((resolve) => setTimeout(resolve, 20)); activeInstalls -= 1; return { executablePath: downloadedBinary }; }, }); const { ensureBrowser } = await import("./manager.js"); await expect( Promise.all([ensureBrowser({ force: true }), ensureBrowser({ force: true })]), ).resolves.toEqual([ { executablePath: downloadedBinary, source: "download" }, { executablePath: downloadedBinary, source: "download" }, ]); expect(maxActiveInstalls).toBe(1); expect(paths.has(HF_LOCK)).toBe(false); }); it("ensureBrowser does not leak the install lock directory after a successful download", async () => { // Regression: @puppeteer/browsers' install() has no concurrency guard — // two CLI invocations that both miss the cache AND system Chrome (the // reported scenario: two `hyperframes browser ensure` runs racing) hit // ensureBrowser's final download-of-last-resort at once, racing on the // same extract target. mkdirSync as an atomic mutex closes that race; // this asserts the lock is actually released afterward (a leaked lock // would permanently wedge every future render on this machine). const downloadedBinary = join(HF_CACHE, "chrome-headless-shell", "downloaded"); // Cache dir exists but is empty (no manifest entries) — distinct from the // ENOTDIR "cache unreadable" case, which falls back to system instead. const paths = installFsMocks({ existing: new Set([HF_CACHE]) }); installPuppeteerBrowsersMock({ installedInHfCache: [], installResult: { executablePath: downloadedBinary }, }); const { ensureBrowser } = await import("./manager.js"); const result = await ensureBrowser(); expect(result).toEqual({ executablePath: downloadedBinary, source: "download", }); expect(paths.has(HF_LOCK)).toBe(false); }); it("withInstallLock reclaims a lock held past the timeout instead of hanging forever", async () => { const paths = installFsMocks({ existing: new Set([CACHE_ROOT, HF_LOCK]) }); const { withInstallLock } = await import("./manager.js"); const result = await withInstallLock(async () => "done", TEST_LOCK_TIMINGS); expect(result).toBe("done"); expect(paths.has(HF_LOCK)).toBe(false); }); it("withInstallLock recovers when a crashed reclaimer leaves both lock directories", async () => { vi.useFakeTimers(); const paths = installFsMocks({ existing: new Set([CACHE_ROOT, HF_LOCK, HF_RECLAIM_LOCK]), }); const { withInstallLock } = await import("./manager.js"); const acquisition = withInstallLock(async () => "done", TEST_LOCK_TIMINGS); await vi.advanceTimersByTimeAsync(TEST_LOCK_TIMINGS.pollMs * 2); await expect(Promise.race([acquisition, Promise.resolve("still waiting")])).resolves.toBe( "done", ); expect(paths.has(HF_LOCK)).toBe(false); expect(paths.has(HF_RECLAIM_LOCK)).toBe(false); }); it("withInstallLock does not reclaim another waiter's fresh lock after this waiter timed out", async () => { // Regression guard for the timeout-reclaim race: if multiple waiters cross // the stale-lock deadline together, waiter A can reclaim the stale lock and // acquire a fresh one. Waiter B's old deadline is still expired, but it must // not delete A's fresh lock. const paths = installFsMocks({ existing: new Set([CACHE_ROOT, HF_LOCK]) }); const { withInstallLock } = await import("./manager.js"); const reclaimOnlyTimings = { ...TEST_LOCK_TIMINGS, heartbeatMs: 1_000 }; const first = withInstallLock(async () => { await new Promise((resolve) => setTimeout(resolve, 30)); return "first"; }, reclaimOnlyTimings); const second = withInstallLock(async () => "second", reclaimOnlyTimings); await expect(Promise.all([first, second])).resolves.toEqual(["first", "second"]); expect(paths.has(HF_LOCK)).toBe(false); expect(paths.has(HF_RECLAIM_LOCK)).toBe(false); }); it("withInstallLock does not let a second caller run concurrently with a slow-but-alive holder", async () => { const paths = installFsMocks({ existing: new Set([CACHE_ROOT]) }); const { withInstallLock } = await import("./manager.js"); let concurrent = 0; let maxConcurrent = 0; const trackConcurrency = async (label: string, durationMs: number) => { concurrent += 1; maxConcurrent = Math.max(maxConcurrent, concurrent); await new Promise((resolve) => setTimeout(resolve, durationMs)); concurrent -= 1; return label; }; const first = withInstallLock(() => trackConcurrency("first", 120), TEST_LOCK_TIMINGS); await new Promise((resolve) => setTimeout(resolve, 5)); // let `first` acquire the lock const second = withInstallLock(() => trackConcurrency("second", 10), TEST_LOCK_TIMINGS); await expect(Promise.all([first, second])).resolves.toEqual(["first", "second"]); expect(maxConcurrent).toBe(1); expect(paths.has(HF_LOCK)).toBe(false); }); it("withInstallLock reports progress while waiting instead of staying silent", async () => { // Fake timers freeze Date.now() so the lock mtime stays non-stale across // the dynamic import that follows — without them, a slow import beat could // push wall-clock past staleMs before `withInstallLock` even starts polling, // firing the immediate-stale short-circuit and skipping the wait-notice // branch this test exists to observe. vi.useFakeTimers(); const paths = installFsMocks({ existing: new Set([CACHE_ROOT, HF_LOCK]), initialMtimeMs: Date.now(), }); const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); const { withInstallLock } = await import("./manager.js"); const acquisition = withInstallLock(async () => "done", { ...TEST_LOCK_TIMINGS, waitNoticeMs: 20, }); // Advance past waitNoticeMs (fires the "Waiting for…" warn), then past // staleMs (lets `reclaimStaleInstallLock` clear the held lock so the // acquisition resolves). await vi.advanceTimersByTimeAsync(TEST_LOCK_TIMINGS.staleMs + TEST_LOCK_TIMINGS.pollMs * 5); await expect(acquisition).resolves.toBe("done"); expect(paths.has(HF_LOCK)).toBe(false); expect( warnSpy.mock.calls.some(([msg]) => String(msg).includes("Waiting for another hyperframes process"), ), ).toBe(true); }); it("keeps the holder running when a heartbeat cannot touch the lock", async () => { installFsMocks({ existing: new Set([CACHE_ROOT]), touchError: Object.assign(new Error("EACCES"), { code: "EACCES" }), }); const { withInstallLock } = await import("./manager.js"); await expect( withInstallLock(async () => { await new Promise((resolve) => setTimeout(resolve, 25)); return "done"; }, TEST_LOCK_TIMINGS), ).resolves.toBe("done"); }); it("warns and falls through when the hyperframes cache cannot be read", async () => { installFsMocks({ existing: new Set([HF_CACHE, SYSTEM_CHROME]) }); installPuppeteerBrowsersMock({ installedInHfCacheError: Object.assign(new Error("ENOTDIR: not a directory"), { code: "ENOTDIR", }), }); const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); const { findBrowser, _resetSystemFallbackWarnForTests } = await import("./manager.js"); _resetSystemFallbackWarnForTests(); const result = await findBrowser(); expect(result).toEqual({ executablePath: SYSTEM_CHROME, source: "system" }); expect(warnSpy.mock.calls[0]?.[0]).toContain("Browser cache read failed (ENOTDIR)"); expect(warnSpy.mock.calls[0]?.[0]).toContain("Falling back to system Chrome"); }); it("falls back to the puppeteer-managed cache when hyperframes cache is empty", async () => { // Empty hyperframes cache, populated puppeteer cache — the regression // scenario from the hf#677 spike. installFsMocks({ existing: new Set([PUPPETEER_CACHE, PUPPETEER_BINARY]), dirs: { [PUPPETEER_CACHE]: [`linux-${CHROME_VERSION}`] }, }); installPuppeteerBrowsersMock(); const { findBrowser } = await import("./manager.js"); const result = await findBrowser(); expect(result).toEqual({ executablePath: PUPPETEER_BINARY, source: "cache", }); }); it.each([ { hostPlatform: "darwin", hostArch: "arm64", expectedDirectory: "chrome-headless-shell-mac-arm64", expectedExecutable: "chrome-headless-shell", }, { hostPlatform: "darwin", hostArch: "x64", expectedDirectory: "chrome-headless-shell-mac-x64", expectedExecutable: "chrome-headless-shell", }, { hostPlatform: "linux", hostArch: "x64", expectedDirectory: "chrome-headless-shell-linux64", expectedExecutable: "chrome-headless-shell", }, { hostPlatform: "win32", hostArch: "ia32", expectedDirectory: "chrome-headless-shell-win32", expectedExecutable: "chrome-headless-shell.exe", }, { hostPlatform: "win32", hostArch: "x64", expectedDirectory: "chrome-headless-shell-win64", expectedExecutable: "chrome-headless-shell.exe", }, ])( "selects only the host-compatible cached shell on $hostPlatform/$hostArch when every platform is present", async ({ hostPlatform, hostArch, expectedDirectory, expectedExecutable }) => { Object.defineProperty(process, "platform", { value: hostPlatform, configurable: true, }); Object.defineProperty(process, "arch", { value: hostArch, configurable: true, }); const version = `host-${CHROME_VERSION}`; const candidates = [ ["chrome-headless-shell-linux64", "chrome-headless-shell"], ["chrome-headless-shell-mac-arm64", "chrome-headless-shell"], ["chrome-headless-shell-mac-x64", "chrome-headless-shell"], ["chrome-headless-shell-win32", "chrome-headless-shell.exe"], ["chrome-headless-shell-win64", "chrome-headless-shell.exe"], ] as const; const binaries = candidates.map(([directory, executable]) => join(PUPPETEER_CACHE, version, directory, executable), ); const expectedBinary = join(PUPPETEER_CACHE, version, expectedDirectory, expectedExecutable); installFsMocks({ existing: new Set([PUPPETEER_CACHE, ...binaries]), dirs: { [PUPPETEER_CACHE]: [version] }, }); installPuppeteerBrowsersMock(); const { findBrowser } = await import("./manager.js"); const result = await findBrowser(); expect(result).toEqual({ executablePath: expectedBinary, source: "cache", }); }, ); it.each([ { hostPlatform: "linux", hostArch: "arm64" }, { hostPlatform: "win32", hostArch: "arm64" }, ])( "does not select a foreign cached shell on unsupported $hostPlatform/$hostArch", async ({ hostPlatform, hostArch }) => { Object.defineProperty(process, "platform", { value: hostPlatform, configurable: true, }); Object.defineProperty(process, "arch", { value: hostArch, configurable: true, }); const version = `host-${CHROME_VERSION}`; const binaries = [ join(PUPPETEER_CACHE, version, "chrome-headless-shell-linux64", "chrome-headless-shell"), join(PUPPETEER_CACHE, version, "chrome-headless-shell-win64", "chrome-headless-shell.exe"), ]; installFsMocks({ existing: new Set([PUPPETEER_CACHE, ...binaries]), dirs: { [PUPPETEER_CACHE]: [version] }, }); installPuppeteerBrowsersMock(); const { findBrowser } = await import("./manager.js"); await expect(findBrowser()).resolves.toBeUndefined(); }, ); it("skips an empty executable in the puppeteer cache", async () => { installFsMocks({ existing: new Set([PUPPETEER_CACHE, PUPPETEER_BINARY]), dirs: { [PUPPETEER_CACHE]: [`linux-${CHROME_VERSION}`] }, emptyFiles: new Set([PUPPETEER_BINARY]), }); installPuppeteerBrowsersMock(); const { findBrowser } = await import("./manager.js"); const result = await findBrowser(); expect(result?.executablePath).not.toBe(PUPPETEER_BINARY); }); it("prefers our pinned cache over the puppeteer cache when BOTH are populated", async () => { installFsMocks({ existing: new Set([HF_CACHE, HF_BINARY, PUPPETEER_CACHE, PUPPETEER_BINARY]), dirs: { [PUPPETEER_CACHE]: [`linux-${CHROME_VERSION}`] }, }); installPuppeteerBrowsersMock({ installedInHfCache: [ { browser: "chrome-headless-shell", executablePath: HF_BINARY, buildId: CHROME_VERSION }, ], }); const { findBrowser } = await import("./manager.js"); const result = await findBrowser(); expect(result).toEqual({ executablePath: HF_BINARY, source: "cache" }); }); it("uses our pinned build, not another tool's older shell in the puppeteer cache", async () => { // Field report: a Mac whose puppeteer cache held mac_arm-121 got that shell for check and snapshot, and it died. const oldBinary = join( PUPPETEER_CACHE, "linux-121.0.6167.85", "chrome-headless-shell-linux64", "chrome-headless-shell", ); installFsMocks({ existing: new Set([HF_CACHE, HF_BINARY, PUPPETEER_CACHE, oldBinary]), dirs: { [PUPPETEER_CACHE]: ["linux-121.0.6167.85"] }, }); installPuppeteerBrowsersMock({ installedInHfCache: [ { browser: "chrome-headless-shell", executablePath: HF_BINARY, buildId: CHROME_VERSION }, ], }); const { findBrowser } = await import("./manager.js"); await expect(findBrowser()).resolves.toEqual({ executablePath: HF_BINARY, source: "cache" }); }); it("skips another build in the puppeteer cache that does not start", async () => { const oldBinary = join( PUPPETEER_CACHE, "linux-121.0.6167.85", "chrome-headless-shell-linux64", "chrome-headless-shell", ); installFsMocks({ existing: new Set([PUPPETEER_CACHE, oldBinary]), dirs: { [PUPPETEER_CACHE]: ["linux-121.0.6167.85"] }, }); installPuppeteerBrowsersMock(); const { findBrowser } = await import("./manager.js"); expect((await findBrowser())?.executablePath).not.toBe(oldBinary); }); it("keeps the newest working shell in the puppeteer cache when the pinned build is absent", async () => { const shared = (version: string) => join( PUPPETEER_CACHE, `linux-${version}`, "chrome-headless-shell-linux64", "chrome-headless-shell", ); installFsMocks({ existing: new Set([PUPPETEER_CACHE, shared("99.0.6533.123"), shared("148.0.7778.97")]), dirs: { [PUPPETEER_CACHE]: ["linux-99.0.6533.123", "linux-148.0.7778.97"] }, }); installPuppeteerBrowsersMock(); vi.doMock("node:child_process", () => ({ execSync: vi.fn(() => { throw new Error("not found"); }), spawnSync: vi.fn(() => ({ status: 0 })), })); const { findBrowser } = await import("./manager.js"); await expect(findBrowser()).resolves.toEqual({ executablePath: shared("148.0.7778.97"), source: "cache", }); }); it("falls back to system Chrome and warns on Linux when no cache has headless-shell", async () => { installFsMocks({ existing: new Set([SYSTEM_CHROME]) }); installPuppeteerBrowsersMock(); const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); const { findBrowser, _resetSystemFallbackWarnForTests } = await import("./manager.js"); _resetSystemFallbackWarnForTests(); const result = await findBrowser(); expect(result).toEqual({ executablePath: SYSTEM_CHROME, source: "system" }); expect(warnSpy).toHaveBeenCalledTimes(1); const message = warnSpy.mock.calls[0]?.[0]; expect(message).toContain(SYSTEM_CHROME); expect(message).toContain("HeadlessExperimental"); expect(message).toContain("chrome-headless-shell"); }); it("does NOT warn when the system path happens to be chrome-headless-shell", async () => { // HYPERFRAMES_BROWSER_PATH-style override pointing directly at a // headless-shell binary should NOT trigger the system-Chrome warning. The // warning is gated on the binary name, not the path source. const directShell = "/opt/chrome-headless-shell/chrome-headless-shell"; installFsMocks({ existing: new Set([directShell]) }); installPuppeteerBrowsersMock(); process.env["HYPERFRAMES_BROWSER_PATH"] = directShell; const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); const { findBrowser, _resetSystemFallbackWarnForTests } = await import("./manager.js"); _resetSystemFallbackWarnForTests(); const result = await findBrowser(); expect(result?.executablePath).toBe(directShell); expect(warnSpy).not.toHaveBeenCalled(); }); // Sibling env-var alias for the CLI resolver. The engine layer already // honors `PRODUCER_HEADLESS_SHELL_PATH` (see // `packages/engine/src/services/browserManager.ts`), and docs // (skills/hyperframes-registry/references/discovery.md, // packages/gcp-cloud-run/Dockerfile, examples/k8s-jobs/Dockerfile.example) // all instruct users to set that name. Before this alias, `hyperframes // check`/`snapshot`/`compare` — which all route through `openSettledCompositionPage` // → `ensureBrowser` → `findFromEnv` — silently ignored a documented escape // hatch that `render` had honored, so a user with a broken pinned build // (win32/x64 STATUS_STACK_BUFFER_OVERRUN 3221225595, #hyperframes-cli-feedback // ts=1784095034) could render successfully but check would still crash on // the cached headless-shell. The alias closes that direction of the // symmetry (the engine side is being closed by #2459). it("resolves via PRODUCER_HEADLESS_SHELL_PATH when HYPERFRAMES_BROWSER_PATH is unset", async () => { const directShell = "/opt/chrome-headless-shell/chrome-headless-shell"; installFsMocks({ existing: new Set([directShell]) }); installPuppeteerBrowsersMock(); process.env["PRODUCER_HEADLESS_SHELL_PATH"] = directShell; const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); const { findBrowser, _resetSystemFallbackWarnForTests } = await import("./manager.js"); _resetSystemFallbackWarnForTests(); const result = await findBrowser(); expect(result?.executablePath).toBe(directShell); expect(result?.source).toBe("env"); expect(warnSpy).not.toHaveBeenCalled(); }); it("prefers HYPERFRAMES_BROWSER_PATH over PRODUCER_HEADLESS_SHELL_PATH when both are set", async () => { // Tiebreak matches `render.ts` — the CLI-native name canonicalizes; the // engine name is a compatibility alias. If both are set the caller almost // certainly meant the CLI-native one. const hfPath = "/opt/hf/chrome-headless-shell"; const producerPath = "/opt/producer/chrome-headless-shell"; installFsMocks({ existing: new Set([hfPath, producerPath]) }); installPuppeteerBrowsersMock(); process.env["HYPERFRAMES_BROWSER_PATH"] = hfPath; process.env["PRODUCER_HEADLESS_SHELL_PATH"] = producerPath; const { findBrowser, _resetSystemFallbackWarnForTests } = await import("./manager.js"); _resetSystemFallbackWarnForTests(); const result = await findBrowser(); expect(result?.executablePath).toBe(hfPath); expect(result?.source).toBe("env"); }); it("does NOT warn on macOS when falling back to system Chrome", async () => { // macOS Chrome still works fine for the screenshot path and the perf // claims around BeginFrame are Linux-only — keep the warning Linux-scoped // so darwin users don't get spammed about a "fix" that doesn't apply. Object.defineProperty(process, "platform", { value: "darwin", configurable: true, }); const darwinChrome = "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"; installFsMocks({ existing: new Set([darwinChrome]) }); vi.doMock("@puppeteer/browsers", () => ({ Browser: { CHROMEHEADLESSSHELL: "chrome-headless-shell" }, detectBrowserPlatform: () => "mac_arm", getInstalledBrowsers: vi.fn().mockResolvedValue([]), install: vi.fn(), })); const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); const { findBrowser, _resetSystemFallbackWarnForTests } = await import("./manager.js"); _resetSystemFallbackWarnForTests(); const result = await findBrowser(); expect(result?.executablePath).toBe(darwinChrome); expect(warnSpy).not.toHaveBeenCalled(); }); it("only warns once across repeated findBrowser() calls", async () => { installFsMocks({ existing: new Set([SYSTEM_CHROME]) }); installPuppeteerBrowsersMock(); const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {}); const { findBrowser, _resetSystemFallbackWarnForTests } = await import("./manager.js"); _resetSystemFallbackWarnForTests(); await findBrowser(); await findBrowser(); await findBrowser(); expect(warnSpy).toHaveBeenCalledTimes(1); }); }); describe("isCorruptArchiveError", () => { it("matches truncated / corrupt archive extraction failures", async () => { const { isCorruptArchiveError } = await import("./manager.js"); for (const msg of [ "invalid end-of-central-directory record", "end of central directory record signature not found", "invalid or corrupt zip file", "File is not a zip file", "unexpected end of file", "the archive is corrupted", ]) { expect(isCorruptArchiveError(new Error(msg))).toBe(true); } }); it("does not match network or unrelated errors", async () => { const { isCorruptArchiveError } = await import("./manager.js"); for (const msg of ["ECONNRESET", "socket hang up", "ENOENT: no such file", "boom"]) { expect(isCorruptArchiveError(new Error(msg))).toBe(false); } }); }); describe("installWithCorruptArchiveRecovery", () => { it("clears the cache and re-downloads once on a corrupt archive, then succeeds", async () => { const { installWithCorruptArchiveRecovery } = await import("./manager.js"); const runInstall = vi .fn() .mockRejectedValueOnce(new Error("invalid end-of-central-directory record")) .mockResolvedValueOnce({ executablePath: "/ok" }); const clearCache = vi.fn(); const onRecover = vi.fn(); const result = await installWithCorruptArchiveRecovery(runInstall, clearCache, onRecover); expect(result).toEqual({ executablePath: "/ok" }); expect(runInstall).toHaveBeenCalledTimes(2); expect(clearCache).toHaveBeenCalledTimes(1); expect(onRecover).toHaveBeenCalledTimes(1); }); it("propagates a non-corruption error without clearing the cache", async () => { const { installWithCorruptArchiveRecovery } = await import("./manager.js"); const runInstall = vi.fn().mockRejectedValue(new Error("ECONNRESET")); const clearCache = vi.fn(); await expect(installWithCorruptArchiveRecovery(runInstall, clearCache)).rejects.toThrow( "ECONNRESET", ); expect(runInstall).toHaveBeenCalledTimes(1); expect(clearCache).not.toHaveBeenCalled(); }); it("does not retry forever: a second corruption propagates", async () => { const { installWithCorruptArchiveRecovery } = await import("./manager.js"); const runInstall = vi.fn().mockRejectedValue(new Error("end of central directory not found")); const clearCache = vi.fn(); await expect(installWithCorruptArchiveRecovery(runInstall, clearCache)).rejects.toThrow( "end of central directory", ); expect(runInstall).toHaveBeenCalledTimes(2); expect(clearCache).toHaveBeenCalledTimes(1); }); }); // Sibling failure mode to #2078 (SIGTRAP at launch): the field feedback in // #hyperframes-cli-feedback ts 1784055194.202169 (darwin/arm64, HF CLI 0.7.57) // hit `All providers failed for chrome-headless-shell 152.0.7928.2` at download // time and had to discover `HYPERFRAMES_BROWSER_PATH` on their own. The raw // error propagated straight through `downloadBrowser` without naming the // escape hatch. This guards the rewrap so the next reporter sees the hint. // // Parameterized across all three OS families because `browserPathHintForPlatform` // branches on `process.platform` and each branch has to survive on its own — // the field reporter was macOS but the same rewrap is what a Windows or Linux // (non-ARM) user would see next time providers fail, and each branch names a // different Chrome install path that has to be spelled correctly. describe("downloadBrowser — install failure surfaces HYPERFRAMES_BROWSER_PATH hint", () => { const origPlatform = process.platform; const origArch = process.arch; beforeEach(() => { vi.resetModules(); delete process.env["HYPERFRAMES_BROWSER_PATH"]; delete process.env["PRODUCER_HEADLESS_SHELL_PATH"]; installChildProcessMocks(); }); afterEach(() => { Object.defineProperty(process, "platform", { value: origPlatform, configurable: true, }); Object.defineProperty(process, "arch", { value: origArch, configurable: true, }); vi.restoreAllMocks(); vi.doUnmock("node:fs"); vi.doUnmock("node:os"); vi.doUnmock("node:child_process"); vi.doUnmock("@puppeteer/browsers"); }); // Note: linux/arm64 is deliberately excluded — `downloadBrowser` short-circuits // into `ensureLinuxArmBrowser` before it ever reaches the install() call this // suite guards (chrome-headless-shell has no linux-arm64 build; see `isLinuxArm` // at the top of `downloadBrowser`). Use linux/x64 to exercise the linux branch // of `browserPathHintForPlatform`. it.each([ { label: "darwin/arm64", platform: "darwin", arch: "arm64", expectedPathHint: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", }, { label: "win32/x64", platform: "win32", arch: "x64", expectedPathHint: "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe", }, { label: "linux/x64", platform: "linux", arch: "x64", expectedPathHint: "/usr/bin/google-chrome", }, ])( "rethrows a non-corrupt install failure with an HYPERFRAMES_BROWSER_PATH hint and preserves the original via cause ($label)", async ({ platform, arch, expectedPathHint }) => { Object.defineProperty(process, "platform", { value: platform, configurable: true, }); Object.defineProperty(process, "arch", { value: arch, configurable: true, }); // No cache, no system Chrome — forces the download-of-last-resort path // that ends in @puppeteer/browsers install(). installFsMocks({ existing: new Set([CACHE_ROOT]) }); const rawMsg = "All providers failed for chrome-headless-shell 152.0.7928.2"; const originalError = new Error(rawMsg); installPuppeteerBrowsersMock({ installedInHfCache: [], installImpl: async () => { throw originalError; }, }); const { ensureBrowser } = await import("./manager.js"); let caught: unknown; try { await ensureBrowser(); } catch (err) { caught = err; } expect(caught).toBeInstanceOf(Error); const msg = (caught as Error).message; // Names the escape-hatch env var by name (that's the entire point). expect(msg).toContain("HYPERFRAMES_BROWSER_PATH"); // Includes the platform-specific example path from // `browserPathHintForPlatform`. expect(msg).toContain(expectedPathHint); // Keeps the original provider-failure text so the user can still // diagnose the underlying cause from the surfaced message. expect(msg).toContain(rawMsg); // Structured `cause` chain intact for tooling that walks it. expect((caught as Error).cause).toBe(originalError); }, ); }); describe("downloadBrowser — too little disk for the browser", () => { beforeEach(() => { vi.resetModules(); delete process.env["HYPERFRAMES_BROWSER_PATH"]; delete process.env["PRODUCER_HEADLESS_SHELL_PATH"]; installChildProcessMocks(); }); afterEach(() => { vi.restoreAllMocks(); vi.doUnmock("node:fs"); vi.doUnmock("node:os"); vi.doUnmock("node:child_process"); vi.doUnmock("@puppeteer/browsers"); vi.doUnmock("../telemetry/system.js"); }); // On a disk that fills mid-unzip, unzip waits on a "Continue? (y/n)" nobody answers, holding the install lock. it.each([ { freeMb: 400, downloads: false }, { freeMb: 4096, downloads: true }, { freeMb: null, downloads: true }, ])("downloads only with room for it: $freeMb MB free", async ({ freeMb, downloads }) => { installFsMocks({ existing: new Set([CACHE_ROOT]) }); const install = vi.fn(async () => ({ executablePath: HF_BINARY })); installPuppeteerBrowsersMock({ installedInHfCache: [], installImpl: install }); const freeDiskMb = vi.fn((): number | null => freeMb); vi.doMock("../telemetry/system.js", async (importOriginal) => ({ ...(await importOriginal()), getFreeDiskMb: freeDiskMb, })); const { ensureBrowser } = await import("./manager.js"); const result = await ensureBrowser().catch((error: Error) => error); expect(freeDiskMb).toHaveBeenCalledWith(CACHE_ROOT); expect(install).toHaveBeenCalledTimes(downloads ? 1 : 0); if (downloads) expect(result).toMatchObject({ source: "download" }); else expect((result as Error).message).toMatch( /^Low disk space: .*needs about 512 MB.*400 MB free/, ); }); it("removes a killed install's leftovers before reading free space, so they never count against it", async () => { const home = useRealCacheHome(); installPuppeteerBrowsersMock({ installedInHfCache: [] }); const staging = join(home, ".cache", "hyperframes", ".chrome-staging-dead"); let leftoverWhenRead: boolean | undefined; vi.doMock("../telemetry/system.js", async (importOriginal) => ({ ...(await importOriginal()), getFreeDiskMb: () => { leftoverWhenRead = existsSync(staging); return 400; }, })); try { const { ensureBrowser, sweepKilledInstalls } = await import("./manager.js"); mkdirSync(join(staging, "partial"), { recursive: true }); await expect(ensureBrowser({ force: true })).rejects.toThrow(/^Low disk space/); expect(leftoverWhenRead).toBe(false); mkdirSync(join(staging, "partial"), { recursive: true }); await sweepKilledInstalls(); expect(existsSync(staging)).toBe(false); } finally { rmSync(home, { recursive: true, force: true }); } }); it.each([ { platform: "linux", unzipsFirst: true }, { platform: "darwin", unzipsFirst: true }, { platform: "win32", unzipsFirst: false }, ])( "on $platform, unzips the download itself first: $unzipsFirst", async ({ platform, unzipsFirst }) => { const home = useRealCacheHome(); const { platform: origPlatform, arch: origArch } = process; Object.defineProperty(process, "platform", { value: platform, configurable: true }); Object.defineProperty(process, "arch", { value: "x64", configurable: true }); const unzip = vi.fn(async () => true); installPuppeteerBrowsersMock({ unzip, installImpl: async ({ cacheDir, buildId }) => writeStagedInstall(cacheDir, buildId, "fresh"), }); try { const { ensureBrowser } = await import("./manager.js"); await ensureBrowser({ force: true }); if (!unzipsFirst) return expect(unzip).not.toHaveBeenCalled(); const [archive, into] = unzip.mock.calls[0] as unknown as [string, string]; expect(into).toBe(stagedVersionDir(dirname(archive), managedChromeVersion())); expect(basename(dirname(archive))).toMatch(/^\.chrome-staging-/); } finally { Object.defineProperty(process, "platform", { value: origPlatform, configurable: true }); Object.defineProperty(process, "arch", { value: origArch, configurable: true }); rmSync(home, { recursive: true, force: true }); } }, ); it("a disk that fills mid-unzip fails the install at once and leaves no staged copy", async () => { const home = useRealCacheHome(); const { platform: origPlatform, arch: origArch } = process; Object.defineProperty(process, "platform", { value: "linux", configurable: true }); Object.defineProperty(process, "arch", { value: "x64", configurable: true }); const install = vi.fn(async ({ cacheDir, buildId }: InstallMockOptions) => writeStagedInstall(cacheDir, buildId, "fresh"), ); installPuppeteerBrowsersMock({ installImpl: install, unzip: async () => { throw new Error("Extraction failed: the disk filled up while unpacking Chrome."); }, }); try { const { ensureBrowser } = await import("./manager.js"); await expect(ensureBrowser({ force: true })).rejects.toThrow("the disk filled up"); expect(install).not.toHaveBeenCalled(); const root = join(home, ".cache", "hyperframes"); expect(readdirSync(root).filter((name) => name.startsWith(".chrome-staging-"))).toEqual([]); } finally { Object.defineProperty(process, "platform", { value: origPlatform, configurable: true }); Object.defineProperty(process, "arch", { value: origArch, configurable: true }); rmSync(home, { recursive: true, force: true }); } }); }); // Regression guard for HF#2103: `hyperframes render` hung forever on macOS // (Apple Silicon) under Node >= 24.16. Root cause was NOT in this file — it was // the extractor `@puppeteer/browsers` <3.0.2 shells out to. That chain // (`@puppeteer/browsers` -> `extract-zip@2.0.1` -> `yauzl@2.10.0`) hits a // classic-stream backpressure regression (nodejs/node#63487) that surfaces a // latent fd-slicer `destroy()` bug in yauzl 2.x (yauzl#169): the inflate read // stream stalls partway through the first entry large enough to cross the write // highWaterMark, never emits `end`, and `stream.pipeline` never settles — so // extraction busy-spins forever, leaving a half-extracted cache with no // executable (puppeteer/puppeteer#14957). // // `@puppeteer/browsers` 3.0.2 dropped `extract-zip` as a dependency and now // extracts with `modern-tar` by default (`yauzl` lingers only as an optional // peer fallback — no longer a runtime dependency), which is the fix. This test // fails if a dependency change ever drags the pin back below 3.x — i.e. // reintroduces the broken extractor as a hard dependency. describe("@puppeteer/browsers pin (HF#2103 extractor-hang regression guard)", () => { it("stays on the major (>= 3) that dropped extract-zip and no longer depends on yauzl", async () => { const { createRequire } = await import("node:module"); const require = createRequire(import.meta.url); const pkg = require("@puppeteer/browsers/package.json") as { version: string; dependencies?: Record; }; const major = Number.parseInt(pkg.version.split(".")[0] ?? "0", 10); expect(major).toBeGreaterThanOrEqual(3); // Belt and suspenders: the durable fix is the *absence* of the broken // extractor, not just a version number, so assert it directly. const deps = pkg.dependencies ?? {}; expect(deps["extract-zip"]).toBeUndefined(); expect(deps["yauzl"]).toBeUndefined(); }); }); describe("browser resolution on macOS 12 (Darwin < 22)", () => { const MAC_12 = { platform: "darwin", release: "21.6.0" }; const MAC_13 = { platform: "darwin", release: "22.1.0" }; const OLD_BUILD = "150.0.7871.124"; const MAC_HF_BINARY = join(HF_CACHE, "chrome-headless-shell", "mac-x", "chrome-headless-shell"); const macPuppeteerBinary = (dir: string) => join(PUPPETEER_CACHE, dir, "chrome-headless-shell-mac-x64", "chrome-headless-shell"); const origPlatform = process.platform; const origArch = process.arch; beforeEach(() => { vi.resetModules(); delete process.env["HYPERFRAMES_BROWSER_PATH"]; delete process.env["PRODUCER_HEADLESS_SHELL_PATH"]; installChildProcessMocks(); Object.defineProperty(process, "platform", { value: "darwin", configurable: true, }); Object.defineProperty(process, "arch", { value: "x64", configurable: true, }); }); afterEach(() => { Object.defineProperty(process, "platform", { value: origPlatform, configurable: true, }); Object.defineProperty(process, "arch", { value: origArch, configurable: true, }); vi.unstubAllEnvs(); vi.doUnmock("node:fs"); vi.doUnmock("node:os"); vi.doUnmock("node:child_process"); vi.doUnmock("@puppeteer/browsers"); }); it.each([ { host: MAC_12, expected: OLD_BUILD }, { host: MAC_13, expected: "152.0.7977.30" }, ])("downloads $expected on $host.release", async ({ host, expected }) => { installFsMocks({ existing: new Set(), osHost: host }); const install = vi.fn(async () => ({ executablePath: MAC_HF_BINARY })); installPuppeteerBrowsersMock({ installImpl: install, browserPlatform: "mac", }); const { ensureBrowser } = await import("./manager.js"); await ensureBrowser({ preferManagedChrome: true }); expect(install).toHaveBeenCalledWith(expect.objectContaining({ buildId: expected })); }); it("ignores a cached newer managed build on macOS 12", async () => { installFsMocks({ existing: new Set([HF_CACHE, MAC_HF_BINARY]), osHost: MAC_12, }); installPuppeteerBrowsersMock({ browserPlatform: "mac", installedInHfCache: [ { browser: "chrome-headless-shell", executablePath: MAC_HF_BINARY, buildId: "152.0.7977.30", }, ], }); const { findBrowser } = await import("./manager.js"); await expect(findBrowser()).resolves.toBeUndefined(); }); it("uses the cached macOS 12 build on macOS 12", async () => { installFsMocks({ existing: new Set([HF_CACHE, MAC_HF_BINARY]), osHost: MAC_12, }); installPuppeteerBrowsersMock({ browserPlatform: "mac", installedInHfCache: [ { browser: "chrome-headless-shell", executablePath: MAC_HF_BINARY, buildId: OLD_BUILD, }, ], }); const { findBrowser } = await import("./manager.js"); await expect(findBrowser()).resolves.toEqual({ executablePath: MAC_HF_BINARY, source: "cache", }); }); it("skips a puppeteer-cache build newer than 150 on macOS 12 but keeps 150", async () => { installFsMocks({ existing: new Set([ PUPPETEER_CACHE, macPuppeteerBinary("mac-152.0.7977.30"), macPuppeteerBinary("mac-150.0.7871.124"), ]), dirs: { [PUPPETEER_CACHE]: ["mac-152.0.7977.30", "mac-150.0.7871.124"] }, osHost: MAC_12, }); installPuppeteerBrowsersMock({ browserPlatform: "mac" }); const { findBrowser } = await import("./manager.js"); await expect(findBrowser()).resolves.toEqual({ executablePath: macPuppeteerBinary("mac-150.0.7871.124"), source: "cache", }); }); it("keeps the pinned puppeteer-cache build on macOS 13", async () => { installFsMocks({ existing: new Set([ PUPPETEER_CACHE, macPuppeteerBinary("mac-152.0.7977.30"), macPuppeteerBinary("mac-150.0.7871.124"), ]), dirs: { [PUPPETEER_CACHE]: ["mac-152.0.7977.30", "mac-150.0.7871.124"] }, osHost: MAC_13, }); installPuppeteerBrowsersMock({ browserPlatform: "mac" }); const { findBrowser } = await import("./manager.js"); await expect(findBrowser()).resolves.toEqual({ executablePath: macPuppeteerBinary("mac-152.0.7977.30"), source: "cache", }); }); it("lets HYPERFRAMES_BROWSER_PATH win on macOS 12", async () => { const envBinary = join("/", "opt", "my-chrome"); vi.stubEnv("HYPERFRAMES_BROWSER_PATH", envBinary); installFsMocks({ existing: new Set([envBinary]), osHost: MAC_12 }); installPuppeteerBrowsersMock({ browserPlatform: "mac" }); const { ensureBrowser } = await import("./manager.js"); await expect(ensureBrowser({ preferManagedChrome: true })).resolves.toEqual({ executablePath: envBinary, source: "env", }); vi.unstubAllEnvs(); }); });