Files
hyperframes/packages/cli/src/browser/manager.test.ts
T
Miguel Ángel fcec26ed5f fix(cli): a Chrome download that stops sending is abandoned, retried, and releases the lock (#6222)
* fix(cli): a Chrome download that stops sending is abandoned, retried, and releases the lock

* fix(cli): a stalled Chrome download is aborted at the socket so the process can exit

* fix(cli): the Chrome download runs in its own process and is killed when it stalls

* test(cli): ignore the expected socket reset in the download stall test on Windows
2026-10-24 17:53:54 +00:00

1777 lines
67 KiB
TypeScript

// 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<typeof import("node:os")>()),
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<string> | undefined;
interface FsMockOptions {
existing: ReadonlySet<string>;
/** map of dir path -> entries returned by readdirSync */
dirs?: Record<string, string[]>;
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<string>;
}
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<string, string>();
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<boolean>;
} = {},
) {
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<typeof import("../telemetry/system.js")>()),
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<typeof import("../telemetry/system.js")>()),
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<string, string>;
};
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();
});
});