Skip to content

Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.

fix: recover from browser startup failures (#6135)

Oleg Isonen05118e0f2266
diff --git a/packages/cli/src/commands/mcp-preview.test.ts b/packages/cli/src/commands/mcp-preview.test.ts
index 0530bf027b..bff2a1797e 100644
--- a/packages/cli/src/commands/mcp-preview.test.ts
+++ b/packages/cli/src/commands/mcp-preview.test.ts
@@ -1,4 +1,10 @@
import { expect, test, vi } from "vitest";
+import { BrowserStartupError } from "@webstudio-is/vision/browser";
+import {
+ createScreenshotCaptureSession,
+ defaultScreenshotDependencies,
+ type ScreenshotDependencies,
+} from "../screenshot";
import {
createMcpPreviewHandlers,
createPreviewFreshness,
@@ -684,6 +690,86 @@ test("times out a stalled screenshot after preview start and releases its sessio
expect(stop).toHaveBeenCalledOnce();
});
+test("leaves time to start a fallback browser within the MCP timeout", async () => {
+ const createBrowserScreenshotSession = vi.fn(async (options) => {
+ if (options.browserPath === "/usr/bin/chromium") {
+ await new Promise((resolve) =>
+ setTimeout(resolve, options.startupTimeout ?? options.timeout)
+ );
+ throw new BrowserStartupError("Chromium startup timed out.");
+ }
+ return {
+ capture: vi.fn(async () => ({
+ navigation: {
+ requestedUrl: options.url,
+ finalUrl: options.url,
+ redirects: [],
+ documentReadyState: "complete" as const,
+ pageMetadata: { rootMarkerPresent: true },
+ layoutStable: true,
+ },
+ viewportWidth: options.width,
+ viewportHeight: options.height,
+ contentWidth: options.width,
+ contentHeight: options.height,
+ horizontalOverflow: false,
+ })),
+ capturePage: vi.fn(async () => []),
+ close: vi.fn(async () => undefined),
+ };
+ });
+ const dependencies: ScreenshotDependencies = {
+ ...defaultScreenshotDependencies,
+ env: {},
+ platform: "linux",
+ access: vi.fn(async (path) => {
+ if (path === "/usr/bin/chromium" || path === "/usr/bin/google-chrome") {
+ return;
+ }
+ throw new Error("missing");
+ }),
+ which: vi.fn(async (command) => {
+ if (command === "chromium") {
+ return "/usr/bin/chromium";
+ }
+ if (command === "google-chrome") {
+ return "/usr/bin/google-chrome";
+ }
+ }),
+ getChromeLauncherInstallations: vi.fn(() => []),
+ getPlaywrightInstallations: vi.fn(async () => []),
+ mkdir: vi.fn(async () => undefined),
+ createBrowserScreenshotSession,
+ readArtifactByte: vi.fn(async () => 1),
+ };
+ const preview = {
+ status: vi.fn(() => ({
+ url: "http://127.0.0.1:3000/",
+ running: true,
+ mode: "iterative" as const,
+ })),
+ startAndWait: vi.fn(),
+ resolveUrl: vi.fn((path: string) => `http://127.0.0.1:3000${path}`),
+ };
+ const handlers = createMcpPreviewHandlers({
+ preview,
+ isStale: () => false,
+ createCaptureSession: () => createScreenshotCaptureSession(dependencies),
+ });
+
+ await expect(
+ handlers.captureScreenshot({
+ path: "/",
+ source: "session",
+ viewport: { width: 800, height: 600 },
+ timeout: 200,
+ })
+ ).resolves.toMatchObject({
+ browser: { path: "/usr/bin/google-chrome" },
+ });
+ expect(createBrowserScreenshotSession).toHaveBeenCalledTimes(2);
+});
+
test("applies internal page credentials only to owned preview captures", async () => {
const preview = {
status: vi.fn(() => ({
diff --git a/packages/cli/src/screenshot.test.ts b/packages/cli/src/screenshot.test.ts
index d3c01bc1a8..da40efea88 100644
--- a/packages/cli/src/screenshot.test.ts
+++ b/packages/cli/src/screenshot.test.ts
@@ -4,6 +4,7 @@ import { Buffer } from "node:buffer";
import { mkdir, mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
+import { BrowserStartupError } from "@webstudio-is/vision/browser";
import {
BrowserNotFoundError,
BrowserInstallUnavailableError,
@@ -53,6 +54,39 @@ const createDependencies = (
...overrides,
});
+const chromiumPath = "/usr/bin/chromium";
+const chromePath = "/usr/bin/google-chrome";
+
+const createDiscoveredBrowserDependencies = (
+ overrides: Partial<ScreenshotDependencies> = {}
+) =>
+ createDependencies({
+ access: vi.fn(async (path) => {
+ if (path === chromiumPath || path === chromePath) {
+ return;
+ }
+ throw new Error("missing");
+ }),
+ which: vi.fn(async (command) => {
+ if (command === "chromium") {
+ return chromiumPath;
+ }
+ if (command === "google-chrome") {
+ return chromePath;
+ }
+ }),
+ ...overrides,
+ });
+
+const getBrowserStartupFailureMessage = (
+ getFailure: (path: string) => string
+) =>
+ [
+ "Unable to start any discovered Chromium-family browser.",
+ `- chromium (path): ${chromiumPath}: ${getFailure(chromiumPath)}`,
+ `- chrome (path): ${chromePath}: ${getFailure(chromePath)}`,
+ ].join("\n");
+
const genericNavigation = {
requestedUrl: "https://example.com",
finalUrl: "https://example.com/home",
@@ -256,6 +290,38 @@ describe("resolveScreenshotBrowser", () => {
]),
});
});
+
+ test("does not discover a fallback for an explicit browser path", async () => {
+ const captureBrowserScreenshot = vi.fn(async () => undefined);
+ const dependencies = createDependencies({
+ access: vi.fn(async (path) => {
+ if (path === "/usr/bin/google-chrome") {
+ return;
+ }
+ throw new Error("missing");
+ }),
+ which: vi.fn(async (command) =>
+ command === "google-chrome" ? "/usr/bin/google-chrome" : undefined
+ ),
+ captureBrowserScreenshot,
+ });
+
+ await expect(
+ captureScreenshot(
+ {
+ url: "https://example.com",
+ width: 800,
+ height: 600,
+ browser: "auto",
+ browserPath: "/missing/chromium",
+ },
+ dependencies
+ )
+ ).rejects.toMatchObject({
+ checked: ["/missing/chromium"],
+ });
+ expect(captureBrowserScreenshot).not.toHaveBeenCalled();
+ });
});
describe("OCR installation", () => {
@@ -342,6 +408,41 @@ test("formats actionable browser installation guidance", () => {
});
describe("captureScreenshot", () => {
+ test("falls back when the preferred browser fails during startup", async () => {
+ const captureBrowserScreenshot = vi.fn(async ({ browserPath }) => {
+ if (browserPath === "/usr/bin/chromium") {
+ throw new BrowserStartupError("Chromium exited with signal SIGABRT.");
+ }
+ return undefined;
+ });
+ const dependencies = createDependencies({
+ which: vi.fn(async (command) => {
+ if (command === "chromium") {
+ return "/usr/bin/chromium";
+ }
+ if (command === "google-chrome") {
+ return "/usr/bin/google-chrome";
+ }
+ }),
+ captureBrowserScreenshot,
+ });
+
+ await expect(
+ captureScreenshot(
+ {
+ url: "https://example.com",
+ width: 800,
+ height: 600,
+ browser: "auto",
+ },
+ dependencies
+ )
+ ).resolves.toMatchObject({
+ browser: { path: "/usr/bin/google-chrome" },
+ });
+ expect(captureBrowserScreenshot).toHaveBeenCalledTimes(2);
+ });
+
test("captures with browser readiness defaults", async () => {
const captureBrowserScreenshot = vi.fn(async () => ({
navigation: genericNavigation,
@@ -415,6 +516,7 @@ describe("captureScreenshot", () => {
waitForSelector: undefined,
waitForTimeout: 250,
timeout: 30000,
+ startupTimeout: 10000,
});
expect(dependencies.mkdir).toHaveBeenCalledWith(tmpdir(), {
recursive: true,
@@ -579,7 +681,7 @@ test("maps page metadata from reusable capture sessions", async () => {
await session.close();
});
-test("resets a reusable capture session after browser startup rejects", async () => {
+test("reports failed browser startup without relaunching the same executable", async () => {
const spawnBrowser = vi.fn(() => ({
kill: vi.fn(() => true),
once: vi.fn((event: string, listener: (error: Error) => void) => {
@@ -589,6 +691,12 @@ test("resets a reusable capture session after browser startup rejects", async ()
}),
}));
const dependencies = createDependencies({
+ access: vi.fn(async (path) => {
+ if (path === "/usr/bin/chromium") {
+ return;
+ }
+ throw new Error("missing");
+ }),
which: vi.fn(async (command) =>
command === "chromium" ? "/usr/bin/chromium" : undefined
),
@@ -603,14 +711,151 @@ test("resets a reusable capture session after browser startup rejects", async ()
timeout: 100,
};
- await expect(session.capture(options)).rejects.toThrow(
- "Browser exited before its DevTools endpoint became ready."
+ await expect(session.capture(options)).rejects.toMatchObject({
+ code: "BROWSER_STARTUP_FAILED",
+ message: expect.stringContaining("/usr/bin/chromium"),
+ });
+ await expect(session.capture(options)).rejects.toMatchObject({
+ code: "BROWSER_STARTUP_FAILED",
+ message: expect.stringContaining("/usr/bin/chromium"),
+ });
+ await session.close();
+ expect(spawnBrowser).toHaveBeenCalledTimes(2);
+});
+
+test.each(["capture", "capturePage"] as const)(
+ "falls back for %s when the preferred browser exits during startup",
+ async (method) => {
+ const browserSession = {
+ capture: vi.fn(),
+ capturePage: vi.fn(async () => [
+ {
+ navigation: genericNavigation,
+ viewportWidth: 800,
+ viewportHeight: 600,
+ contentWidth: 800,
+ contentHeight: 600,
+ horizontalOverflow: false,
+ },
+ ]),
+ close: vi.fn(async () => undefined),
+ };
+ const createBrowserScreenshotSession = vi.fn(async (options) => {
+ if (options.browserPath === "/usr/bin/chromium") {
+ throw new BrowserStartupError(
+ "Browser exited before its DevTools endpoint became ready (signal SIGABRT)."
+ );
+ }
+ return browserSession;
+ });
+ const dependencies = createDiscoveredBrowserDependencies({
+ createBrowserScreenshotSession,
+ });
+ const session = createScreenshotCaptureSession(dependencies);
+
+ const options = {
+ url: "https://example.com",
+ width: 800,
+ height: 600,
+ browser: "auto" as const,
+ };
+ const result =
+ method === "capture"
+ ? await session.capture(options)
+ : (await session.capturePage([options]))[0];
+
+ expect(result.browser.path).toBe(chromePath);
+ expect(createBrowserScreenshotSession).toHaveBeenCalledTimes(2);
+ await session.close();
+ }
+);
+
+test("does not start a fallback browser for an explicit browser path", async () => {
+ const createBrowserScreenshotSession = vi.fn(async () => {
+ throw new BrowserStartupError("Chromium exited with signal SIGABRT.");
+ });
+ const dependencies = createDependencies({
+ which: vi.fn(async (command) =>
+ command === "google-chrome" ? "/usr/bin/google-chrome" : undefined
+ ),
+ createBrowserScreenshotSession,
+ });
+ const session = createScreenshotCaptureSession(dependencies);
+
+ await expect(
+ session.capture({
+ url: "https://example.com",
+ width: 800,
+ height: 600,
+ browser: "auto",
+ browserPath: "/usr/bin/chromium",
+ })
+ ).rejects.toMatchObject({
+ code: "BROWSER_STARTUP_FAILED",
+ message: expect.stringContaining("/usr/bin/chromium"),
+ });
+ expect(createBrowserScreenshotSession).toHaveBeenCalledTimes(1);
+ await session.close();
+});
+
+test("reports every browser that failed during startup", async () => {
+ const createBrowserScreenshotSession = vi.fn(async (options) => {
+ throw new BrowserStartupError(
+ `Startup timed out for ${options.browserPath}`
+ );
+ });
+ const dependencies = createDiscoveredBrowserDependencies({
+ createBrowserScreenshotSession,
+ });
+ const session = createScreenshotCaptureSession(dependencies);
+
+ await expect(
+ session.capture({
+ url: "https://example.com",
+ width: 800,
+ height: 600,
+ browser: "auto",
+ })
+ ).rejects.toMatchObject({
+ code: "BROWSER_STARTUP_FAILED",
+ message: getBrowserStartupFailureMessage(
+ (path) => `Startup timed out for ${path}`
+ ),
+ });
+ expect(createBrowserScreenshotSession).toHaveBeenCalledTimes(2);
+ await session.close();
+});
+
+test("reports concurrent browser startup failures once per executable", async () => {
+ const createBrowserScreenshotSession = vi.fn(async (options) => {
+ throw new BrowserStartupError(`Startup failed for ${options.browserPath}`);
+ });
+ const dependencies = createDiscoveredBrowserDependencies({
+ createBrowserScreenshotSession,
+ });
+ const session = createScreenshotCaptureSession(dependencies);
+ const options = {
+ url: "https://example.com",
+ width: 800,
+ height: 600,
+ browser: "auto" as const,
+ };
+
+ const results = await Promise.allSettled([
+ session.capture(options),
+ session.capture(options),
+ ]);
+ const messages = results.map((result) =>
+ result.status === "rejected" && result.reason instanceof Error
+ ? result.reason.message
+ : undefined
);
- await expect(session.capture(options)).rejects.toThrow(
- "Browser exited before its DevTools endpoint became ready."
+ const failureMessage = getBrowserStartupFailureMessage(
+ (path) => `Startup failed for ${path}`
);
+ expect(messages).toEqual([failureMessage, failureMessage]);
+ expect(createBrowserScreenshotSession).toHaveBeenCalledTimes(2);
await session.close();
- expect(spawnBrowser).toHaveBeenCalledTimes(4);
});
test("does not create a browser session after cleanup during discovery", async () => {
diff --git a/packages/cli/src/screenshot.ts b/packages/cli/src/screenshot.ts
index ffc23e8ff5..5fcc229d18 100644
--- a/packages/cli/src/screenshot.ts
+++ b/packages/cli/src/screenshot.ts
@@ -6,6 +6,7 @@ import { spawn } from "node:child_process";
import { Launcher } from "chrome-launcher";
import which from "which";
import {
+ defaultBrowserStartupTimeout,
defaultScreenshotTimeout,
defaultScreenshotWaitForTimeout,
defaultScreenshotWaitUntil,
@@ -13,6 +14,7 @@ import {
type ScreenshotWaitUntil,
} from "@webstudio-is/vision/browser";
import {
+ BrowserStartupError,
captureBrowserScreenshot,
createBrowserScreenshotSession as createVisionBrowserScreenshotSession,
defaultBrowserScreenshotDependencies,
@@ -358,14 +360,13 @@ const uniqueCandidates = (candidates: readonly BrowserCandidate[]) => {
});
};
-export const resolveScreenshotBrowser = async (
+const getScreenshotBrowserCandidates = async (
options: {
browser: ScreenshotBrowser;
browserPath?: string;
},
- dependencies = defaultScreenshotDependencies
-): Promise<BrowserCandidate> => {
- const checked: string[] = [];
+ dependencies: ScreenshotDependencies
+) => {
const candidates: BrowserCandidate[] = [];
if (options.browserPath !== undefined) {
@@ -377,6 +378,7 @@ export const resolveScreenshotBrowser = async (
? inferBrowser(options.browserPath)
: options.browser,
});
+ return candidates;
}
const envBrowserPath = dependencies.env.WEBSTUDIO_BROWSER_PATH;
@@ -432,7 +434,25 @@ export const resolveScreenshotBrowser = async (
)
);
- for (const candidate of uniqueCandidates(candidates)) {
+ return uniqueCandidates(candidates);
+};
+
+const resolveScreenshotBrowserCandidate = async (
+ options: {
+ browser: ScreenshotBrowser;
+ browserPath?: string;
+ },
+ dependencies: ScreenshotDependencies,
+ excludedPaths: ReadonlySet<string>
+): Promise<BrowserCandidate> => {
+ const checked: string[] = [];
+ for (const candidate of await getScreenshotBrowserCandidates(
+ options,
+ dependencies
+ )) {
+ if (excludedPaths.has(candidate.path)) {
+ continue;
+ }
checked.push(candidate.path);
if (await isExecutable(candidate.path, dependencies)) {
return candidate;
@@ -442,6 +462,15 @@ export const resolveScreenshotBrowser = async (
throw new BrowserNotFoundError(checked);
};
+export const resolveScreenshotBrowser = async (
+ options: {
+ browser: ScreenshotBrowser;
+ browserPath?: string;
+ },
+ dependencies = defaultScreenshotDependencies
+): Promise<BrowserCandidate> =>
+ await resolveScreenshotBrowserCandidate(options, dependencies, new Set());
+
export const getNoBrowserFoundMessage = (checked: readonly string[]) =>
[
"No supported Chromium browser was found.",
@@ -648,27 +677,34 @@ const getBrowserScreenshotOptions = (
browserPath: string,
output: string,
dependencies: ScreenshotDependencies
-): BrowserScreenshotOptions => ({
- browserPath,
- output,
- width: options.width,
- height: options.height,
- fullPage: options.fullPage,
- includeImageMetrics: options.includeImageMetrics,
- includeResourceMetrics: options.includeResourceMetrics,
- includeContrastMetrics: options.includeContrastMetrics,
- ...webstudioPageInstrumentation,
- url: options.url,
- httpCredentials: options.httpCredentials,
- uid: dependencies.getuid(),
- waitUntil: options.waitUntil ?? defaultScreenshotWaitUntil,
- waitForSelector: options.waitForSelector,
- waitForTimeout: options.waitForTimeout ?? defaultScreenshotWaitForTimeout,
- timeout: options.timeout ?? defaultScreenshotTimeout,
- format: options.format,
- quality: options.quality,
- scale: options.scale,
-});
+): BrowserScreenshotOptions => {
+ const timeout = options.timeout ?? defaultScreenshotTimeout;
+ return {
+ browserPath,
+ output,
+ width: options.width,
+ height: options.height,
+ fullPage: options.fullPage,
+ includeImageMetrics: options.includeImageMetrics,
+ includeResourceMetrics: options.includeResourceMetrics,
+ includeContrastMetrics: options.includeContrastMetrics,
+ ...webstudioPageInstrumentation,
+ url: options.url,
+ httpCredentials: options.httpCredentials,
+ uid: dependencies.getuid(),
+ waitUntil: options.waitUntil ?? defaultScreenshotWaitUntil,
+ waitForSelector: options.waitForSelector,
+ waitForTimeout: options.waitForTimeout ?? defaultScreenshotWaitForTimeout,
+ timeout,
+ startupTimeout: Math.max(
+ 1,
+ Math.min(defaultBrowserStartupTimeout, Math.floor(timeout / 2))
+ ),
+ format: options.format,
+ quality: options.quality,
+ scale: options.scale,
+ };
+};
const validateScreenshotArtifact = async (
output: string,
@@ -744,40 +780,104 @@ const captureResolvedScreenshot = async (
export const captureScreenshot = async (
options: CaptureScreenshotOptions,
dependencies = defaultScreenshotDependencies
-) => {
- const browser = await resolveScreenshotBrowser(options, dependencies);
- return await captureResolvedScreenshot(options, browser, dependencies);
+) =>
+ await withBrowserStartupFallback({
+ options,
+ dependencies,
+ state: createBrowserStartupState(),
+ attempt: async (browser) =>
+ await captureResolvedScreenshot(options, browser, dependencies),
+ });
+
+const createBrowserStartupError = (
+ failures: readonly { browser: BrowserCandidate; error: unknown }[]
+) =>
+ Object.assign(
+ new BrowserStartupError(
+ [
+ "Unable to start any discovered Chromium-family browser.",
+ ...failures.map(
+ ({ browser, error }) =>
+ `- ${browser.browser} (${browser.source}): ${browser.path}: ${error instanceof Error ? error.message : String(error)}`
+ ),
+ ].join("\n")
+ ),
+ {
+ attempts: failures.map(({ browser }) => browser),
+ }
+ );
+
+type BrowserStartupState = {
+ failedPaths: Set<string>;
+ failures: Array<{ browser: BrowserCandidate; error: unknown }>;
+};
+
+const createBrowserStartupState = (): BrowserStartupState => ({
+ failedPaths: new Set(),
+ failures: [],
+});
+
+const withBrowserStartupFallback = async <Result>({
+ options,
+ dependencies,
+ state,
+ attempt,
+ validateBrowser,
+ isCancelled = () => false,
+}: {
+ options: CaptureScreenshotOptions;
+ dependencies: ScreenshotDependencies;
+ state: BrowserStartupState;
+ attempt: (browser: BrowserCandidate) => Promise<Result>;
+ validateBrowser?: (browser: BrowserCandidate) => void;
+ isCancelled?: () => boolean;
+}): Promise<Result> => {
+ while (true) {
+ let browser: BrowserCandidate;
+ try {
+ browser = await resolveScreenshotBrowserCandidate(
+ options,
+ dependencies,
+ state.failedPaths
+ );
+ } catch (error) {
+ if (error instanceof BrowserNotFoundError && state.failures.length > 0) {
+ throw createBrowserStartupError(state.failures);
+ }
+ throw error;
+ }
+ validateBrowser?.(browser);
+ try {
+ return await attempt(browser);
+ } catch (error) {
+ if (error instanceof BrowserStartupError === false || isCancelled()) {
+ throw error;
+ }
+ if (state.failedPaths.has(browser.path) === false) {
+ state.failures.push({ browser, error });
+ state.failedPaths.add(browser.path);
+ }
+ if (options.browserPath !== undefined) {
+ throw createBrowserStartupError(state.failures);
+ }
+ }
+ }
};
export const createScreenshotCaptureSession = (
dependencies = defaultScreenshotDependencies
) => {
- let browserPromise: Promise<BrowserCandidate> | undefined;
let browserSession: BrowserScreenshotSession | undefined;
+ let browserSessionCandidate: BrowserCandidate | undefined;
let browserSessionPromise: Promise<BrowserScreenshotSession> | undefined;
let closePromise: Promise<void> | undefined;
let closed = false;
+ const startupState = createBrowserStartupState();
const assertOpen = () => {
if (closed) {
throw new Error("Screenshot capture session is closed.");
}
};
- const getBrowser = async (options: CaptureScreenshotOptions) => {
- assertOpen();
- const pendingBrowser =
- browserPromise ?? resolveScreenshotBrowser(options, dependencies);
- browserPromise = pendingBrowser;
- try {
- const browser = await pendingBrowser;
- assertOpen();
- return browser;
- } catch (error) {
- if (browserPromise === pendingBrowser) {
- browserPromise = undefined;
- }
- throw error;
- }
- };
const getBrowserSession = async (
options: BrowserScreenshotOptions
): Promise<BrowserScreenshotSession> => {
@@ -804,32 +904,57 @@ export const createScreenshotCaptureSession = (
throw error;
}
};
- return {
- async capture(options: CaptureScreenshotOptions) {
- const resolvedBrowser = await getBrowser(options);
+ const getReadyBrowser = async (
+ options: CaptureScreenshotOptions,
+ compatibleOptions: readonly CaptureScreenshotOptions[] = [options]
+ ) => {
+ const validateBrowser = (browser: BrowserCandidate) => {
if (
- (options.browserPath !== undefined &&
- options.browserPath !== resolvedBrowser.path) ||
- (options.browser !== "auto" &&
- options.browser !== resolvedBrowser.browser)
+ compatibleOptions.some(
+ (candidateOptions) =>
+ (candidateOptions.browserPath !== undefined &&
+ candidateOptions.browserPath !== browser.path) ||
+ (candidateOptions.browser !== "auto" &&
+ candidateOptions.browser !== browser.browser)
+ )
) {
throw new Error(
"A reusable screenshot session cannot switch browser executables."
);
}
- const activeBrowserSession = await getBrowserSession(
- getBrowserScreenshotOptions(
- options,
- resolvedBrowser.path,
- options.output ?? "",
- dependencies
- )
- );
+ };
+ if (browserSession !== undefined && browserSessionCandidate !== undefined) {
+ validateBrowser(browserSessionCandidate);
+ return { browser: browserSessionCandidate, session: browserSession };
+ }
+ return await withBrowserStartupFallback({
+ options,
+ dependencies,
+ state: startupState,
+ validateBrowser,
+ async attempt(browser) {
+ const session = await getBrowserSession(
+ getBrowserScreenshotOptions(
+ options,
+ browser.path,
+ options.output ?? "",
+ dependencies
+ )
+ );
+ browserSessionCandidate = browser;
+ return { browser, session };
+ },
+ isCancelled: () => closed,
+ });
+ };
+ return {
+ async capture(options: CaptureScreenshotOptions) {
+ const { browser, session } = await getReadyBrowser(options);
return await captureResolvedScreenshot(
options,
- resolvedBrowser,
+ browser,
dependencies,
- activeBrowserSession
+ session
);
},
async capturePage(optionsList: readonly CaptureScreenshotOptions[]) {
@@ -838,20 +963,10 @@ export const createScreenshotCaptureSession = (
if (firstOptions === undefined) {
return [];
}
- const resolvedBrowser = await getBrowser(firstOptions);
- if (
- optionsList.some(
- (options) =>
- (options.browserPath !== undefined &&
- options.browserPath !== resolvedBrowser.path) ||
- (options.browser !== "auto" &&
- options.browser !== resolvedBrowser.browser)
- )
- ) {
- throw new Error(
- "A reusable screenshot session cannot switch browser executables."
- );
- }
+ const { browser, session } = await getReadyBrowser(
+ firstOptions,
+ optionsList
+ );
const startedAt = dependencies.now();
const batchSequence = screenshotBatchSequence;
screenshotBatchSequence += 1;
@@ -869,17 +984,14 @@ export const createScreenshotCaptureSession = (
output,
browserOptions: getBrowserScreenshotOptions(
options,
- resolvedBrowser.path,
+ browser.path,
output,
dependencies
),
};
})
);
- const activeBrowserSession = await getBrowserSession(
- captures[0].browserOptions
- );
- const layouts = await activeBrowserSession.capturePage(
+ const layouts = await session.capturePage(
captures.map((capture) => capture.browserOptions)
);
await Promise.all(
@@ -895,7 +1007,7 @@ export const createScreenshotCaptureSession = (
const layout = toWebstudioLayout(capturedLayout);
return {
output,
- browser: resolvedBrowser,
+ browser,
viewport: { width: options.width, height: options.height },
fullPage: options.fullPage === true,
elapsedMs: layout.timings?.wallMs ?? 0,
diff --git a/packages/vision/src/screenshot-browser-cdp.test.ts b/packages/vision/src/screenshot-browser-cdp.test.ts
index 5b8d408f22..a0f9052a09 100644
--- a/packages/vision/src/screenshot-browser-cdp.test.ts
+++ b/packages/vision/src/screenshot-browser-cdp.test.ts
@@ -1027,7 +1027,10 @@ test("removes the browser profile when spawning throws", async () => {
},
dependencies
)
- ).rejects.toThrow("Browser spawn failed");
+ ).rejects.toMatchObject({
+ code: "BROWSER_STARTUP_FAILED",
+ message: "Browser spawn failed",
+ });
expect(dependencies.rm).toHaveBeenCalledWith("/tmp/vision-browser-test", {
recursive: true,
force: true,
@@ -1123,6 +1126,7 @@ test("reports browser startup exit diagnostics without local paths", async () =>
dependencies
)
).rejects.toMatchObject({
+ code: "BROWSER_STARTUP_FAILED",
message:
"Browser exited before its DevTools endpoint became ready (exit code 21). Check the browser installation or provide a supported Chromium executable.",
});
@@ -1513,7 +1517,10 @@ test("stops polling when the browser DevTools port is not created", async () =>
},
dependencies
)
- ).rejects.toThrow("Browser DevTools endpoint was not created within 10ms.");
+ ).rejects.toMatchObject({
+ code: "BROWSER_STARTUP_FAILED",
+ message: "Browser DevTools endpoint was not created within 10ms.",
+ });
const callsAfterTimeout = vi.mocked(dependencies.readFile).mock.calls.length;
await new Promise((resolve) => setTimeout(resolve, 75));
@@ -1521,6 +1528,34 @@ test("stops polling when the browser DevTools port is not created", async () =>
expect(browserProcess.kill).toHaveBeenCalled();
});
+test("uses a separate browser startup timeout", async () => {
+ const browserProcess = new FakeBrowserProcess();
+ const dependencies = createDependencies({ browserProcess });
+ vi.mocked(dependencies.readFile).mockRejectedValue(
+ Object.assign(new Error("not ready"), { code: "ENOENT" })
+ );
+
+ await expect(
+ createBrowserScreenshotSession(
+ {
+ url: "https://example.com",
+ output: "/tmp/current.png",
+ width: 800,
+ height: 600,
+ browserPath: "/usr/bin/chromium",
+ waitUntil: "load",
+ waitForTimeout: 0,
+ timeout: 100,
+ startupTimeout: 5,
+ },
+ dependencies
+ )
+ ).rejects.toMatchObject({
+ code: "BROWSER_STARTUP_FAILED",
+ message: "Browser DevTools endpoint was not created within 5ms.",
+ });
+});
+
test("does not wait indefinitely for a failed browser startup to exit", async () => {
const browserProcess = new FakeBrowserProcess();
browserProcess.kill.mockImplementation((signal) => {
diff --git a/packages/vision/src/screenshot-browser-cdp.ts b/packages/vision/src/screenshot-browser-cdp.ts
index 85682e258e..85dd295789 100644
--- a/packages/vision/src/screenshot-browser-cdp.ts
+++ b/packages/vision/src/screenshot-browser-cdp.ts
@@ -58,6 +58,7 @@ export type BrowserScreenshotOptions = {
waitForTimeout: number;
finalizeExpression?: string;
timeout: number;
+ startupTimeout?: number;
format?: "png" | "jpeg" | "webp";
quality?: number;
scale?: number;
@@ -1239,6 +1240,15 @@ const getScreenshotCaptureParams = async ({
};
};
+export class BrowserStartupError extends Error {
+ readonly code = "BROWSER_STARTUP_FAILED";
+
+ constructor(message: string, options?: { cause?: unknown }) {
+ super(message, options);
+ this.name = "BrowserStartupError";
+ }
+}
+
class BrowserSessionClosedError extends Error {}
const getBrowserExitMessage = (message: string, reason?: string) =>
@@ -1289,6 +1299,7 @@ const startBrowserRuntimeOnce = async (
options: BrowserScreenshotOptions,
dependencies: BrowserScreenshotDependencies
): Promise<BrowserRuntime> => {
+ const startupTimeout = options.startupTimeout ?? options.timeout;
const userDataDir = await dependencies.mkdtemp(
join(tmpdir(), "vision-browser-")
);
@@ -1332,7 +1343,7 @@ const startBrowserRuntimeOnce = async (
});
try {
const { port } = await Promise.race([
- waitForDevToolsPort(userDataDir, dependencies, options.timeout),
+ waitForDevToolsPort(userDataDir, dependencies, startupTimeout),
browserClosed.then((reason) => {
throw new BrowserSessionClosedError(
getBrowserExitMessage(
@@ -1373,7 +1384,7 @@ const startBrowserRuntimeOnce = async (
browserProcess,
browserClosed,
running,
- gracePeriodMs: Math.min(options.timeout, 2000),
+ gracePeriodMs: Math.min(startupTimeout, 2000),
});
await dependencies
.rm(userDataDir, { recursive: true, force: true })
@@ -1390,10 +1401,20 @@ const startBrowserRuntime = async (
return await startBrowserRuntimeOnce(options, dependencies);
} catch (error) {
if (error instanceof BrowserSessionClosedError === false) {
- throw error;
+ throw new BrowserStartupError(
+ error instanceof Error ? error.message : String(error),
+ { cause: error }
+ );
}
}
- return await startBrowserRuntimeOnce(options, dependencies);
+ try {
+ return await startBrowserRuntimeOnce(options, dependencies);
+ } catch (error) {
+ throw new BrowserStartupError(
+ error instanceof Error ? error.message : String(error),
+ { cause: error }
+ );
+ }
};
const capturePageWithBrowserRuntime = async (
diff --git a/packages/vision/src/screenshot-browser.test.ts b/packages/vision/src/screenshot-browser.test.ts
index 450c67efee..e95438f5ac 100644
--- a/packages/vision/src/screenshot-browser.test.ts
+++ b/packages/vision/src/screenshot-browser.test.ts
@@ -1,5 +1,6 @@
import { expect, test } from "vitest";
import {
+ defaultBrowserStartupTimeout,
defaultScreenshotTimeout,
defaultScreenshotWaitForTimeout,
defaultScreenshotWaitUntil,
@@ -36,4 +37,5 @@ test("defines screenshot readiness defaults", () => {
expect(defaultScreenshotWaitUntil).toBe("load");
expect(defaultScreenshotWaitForTimeout).toBe(250);
expect(defaultScreenshotTimeout).toBe(30000);
+ expect(defaultBrowserStartupTimeout).toBe(10000);
});
diff --git a/packages/vision/src/screenshot-browser.ts b/packages/vision/src/screenshot-browser.ts
index 1759c604fd..79c72d7261 100644
--- a/packages/vision/src/screenshot-browser.ts
+++ b/packages/vision/src/screenshot-browser.ts
@@ -29,6 +29,8 @@ export const defaultScreenshotWaitForTimeout = 250;
export const defaultScreenshotTimeout = 30000;
+export const defaultBrowserStartupTimeout = 10000;
+
export type ScreenshotCaptureOptions = {
output?: string;
viewport: { width: number; height: number };