@@ -369,6 +369,13 @@ describe("resolveBrowserGpuMode", () => {
369369 return { close, launch } ;
370370 } ;
371371
372+ const notWsl = {
373+ platform : "linux" as const ,
374+ release : "6.8.0-45-generic" ,
375+ readProcVersion : ( ) => "Linux version 6.8.0-45-generic" ,
376+ renderNodeAccess : ( ) => ( { state : "read-write" as const } ) ,
377+ } ;
378+
372379 beforeEach ( ( ) => {
373380 _resetAutoBrowserGpuModeCacheForTests ( ) ;
374381 } ) ;
@@ -414,15 +421,15 @@ describe("resolveBrowserGpuMode", () => {
414421 renderer : "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device))" ,
415422 } ) ;
416423 const warn = vi . spyOn ( console , "warn" ) . mockImplementation ( ( ) => { } ) ;
417- const mode = await resolveBrowserGpuMode ( "hardware" , { platform : "linux" } ) ;
424+ const mode = await resolveBrowserGpuMode ( "hardware" , { platform : "linux" , wslHost : notWsl } ) ;
418425 expect ( mode ) . toBe ( "hardware" ) ;
419426 const warning = warn . mock . calls . map ( ( call ) => String ( call [ 0 ] ) ) . join ( "\n" ) ;
420427 expect ( warning ) . toContain ( "browserGpuMode=hardware was requested" ) ;
421428 expect ( warning ) . toContain ( "--gpus all" ) ;
422429 // Once per process, not once per worker — the render path resolves the
423430 // mode for the probe browser plus every parallel worker.
424- await resolveBrowserGpuMode ( "hardware" , { platform : "linux" } ) ;
425- await resolveBrowserGpuMode ( "hardware" , { platform : "linux" } ) ;
431+ await resolveBrowserGpuMode ( "hardware" , { platform : "linux" , wslHost : notWsl } ) ;
432+ await resolveBrowserGpuMode ( "hardware" , { platform : "linux" , wslHost : notWsl } ) ;
426433 expect ( warn ) . toHaveBeenCalledTimes ( 1 ) ;
427434 } ) ;
428435
@@ -440,7 +447,9 @@ describe("resolveBrowserGpuMode", () => {
440447 renderer : "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device))" ,
441448 } ) ;
442449 const warn = vi . spyOn ( console , "warn" ) . mockImplementation ( ( ) => { } ) ;
443- expect ( await resolveBrowserGpuMode ( "hardware" , { platform : "darwin" } ) ) . toBe ( "hardware" ) ;
450+ expect ( await resolveBrowserGpuMode ( "hardware" , { platform : "darwin" , wslHost : notWsl } ) ) . toBe (
451+ "hardware" ,
452+ ) ;
444453 const warning = String ( warn . mock . calls [ 0 ] ?. [ 0 ] ) ;
445454 expect ( warning ) . toContain ( "host exposes a GPU" ) ;
446455 expect ( warning ) . not . toContain ( "--gpus all" ) ;
@@ -454,13 +463,127 @@ describe("resolveBrowserGpuMode", () => {
454463 launch : vi . fn ( ) . mockRejectedValue ( new Error ( "spawn ENOENT /bad/chrome" ) ) ,
455464 } as unknown as PuppeteerNode ) ;
456465 const warn = vi . spyOn ( console , "warn" ) . mockImplementation ( ( ) => { } ) ;
457- expect ( await resolveBrowserGpuMode ( "hardware" , { platform : "linux" } ) ) . toBe ( "hardware" ) ;
466+ expect ( await resolveBrowserGpuMode ( "hardware" , { platform : "linux" , wslHost : notWsl } ) ) . toBe (
467+ "hardware" ,
468+ ) ;
458469 const warning = String ( warn . mock . calls [ 0 ] ?. [ 0 ] ) ;
459470 expect ( warning ) . toContain ( "GPU probe could not run" ) ;
460471 expect ( warning ) . toContain ( "hyperframes doctor" ) ;
461472 expect ( warning ) . not . toContain ( "--gpus all" ) ;
462473 } ) ;
463474
475+ describe ( "under WSL (heygen-com/hyperframes#5548)" , ( ) => {
476+ const wslHost = {
477+ platform : "linux" as const ,
478+ release : "5.15.167.4-microsoft-standard-WSL2" ,
479+ readProcVersion : ( ) => "" ,
480+ renderNodeAccess : ( ) => ( { state : "denied" as const , group : "render" , userInGroup : false } ) ,
481+ } ;
482+ const output = ( spy : { mock : { calls : unknown [ ] [ ] } } ) =>
483+ spy . mock . calls . map ( ( call ) => String ( call [ 0 ] ) ) . join ( "\n" ) ;
484+ const neverAnsweringProbe = ( ) => {
485+ const launch = vi . fn ( ) . mockResolvedValue ( {
486+ newPage : vi . fn ( ) . mockResolvedValue ( { evaluate : ( ) => new Promise ( ( ) => { } ) } ) ,
487+ close : ( ) => new Promise ( ( ) => { } ) ,
488+ process : ( ) => ( { kill : vi . fn ( ) } ) ,
489+ disconnect : vi . fn ( ) . mockResolvedValue ( undefined ) ,
490+ } ) ;
491+ _setPuppeteerForTests ( { launch } as unknown as PuppeteerNode ) ;
492+ } ;
493+
494+ it ( "auto mode says it fell back to software, why, and the fix, once" , async ( ) => {
495+ setMockWebGlProbe ( { hasWebGL : false , vendor : "" , renderer : "" } ) ;
496+ const error = vi . spyOn ( console , "error" ) . mockImplementation ( ( ) => { } ) ;
497+ expect ( await resolveBrowserGpuMode ( "auto" , { platform : "linux" , wslHost } ) ) . toBe ( "software" ) ;
498+ await resolveBrowserGpuMode ( "auto" , { platform : "linux" , wslHost } ) ;
499+ const text = output ( error ) ;
500+ expect ( text ) . toContain ( "browserGpuMode probe → software (WebGL unavailable)" ) ;
501+ expect ( text ) . toContain (
502+ "WSL: the GPU check found no hardware GPU, so this render uses software" ,
503+ ) ;
504+ expect ( text ) . toContain ( 'is not in its group ("render")' ) ;
505+ expect ( text ) . toContain ( "sudo usermod -aG render $USER" ) ;
506+ expect ( text . match ( / u s e r m o d / g) ) . toHaveLength ( 1 ) ;
507+ } ) ;
508+
509+ it ( "auto mode says the check did not finish when the probe page times out" , async ( ) => {
510+ vi . useFakeTimers ( ) ;
511+ try {
512+ neverAnsweringProbe ( ) ;
513+ const error = vi . spyOn ( console , "error" ) . mockImplementation ( ( ) => { } ) ;
514+ const mode = resolveBrowserGpuMode ( "auto" , { platform : "linux" , wslHost } ) ;
515+ await vi . advanceTimersByTimeAsync ( 15_000 + 250 ) ;
516+ await expect ( mode ) . resolves . toBe ( "software" ) ;
517+ const text = output ( error ) ;
518+ expect ( text ) . toContain ( "did not answer within 15000ms" ) ;
519+ expect ( text ) . toContain ( "WSL: the GPU check could not finish" ) ;
520+ expect ( text ) . not . toContain ( "found no hardware GPU" ) ;
521+ } finally {
522+ vi . useRealTimers ( ) ;
523+ }
524+ } ) ;
525+
526+ it ( "explicit 'hardware' after a timeout stays unverified and never claims software" , async ( ) => {
527+ vi . useFakeTimers ( ) ;
528+ try {
529+ neverAnsweringProbe ( ) ;
530+ const error = vi . spyOn ( console , "error" ) . mockImplementation ( ( ) => { } ) ;
531+ const warn = vi . spyOn ( console , "warn" ) . mockImplementation ( ( ) => { } ) ;
532+ const mode = resolveBrowserGpuMode ( "hardware" , { platform : "linux" , wslHost } ) ;
533+ await vi . advanceTimersByTimeAsync ( 15_000 + 250 ) ;
534+ await expect ( mode ) . resolves . toBe ( "hardware" ) ;
535+ const warning = output ( warn ) ;
536+ expect ( warning ) . toContain ( "hardware acceleration is UNVERIFIED" ) ;
537+ expect ( warning ) . toContain ( "hyperframes doctor" ) ;
538+ expect ( warning ) . toContain ( "sudo usermod -aG render $USER" ) ;
539+ expect ( warning ) . not . toContain ( "found no hardware GPU" ) ;
540+ expect ( output ( error ) ) . not . toContain ( "this render uses software" ) ;
541+ } finally {
542+ vi . useRealTimers ( ) ;
543+ }
544+ } ) ;
545+
546+ it ( "explicit 'hardware' with a broken Chrome keeps the Chrome-install advice" , async ( ) => {
547+ _setPuppeteerForTests ( {
548+ launch : vi . fn ( ) . mockRejectedValue ( new Error ( "spawn ENOENT /bad/chrome" ) ) ,
549+ } as unknown as PuppeteerNode ) ;
550+ const error = vi . spyOn ( console , "error" ) . mockImplementation ( ( ) => { } ) ;
551+ const warn = vi . spyOn ( console , "warn" ) . mockImplementation ( ( ) => { } ) ;
552+ expect ( await resolveBrowserGpuMode ( "hardware" , { platform : "linux" , wslHost } ) ) . toBe (
553+ "hardware" ,
554+ ) ;
555+ const warning = output ( warn ) ;
556+ expect ( warning ) . toContain ( "GPU probe could not run" ) ;
557+ expect ( warning ) . toContain ( "hyperframes doctor" ) ;
558+ expect ( warning ) . not . toContain ( "--gpus all" ) ;
559+ expect ( output ( error ) ) . not . toContain ( "this render uses software" ) ;
560+ } ) ;
561+
562+ it ( "explicit 'hardware' with no hardware GPU gives the WSL fix, not Docker passthrough" , async ( ) => {
563+ setMockWebGlProbe ( { hasWebGL : false , vendor : "" , renderer : "" } ) ;
564+ const error = vi . spyOn ( console , "error" ) . mockImplementation ( ( ) => { } ) ;
565+ const warn = vi . spyOn ( console , "warn" ) . mockImplementation ( ( ) => { } ) ;
566+ expect ( await resolveBrowserGpuMode ( "hardware" , { platform : "linux" , wslHost } ) ) . toBe (
567+ "hardware" ,
568+ ) ;
569+ const warning = output ( warn ) ;
570+ expect ( warning ) . toContain ( "sudo usermod -aG render $USER" ) ;
571+ expect ( warning ) . not . toContain ( "--gpus all" ) ;
572+ expect ( output ( error ) ) . not . toContain ( "this render uses software" ) ;
573+ } ) ;
574+
575+ it ( "stays quiet when WSL hands Chrome a hardware GPU" , async ( ) => {
576+ setMockWebGlProbe ( {
577+ hasWebGL : true ,
578+ vendor : "Google Inc. (Microsoft Corporation)" ,
579+ renderer : "ANGLE (Microsoft Corporation, D3D12 (Intel(R) Graphics), OpenGL ES 3.0)" ,
580+ } ) ;
581+ const error = vi . spyOn ( console , "error" ) . mockImplementation ( ( ) => { } ) ;
582+ expect ( await resolveBrowserGpuMode ( "auto" , { platform : "linux" , wslHost } ) ) . toBe ( "hardware" ) ;
583+ expect ( output ( error ) ) . not . toContain ( "WSL" ) ;
584+ } ) ;
585+ } ) ;
586+
464587 it ( "falls back to 'software' within the probe budget when the probe page never answers" , async ( ) => {
465588 vi . useFakeTimers ( ) ;
466589 try {
0 commit comments