Skip to content

Commit 9b99605

Browse files
fix(engine): renders under WSL use the GPU through full Chrome when the headless shell cannot (#5574)
* fix(engine): renders under WSL use the GPU through full Chrome when the headless shell cannot Part of #5548. * fix(engine): a missing or unreadable full Chrome cache never stops a WSL render
1 parent abe97f6 commit 9b99605

8 files changed

Lines changed: 379 additions & 70 deletions

File tree

‎docs/guides/troubleshooting.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -249,6 +249,18 @@ sudo usermod -aG render $USER
249249
wsl --shutdown
250250
```
251251

252+
That alone may not be enough: on some drivers Chrome's headless shell, which
253+
HyperFrames installs, cannot reach the GPU under WSL while full Chrome can.
254+
Install full Chrome once; when the headless shell finds no GPU, HyperFrames tries
255+
it and renders with it if it reaches the GPU:
256+
257+
```bash
258+
npx @puppeteer/browsers install chrome@stable --path ~/.cache/puppeteer
259+
```
260+
261+
The log then shows `browserGpuMode probe → hardware (full Chrome: ...)`. To pick a
262+
full Chrome yourself, set `HYPERFRAMES_BROWSER_PATH` to its path.
263+
252264
If the GPU is still not used, render from Windows instead. Copy the project to
253265
a Windows drive (for example `C:\Users\you\renders\my-video`) and run the same
254266
command from PowerShell, where Chrome uses the graphics card through Direct3D:

‎packages/engine/src/services/browserManager.test.ts‎

Lines changed: 152 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,8 @@ import {
2727
releaseBrowser,
2828
resolveHeadlessShellPath,
2929
resolveBrowserGpuMode,
30+
resolveCaptureBrowserPath,
31+
resolveFullChromePath,
3032
} from "./browserManager.js";
3133

3234
describe("BeginFrame capability probe", () => {
@@ -481,6 +483,88 @@ describe("resolveBrowserGpuMode", () => {
481483
};
482484
const output = (spy: { mock: { calls: unknown[][] } }) =>
483485
spy.mock.calls.map((call) => String(call[0])).join("\n");
486+
const noFullChrome = () => undefined;
487+
const FULL_CHROME = "/home/u/.cache/puppeteer/chrome/linux-152/chrome-linux64/chrome";
488+
const SHELL_RENDERER = {
489+
hasWebGL: false,
490+
vendor: "",
491+
renderer: "",
492+
};
493+
const D3D12_RENDERER = {
494+
hasWebGL: true,
495+
vendor: "Google Inc. (Microsoft Corporation)",
496+
renderer:
497+
"ANGLE (Microsoft Corporation, D3D12 (NVIDIA GeForce RTX 4070 SUPER), OpenGL ES 3.1)",
498+
};
499+
/** The headless shell finds no GPU; full Chrome answers with `fullChromeInfo`. */
500+
const shellWithoutGpu = (fullChromeInfo: typeof D3D12_RENDERER) => {
501+
const launch = vi.fn(async (options: { executablePath?: string }) => ({
502+
newPage: vi.fn().mockResolvedValue({
503+
evaluate: vi
504+
.fn()
505+
.mockResolvedValue(
506+
options.executablePath === FULL_CHROME ? fullChromeInfo : SHELL_RENDERER,
507+
),
508+
}),
509+
close: vi.fn().mockResolvedValue(undefined),
510+
}));
511+
_setPuppeteerForTests({ launch } as unknown as PuppeteerNode);
512+
return launch;
513+
};
514+
const withFullChrome = {
515+
platform: "linux" as const,
516+
wslHost,
517+
chromePath: "/home/u/.cache/hyperframes/chrome/chrome-headless-shell",
518+
findFullChrome: () => FULL_CHROME,
519+
};
520+
521+
it("renders on full Chrome when the headless shell finds no GPU", async () => {
522+
const launch = shellWithoutGpu(D3D12_RENDERER);
523+
const error = vi.spyOn(console, "error").mockImplementation(() => {});
524+
expect(await resolveBrowserGpuMode("auto", withFullChrome)).toBe("hardware");
525+
expect(await resolveCaptureBrowserPath("hardware", { chromePath: "/shell" })).toBe(
526+
FULL_CHROME,
527+
);
528+
expect(launch.mock.calls.map(([options]) => options.executablePath)).toEqual([
529+
withFullChrome.chromePath,
530+
FULL_CHROME,
531+
]);
532+
const text = output(error);
533+
expect(text).toContain("browserGpuMode probe → hardware (full Chrome: WebGL renderer");
534+
expect(text).not.toContain("uses software");
535+
});
536+
537+
it("explicit 'hardware' takes the full Chrome route without warning", async () => {
538+
shellWithoutGpu(D3D12_RENDERER);
539+
vi.spyOn(console, "error").mockImplementation(() => {});
540+
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
541+
expect(await resolveBrowserGpuMode("hardware", withFullChrome)).toBe("hardware");
542+
expect(await resolveCaptureBrowserPath("hardware")).toBe(FULL_CHROME);
543+
expect(warn).not.toHaveBeenCalled();
544+
});
545+
546+
it("says full Chrome found no GPU either, and names native Windows", async () => {
547+
shellWithoutGpu(SHELL_RENDERER);
548+
const error = vi.spyOn(console, "error").mockImplementation(() => {});
549+
expect(await resolveBrowserGpuMode("auto", withFullChrome)).toBe("software");
550+
expect(await resolveCaptureBrowserPath("software", { chromePath: "/shell" })).toBe("/shell");
551+
const text = output(error);
552+
expect(text).toContain(`Full Chrome (${FULL_CHROME}) found no hardware GPU either.`);
553+
expect(text).toContain("native Windows");
554+
expect(text).not.toContain("@puppeteer/browsers install chrome");
555+
});
556+
557+
it("without full Chrome, says how to install it", async () => {
558+
shellWithoutGpu(D3D12_RENDERER);
559+
const error = vi.spyOn(console, "error").mockImplementation(() => {});
560+
expect(
561+
await resolveBrowserGpuMode("auto", { ...withFullChrome, findFullChrome: noFullChrome }),
562+
).toBe("software");
563+
expect(await resolveCaptureBrowserPath("hardware", { chromePath: "/shell" })).toBe("/shell");
564+
expect(output(error)).toContain(
565+
"npx @puppeteer/browsers install chrome@stable --path ~/.cache/puppeteer",
566+
);
567+
});
484568
const neverAnsweringProbe = () => {
485569
const launch = vi.fn().mockResolvedValue({
486570
newPage: vi.fn().mockResolvedValue({ evaluate: () => new Promise(() => {}) }),
@@ -494,8 +578,18 @@ describe("resolveBrowserGpuMode", () => {
494578
it("auto mode says it fell back to software, why, and the fix, once", async () => {
495579
setMockWebGlProbe({ hasWebGL: false, vendor: "", renderer: "" });
496580
const error = vi.spyOn(console, "error").mockImplementation(() => {});
497-
expect(await resolveBrowserGpuMode("auto", { platform: "linux", wslHost })).toBe("software");
498-
await resolveBrowserGpuMode("auto", { platform: "linux", wslHost });
581+
expect(
582+
await resolveBrowserGpuMode("auto", {
583+
platform: "linux",
584+
wslHost,
585+
findFullChrome: noFullChrome,
586+
}),
587+
).toBe("software");
588+
await resolveBrowserGpuMode("auto", {
589+
platform: "linux",
590+
wslHost,
591+
findFullChrome: noFullChrome,
592+
});
499593
const text = output(error);
500594
expect(text).toContain("browserGpuMode probe → software (WebGL unavailable)");
501595
expect(text).toContain(
@@ -511,7 +605,11 @@ describe("resolveBrowserGpuMode", () => {
511605
try {
512606
neverAnsweringProbe();
513607
const error = vi.spyOn(console, "error").mockImplementation(() => {});
514-
const mode = resolveBrowserGpuMode("auto", { platform: "linux", wslHost });
608+
const mode = resolveBrowserGpuMode("auto", {
609+
platform: "linux",
610+
wslHost,
611+
findFullChrome: noFullChrome,
612+
});
515613
await vi.advanceTimersByTimeAsync(15_000 + 250);
516614
await expect(mode).resolves.toBe("software");
517615
const text = output(error);
@@ -529,7 +627,11 @@ describe("resolveBrowserGpuMode", () => {
529627
neverAnsweringProbe();
530628
const error = vi.spyOn(console, "error").mockImplementation(() => {});
531629
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
532-
const mode = resolveBrowserGpuMode("hardware", { platform: "linux", wslHost });
630+
const mode = resolveBrowserGpuMode("hardware", {
631+
platform: "linux",
632+
wslHost,
633+
findFullChrome: noFullChrome,
634+
});
533635
await vi.advanceTimersByTimeAsync(15_000 + 250);
534636
await expect(mode).resolves.toBe("hardware");
535637
const warning = output(warn);
@@ -549,9 +651,13 @@ describe("resolveBrowserGpuMode", () => {
549651
} as unknown as PuppeteerNode);
550652
const error = vi.spyOn(console, "error").mockImplementation(() => {});
551653
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
552-
expect(await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost })).toBe(
553-
"hardware",
554-
);
654+
expect(
655+
await resolveBrowserGpuMode("hardware", {
656+
platform: "linux",
657+
wslHost,
658+
findFullChrome: noFullChrome,
659+
}),
660+
).toBe("hardware");
555661
const warning = output(warn);
556662
expect(warning).toContain("GPU probe could not run");
557663
expect(warning).toContain("hyperframes doctor");
@@ -563,9 +669,13 @@ describe("resolveBrowserGpuMode", () => {
563669
setMockWebGlProbe({ hasWebGL: false, vendor: "", renderer: "" });
564670
const error = vi.spyOn(console, "error").mockImplementation(() => {});
565671
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
566-
expect(await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost })).toBe(
567-
"hardware",
568-
);
672+
expect(
673+
await resolveBrowserGpuMode("hardware", {
674+
platform: "linux",
675+
wslHost,
676+
findFullChrome: noFullChrome,
677+
}),
678+
).toBe("hardware");
569679
const warning = output(warn);
570680
expect(warning).toContain("sudo usermod -aG render $USER");
571681
expect(warning).not.toContain("--gpus all");
@@ -579,11 +689,42 @@ describe("resolveBrowserGpuMode", () => {
579689
renderer: "ANGLE (Microsoft Corporation, D3D12 (Intel(R) Graphics), OpenGL ES 3.0)",
580690
});
581691
const error = vi.spyOn(console, "error").mockImplementation(() => {});
582-
expect(await resolveBrowserGpuMode("auto", { platform: "linux", wslHost })).toBe("hardware");
692+
expect(
693+
await resolveBrowserGpuMode("auto", {
694+
platform: "linux",
695+
wslHost,
696+
findFullChrome: noFullChrome,
697+
}),
698+
).toBe("hardware");
583699
expect(output(error)).not.toContain("WSL");
584700
});
585701
});
586702

703+
it("finds no full Chrome, without throwing, when its cache cannot be read", () => {
704+
const home = mkdtempSync(join(tmpdir(), "hf-full-chrome-cache-"));
705+
const saved = { HOME: process.env.HOME, USERPROFILE: process.env.USERPROFILE };
706+
try {
707+
mkdirSync(join(home, ".cache", "puppeteer"), { recursive: true });
708+
writeFileSync(join(home, ".cache", "puppeteer", "chrome"), "not a folder");
709+
Object.assign(process.env, { HOME: home, USERPROFILE: home });
710+
expect(resolveFullChromePath()).toBeUndefined();
711+
} finally {
712+
Object.assign(process.env, saved);
713+
rmSync(home, { recursive: true, force: true });
714+
}
715+
});
716+
717+
it("never swaps the browser outside WSL", async () => {
718+
setMockWebGlProbe({ hasWebGL: false, vendor: "", renderer: "" });
719+
vi.spyOn(console, "error").mockImplementation(() => {});
720+
const findFullChrome = vi.fn(() => "/full/chrome");
721+
expect(
722+
await resolveBrowserGpuMode("auto", { platform: "linux", wslHost: notWsl, findFullChrome }),
723+
).toBe("software");
724+
expect(findFullChrome).not.toHaveBeenCalled();
725+
expect(await resolveCaptureBrowserPath("hardware", { chromePath: "/shell" })).toBe("/shell");
726+
});
727+
587728
it("falls back to 'software' within the probe budget when the probe page never answers", async () => {
588729
vi.useFakeTimers();
589730
try {

0 commit comments

Comments
 (0)