2121 * `background-removal/manager.test.ts`) so we don't touch the real
2222 * `HOME` cache.
2323 */
24- import { join , sep } from "node:path" ;
24+ import { existsSync , mkdirSync , mkdtempSync , readFileSync , rmSync , writeFileSync } from "node:fs" ;
25+ import { tmpdir } from "node:os" ;
26+ import { dirname , join , relative , sep } from "node:path" ;
2527import { afterEach , beforeEach , describe , expect , it , vi } from "vitest" ;
2628import { managedChromeVersion } from "./manager.js" ;
2729
@@ -59,6 +61,27 @@ const TEST_LOCK_TIMINGS = {
5961 waitNoticeMs : 1_000 ,
6062} ;
6163
64+ // Points node:os homedir at a fresh temp dir so the manager runs against the real filesystem.
65+ function useRealCacheHome ( ) : string {
66+ const home = mkdtempSync ( join ( tmpdir ( ) , "hf-browser-cache-" ) ) ;
67+ vi . doMock ( "node:os" , async ( importOriginal ) => ( {
68+ ...( await importOriginal < typeof import ( "node:os" ) > ( ) ) ,
69+ homedir : ( ) => home ,
70+ } ) ) ;
71+ return home ;
72+ }
73+
74+ function writeStagedInstall ( cacheDir : string , buildId : string , content : string ) {
75+ const path = join ( cacheDir , "chrome-headless-shell" , `linux-${ buildId } ` ) ;
76+ const executablePath = join ( path , "chrome-headless-shell-linux64" , "chrome-headless-shell" ) ;
77+ mkdirSync ( dirname ( executablePath ) , { recursive : true } ) ;
78+ writeFileSync ( executablePath , content ) ;
79+ return { executablePath, path } ;
80+ }
81+
82+ // The mocked fs path set of the current test, so the install mock can stage files into it.
83+ let mockedPaths : Set < string > | undefined ;
84+
6285interface FsMockOptions {
6386 existing : ReadonlySet < string > ;
6487 /** map of dir path -> entries returned by readdirSync */
@@ -79,13 +102,18 @@ function installFsMocks({
79102 // Mutable, and returned, so tests can pre-seed a "lock already held" path or
80103 // assert the lock dir doesn't leak after ensureBrowser resolves.
81104 const paths = new Set ( existing ) ;
105+ mockedPaths = paths ;
82106 const mtimes = new Map ( [ ...existing ] . map ( ( p ) => [ p , initialMtimeMs ] ) ) ;
83107 const contents = new Map < string , string > ( ) ;
84108 vi . doMock ( "node:fs" , ( ) => ( {
85109 existsSync : ( p : string ) => paths . has ( p ) ,
86110 readdirSync : ( p : string ) => {
87111 const entries = dirs ?. [ p ] ;
88- if ( ! entries ) throw new Error ( `ENOENT: readdirSync mock had no entry for ${ p } ` ) ;
112+ if ( ! entries ) {
113+ const err = new Error ( `ENOENT: readdirSync mock had no entry for ${ p } ` ) ;
114+ ( err as NodeJS . ErrnoException ) . code = "ENOENT" ;
115+ throw err ;
116+ }
89117 return entries ;
90118 } ,
91119 mkdirSync : ( p : string , opts ?: { recursive ?: boolean } ) => {
@@ -109,6 +137,18 @@ function installFsMocks({
109137 }
110138 }
111139 } ,
140+ renameSync : ( from : string , to : string ) => {
141+ const moved = [ ...paths ] . filter ( ( p ) => p === from || p . startsWith ( from + sep ) ) ;
142+ if ( moved . length === 0 ) {
143+ const err = new Error ( `ENOENT: no such file or directory, rename '${ from } '` ) ;
144+ ( err as NodeJS . ErrnoException ) . code = "ENOENT" ;
145+ throw err ;
146+ }
147+ for ( const p of moved ) {
148+ paths . delete ( p ) ;
149+ paths . add ( to + p . slice ( from . length ) ) ;
150+ }
151+ } ,
112152 statSync : ( p : string ) => {
113153 if ( ! paths . has ( p ) ) {
114154 const err = new Error ( `ENOENT: no such file or directory, stat '${ p } '` ) ;
@@ -160,10 +200,25 @@ function installPuppeteerBrowsersMock(
160200 } > ;
161201 browserPlatform ?: string ;
162202 installedInHfCacheError ?: Error ;
163- installResult ?: { executablePath : string } ;
164- installImpl ?: ( options : { buildId : string } ) => Promise < { executablePath : string } > ;
203+ installResult ?: { executablePath : string ; path ?: string } ;
204+ installImpl ?: ( options : {
205+ buildId : string ;
206+ cacheDir : string ;
207+ } ) => Promise < { executablePath : string ; path ?: string } > ;
165208 } = { } ,
166209) {
210+ const impl =
211+ opts . installImpl ?? ( async ( ) => opts . installResult ?? { executablePath : HF_BINARY } ) ;
212+ // Fixtures name the binary where it lands in HF_CACHE; install() really writes it under its own cacheDir.
213+ const stagedInstall = async ( options : { buildId : string ; cacheDir : string } ) => {
214+ const result = await impl ( options ) ;
215+ if ( result . path || ! result . executablePath . startsWith ( HF_CACHE + sep ) ) return result ;
216+ const rel = relative ( HF_CACHE , result . executablePath ) ;
217+ const executablePath = join ( options . cacheDir , rel ) ;
218+ const path = join ( options . cacheDir , ...rel . split ( sep ) . slice ( 0 , 2 ) ) ;
219+ mockedPaths ?. add ( path ) . add ( executablePath ) ;
220+ return { executablePath, path } ;
221+ } ;
167222 vi . doMock ( "@puppeteer/browsers" , ( ) => ( {
168223 Browser : { CHROMEHEADLESSSHELL : "chrome-headless-shell" } ,
169224 detectBrowserPlatform : ( ) => opts . browserPlatform ?? "linux" ,
@@ -175,11 +230,7 @@ function installPuppeteerBrowsersMock(
175230 ...browser ,
176231 } ) ) ,
177232 ) ,
178- install : vi
179- . fn ( )
180- . mockImplementation (
181- opts . installImpl ?? ( async ( ) => opts . installResult ?? { executablePath : HF_BINARY } ) ,
182- ) ,
233+ install : vi . fn ( ) . mockImplementation ( stagedInstall ) ,
183234 } ) ) ;
184235}
185236
@@ -378,8 +429,9 @@ describe("findBrowser — cache resolution", () => {
378429 // The stale install DIR is present (extraction got partway through, e.g. an
379430 // ABOUT/LICENSE-only extract) even though the exe itself is missing —
380431 // exercises the purge-before-redownload fix, not just the redownload path.
432+ const staleLeftover = join ( staleInstallDir , "ABOUT" ) ;
381433 const paths = installFsMocks ( {
382- existing : new Set ( [ HF_CACHE , staleInstallDir ] ) ,
434+ existing : new Set ( [ HF_CACHE , staleInstallDir , staleLeftover ] ) ,
383435 } ) ;
384436 installPuppeteerBrowsersMock ( {
385437 installedInHfCache : [
@@ -402,13 +454,13 @@ describe("findBrowser — cache resolution", () => {
402454 source : "download" ,
403455 } ) ;
404456 expect ( warnSpy ) . toHaveBeenCalledWith ( expect . stringContaining ( "Cached binary missing" ) ) ;
405- // The stale directory must be gone before @puppeteer/browsers' install()
406- // sees it — otherwise install() throws "folder exists but exe missing"
407- // instead of re-extracting (the exact bug both feedback reports hit).
408- expect ( paths . has ( staleInstallDir ) ) . toBe ( false ) ;
457+ // The partial extract is replaced wholesale, not merged into ( install() would
458+ // otherwise throw "folder exists but exe missing", the bug both feedback reports hit).
459+ expect ( paths . has ( staleLeftover ) ) . toBe ( false ) ;
460+ expect ( paths . has ( redownloadedBinary ) ) . toBe ( true ) ;
409461 } ) ;
410462
411- it ( "ensureBrowser({force: true}) purges the whole cache before downloading , bypassing any cache/system shortcut" , async ( ) => {
463+ it ( "ensureBrowser({force: true}) re-downloads without purging the cache , bypassing any cache/system shortcut" , async ( ) => {
412464 const staleInstallDir = join ( HF_CACHE , "chrome-headless-shell" , "linux-131.0.6778.85" ) ;
413465 const downloadedBinary = join ( HF_CACHE , "chrome-headless-shell" , "force-downloaded" ) ;
414466 // A HEALTHY cached binary AND system Chrome are both present — force must
@@ -436,14 +488,88 @@ describe("findBrowser — cache resolution", () => {
436488 executablePath : downloadedBinary ,
437489 source : "download" ,
438490 } ) ;
439- // clearBrowser() wipes prior contents; withInstallLock uses a sibling lock
440- // outside CACHE_DIR, so assert the purge on what was actually INSIDE it,
441- // not the directory's own existence.
442- expect ( paths . has ( staleInstallDir ) ) . toBe ( false ) ;
443- expect ( paths . has ( HF_BINARY ) ) . toBe ( false ) ;
491+ // Only the downloaded version dir is swapped in; other cache entries stay.
492+ expect ( paths . has ( downloadedBinary ) ) . toBe ( true ) ;
493+ expect ( paths . has ( HF_BINARY ) ) . toBe ( true ) ;
494+ } ) ;
495+
496+ it ( "keeps a live reader's binary valid while a concurrent --force re-downloads it" , async ( ) => {
497+ const home = useRealCacheHome ( ) ;
498+ let label = "old" ;
499+ let seenMidInstall : string | undefined ;
500+ let liveBinary : string | undefined ;
501+ installPuppeteerBrowsersMock ( {
502+ installImpl : async ( { cacheDir, buildId } ) => {
503+ if ( liveBinary ) seenMidInstall = readFileSync ( liveBinary , "utf8" ) ;
504+ return writeStagedInstall ( cacheDir , buildId , label ) ;
505+ } ,
506+ } ) ;
507+ try {
508+ const { ensureBrowser, CACHE_DIR } = await import ( "./manager.js" ) ;
509+ const otherVersion = join ( CACHE_DIR , "chrome-headless-shell" , "linux-1.0.0" , "marker" ) ;
510+ mkdirSync ( dirname ( otherVersion ) , { recursive : true } ) ;
511+ writeFileSync ( otherVersion , "other" ) ;
512+
513+ liveBinary = ( await ensureBrowser ( { force : true } ) ) . executablePath ;
514+ label = "new" ;
515+ const forced = await ensureBrowser ( { force : true } ) ;
516+
517+ expect ( seenMidInstall ) . toBe ( "old" ) ;
518+ expect ( forced . executablePath ) . toBe ( liveBinary ) ;
519+ expect ( readFileSync ( liveBinary , "utf8" ) ) . toBe ( "new" ) ;
520+ expect ( readFileSync ( otherVersion , "utf8" ) ) . toBe ( "other" ) ;
521+ } finally {
522+ rmSync ( home , { recursive : true , force : true } ) ;
523+ }
524+ } ) ;
525+
526+ it ( "restores the previous version when the staged install cannot be moved in" , async ( ) => {
527+ const home = useRealCacheHome ( ) ;
528+ let stageNothing = false ;
529+ installPuppeteerBrowsersMock ( {
530+ installImpl : async ( { cacheDir, buildId } ) => {
531+ const staged = writeStagedInstall ( cacheDir , buildId , "old" ) ;
532+ if ( stageNothing ) rmSync ( staged . path , { recursive : true , force : true } ) ;
533+ return staged ;
534+ } ,
535+ } ) ;
536+ try {
537+ const { ensureBrowser } = await import ( "./manager.js" ) ;
538+ const liveBinary = ( await ensureBrowser ( { force : true } ) ) . executablePath ;
539+ stageNothing = true ;
540+
541+ await expect ( ensureBrowser ( { force : true } ) ) . rejects . toThrow ( "HYPERFRAMES_BROWSER_PATH" ) ;
542+ expect ( readFileSync ( liveBinary , "utf8" ) ) . toBe ( "old" ) ;
543+ } finally {
544+ rmSync ( home , { recursive : true , force : true } ) ;
545+ }
546+ } ) ;
547+
548+ it ( "sweeps dirs leaked by a killed install on the next install and on clear" , async ( ) => {
549+ const home = useRealCacheHome ( ) ;
550+ installPuppeteerBrowsersMock ( {
551+ installImpl : async ( { cacheDir, buildId } ) => writeStagedInstall ( cacheDir , buildId , "fresh" ) ,
552+ } ) ;
553+ const root = join ( home , ".cache" , "hyperframes" ) ;
554+ const leftovers = [ join ( root , ".chrome-staging-dead" ) , join ( root , ".chrome-replaced-dead" ) ] ;
555+ const seedLeftovers = ( ) => {
556+ for ( const dir of leftovers ) mkdirSync ( join ( dir , "partial" ) , { recursive : true } ) ;
557+ } ;
558+ try {
559+ const { ensureBrowser, clearBrowser } = await import ( "./manager.js" ) ;
560+ seedLeftovers ( ) ;
561+ await ensureBrowser ( { force : true } ) ;
562+ expect ( leftovers . filter ( ( dir ) => existsSync ( dir ) ) ) . toEqual ( [ ] ) ;
563+
564+ seedLeftovers ( ) ;
565+ expect ( clearBrowser ( ) ) . toBe ( true ) ;
566+ expect ( leftovers . filter ( ( dir ) => existsSync ( dir ) ) ) . toEqual ( [ ] ) ;
567+ } finally {
568+ rmSync ( home , { recursive : true , force : true } ) ;
569+ }
444570 } ) ;
445571
446- it ( "serializes concurrent force downloads so one purge cannot delete another installer's lock " , async ( ) => {
572+ it ( "serializes concurrent force downloads so they never install at the same time " , async ( ) => {
447573 const downloadedBinary = join ( HF_CACHE , "chrome-headless-shell" , "force-downloaded" ) ;
448574 const paths = installFsMocks ( {
449575 existing : new Set ( [ CACHE_ROOT , HF_CACHE , HF_BINARY ] ) ,
0 commit comments