Skip to content

Automate browser based workflows with AI

[codex] Handle quickstart Chromium install failures (#5909)

Suchintan97fd07b801d6
diff --git a/skyvern/cli/init_command.py b/skyvern/cli/init_command.py
index b30bdb653..7c16521d6 100644
--- a/skyvern/cli/init_command.py
+++ b/skyvern/cli/init_command.py
@@ -2,6 +2,9 @@ import asyncio
import os
import subprocess
import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal, overload
import typer
from rich.padding import Padding
@@ -18,12 +21,153 @@ from .database import setup_postgresql
from .llm_setup import setup_llm_providers, update_or_add_env_var
from .masked_prompt import ask_secret
+PLAYWRIGHT_CHROMIUM_BROWSER_TYPES = {"chromium-headful", "chromium-headless"}
+
+@dataclass
+class BrowserInstallStatus:
+ """Status for the optional Playwright-managed Chromium install step."""
+
+ required: bool
+ ready: bool
+ skipped: bool = False
+ already_installed: bool = False
+ attempted: bool = False
+ reason: str | None = None
+ error: str | None = None
+
+
+@dataclass
+class InitEnvResult:
+ """Result of the interactive initialization flow."""
+
+ run_local: bool
+ browser_type: str | None = None
+ browser_install: BrowserInstallStatus = field(
+ default_factory=lambda: BrowserInstallStatus(required=False, ready=True)
+ )
+
+ def __bool__(self) -> bool:
+ """Preserve bool-like behavior for existing callers."""
+ return self.run_local
+
+
+def _browser_type_requires_playwright_chromium(browser_type: str | None) -> bool:
+ return browser_type in PLAYWRIGHT_CHROMIUM_BROWSER_TYPES
+
+
+def _playwright_chromium_executable_path() -> Path | None:
+ try:
+ from playwright.sync_api import sync_playwright
+
+ with sync_playwright() as playwright:
+ return Path(playwright.chromium.executable_path)
+ except Exception:
+ return None
+
+
+def _is_playwright_chromium_installed() -> bool:
+ executable_path = _playwright_chromium_executable_path()
+ return executable_path is not None and executable_path.exists()
+
+
+def _format_subprocess_error(error: subprocess.CalledProcessError) -> str:
+ stderr = (error.stderr or "").strip()
+ if stderr:
+ return stderr
+ stdout = (error.stdout or "").strip()
+ if stdout:
+ return stdout
+ return str(error)
+
+
+def _ensure_playwright_chromium(browser_type: str | None, skip_browser_install: bool) -> BrowserInstallStatus:
+ """Install Playwright Chromium when the selected browser mode needs it."""
+ if not _browser_type_requires_playwright_chromium(browser_type):
+ reason = f"browser mode is {browser_type or 'not set'}"
+ console.print(f"[green]Skipping Chromium installation because {reason}.[/green]")
+ return BrowserInstallStatus(required=False, ready=True, skipped=True, reason=reason)
+
+ if _is_playwright_chromium_installed():
+ console.print("[green]Playwright Chromium is already installed. Skipping download.[/green]")
+ return BrowserInstallStatus(required=True, ready=True, skipped=True, already_installed=True)
+
+ if skip_browser_install:
+ console.print("⏭️ [yellow]Skipping Chromium installation as requested.[/yellow]")
+ return BrowserInstallStatus(
+ required=True,
+ ready=False,
+ skipped=True,
+ reason="--skip-browser-install was provided",
+ )
+
+ console.print("\n⬇️ [bold blue]Installing Chromium browser...[/bold blue]")
+ capture_setup_event("playwright-install-start")
+ with Progress(
+ SpinnerColumn(), TextColumn("[progress.description]{task.description}"), transient=True, console=console
+ ) as progress:
+ progress.add_task("[bold blue]Downloading Chromium, this may take a moment...", total=None)
+ try:
+ subprocess.run(["playwright", "install", "chromium"], check=True, capture_output=True, text=True)
+ capture_setup_event("playwright-install-complete", success=True)
+ console.print("✅ [green]Chromium installation complete.[/green]")
+ return BrowserInstallStatus(required=True, ready=True, attempted=True)
+ except subprocess.CalledProcessError as e:
+ error_message = _format_subprocess_error(e)
+ capture_setup_event(
+ "playwright-install-fail",
+ success=False,
+ error_type="playwright_install_error",
+ error_message=error_message,
+ )
+ console.print(
+ Panel(
+ "[bold yellow]Chromium installation did not complete.[/bold yellow]\n\n"
+ "The rest of your Skyvern setup has been saved. Browser modes that launch "
+ "Playwright-managed Chromium will not be ready until this is fixed.\n\n"
+ "Run this command to finish the browser install:\n"
+ "[cyan]playwright install chromium[/cyan]",
+ border_style="yellow",
+ )
+ )
+ return BrowserInstallStatus(
+ required=True,
+ ready=False,
+ attempted=True,
+ error=error_message,
+ )
+
+
+def _init_return_value(result: InitEnvResult, return_result: bool) -> bool | InitEnvResult:
+ if return_result:
+ return result
+ return result.run_local
+
+
+@overload
def init_env(
no_postgres: bool = False,
database_string: str = "",
skip_browser_install: bool = False,
-) -> bool:
+ return_result: Literal[False] = False,
+) -> bool: ...
+
+
+@overload
+def init_env(
+ no_postgres: bool = False,
+ database_string: str = "",
+ skip_browser_install: bool = False,
+ return_result: Literal[True] = True,
+) -> InitEnvResult: ...
+
+
+def init_env(
+ no_postgres: bool = False,
+ database_string: str = "",
+ skip_browser_install: bool = False,
+ return_result: bool = False,
+) -> bool | InitEnvResult:
"""Interactive initialization command for Skyvern."""
console.print(
Panel(
@@ -40,6 +184,7 @@ def init_env(
)
run_local = infra_choice == "local"
+ result = InitEnvResult(run_local=run_local)
if run_local:
if database_string:
@@ -84,6 +229,7 @@ def init_env(
console.print("\n[bold blue]Configuring browser settings...[/bold blue]")
browser_type, browser_location, remote_debugging_url = setup_browser_config()
+ result.browser_type = browser_type
update_or_add_env_var("BROWSER_TYPE", browser_type)
if browser_location:
update_or_add_env_var("CHROME_EXECUTABLE_PATH", browser_location)
@@ -138,7 +284,7 @@ def init_env(
api_key = ask_secret("Please re-enter your Skyvern API key")
if not api_key:
console.print("[bold red]Error: API key cannot be empty. Aborting initialization.[/bold red]")
- return False
+ return _init_return_value(result, return_result)
update_or_add_env_var("SKYVERN_BASE_URL", base_url)
console.print(
@@ -175,34 +321,14 @@ def init_env(
)
if run_local:
- if skip_browser_install:
- console.print("⏭️ [yellow]Skipping Chromium installation as requested.[/yellow]")
- else:
- console.print("\n⬇️ [bold blue]Installing Chromium browser...[/bold blue]")
- capture_setup_event("playwright-install-start")
- with Progress(
- SpinnerColumn(), TextColumn("[progress.description]{task.description}"), transient=True, console=console
- ) as progress:
- progress.add_task("[bold blue]Downloading Chromium, this may take a moment...", total=None)
- try:
- subprocess.run(["playwright", "install", "chromium"], check=True, capture_output=True, text=True)
- capture_setup_event("playwright-install-complete", success=True)
- except subprocess.CalledProcessError as e:
- capture_setup_event(
- "playwright-install-fail",
- success=False,
- error_type="playwright_install_error",
- error_message=e.stderr.strip() if e.stderr else str(e),
- )
- raise
- console.print("✅ [green]Chromium installation complete.[/green]")
+ result.browser_install = _ensure_playwright_chromium(result.browser_type, skip_browser_install)
console.print("\n🎉 [bold green]Skyvern setup complete![/bold green]")
capture_setup_event("init-complete", success=True, extra_data={"mode": "local"})
console.print("[bold]To start using Skyvern, run:[/bold]")
console.print(Padding("skyvern run server", (1, 4), style="reverse green"))
- return run_local
+ return _init_return_value(result, return_result)
def init_app_factory() -> typer.Typer:
@@ -257,21 +383,4 @@ def init_browser() -> None:
)
console.print("✅ [green]Browser configuration complete.[/green]")
- console.print("\n⬇️ [bold blue]Installing Chromium browser...[/bold blue]")
- capture_setup_event("playwright-install-start")
- with Progress(
- SpinnerColumn(), TextColumn("[progress.description]{task.description}"), transient=True, console=console
- ) as progress:
- progress.add_task("[bold blue]Downloading Chromium, this may take a moment...", total=None)
- try:
- subprocess.run(["playwright", "install", "chromium"], check=True, capture_output=True, text=True)
- capture_setup_event("playwright-install-complete", success=True)
- except subprocess.CalledProcessError as e:
- capture_setup_event(
- "playwright-install-fail",
- success=False,
- error_type="playwright_install_error",
- error_message=e.stderr.strip() if e.stderr else str(e),
- )
- raise
- console.print("✅ [green]Chromium installation complete.[/green]")
+ _ensure_playwright_chromium(browser_type, skip_browser_install=False)
diff --git a/skyvern/cli/quickstart.py b/skyvern/cli/quickstart.py
index 92bd95eb0..49080bb44 100644
--- a/skyvern/cli/quickstart.py
+++ b/skyvern/cli/quickstart.py
@@ -47,6 +47,15 @@ Self-hosted local server
console.print(Panel(Text(message), title="Skyvern Quickstart", border_style="cyan"))
+def _browser_install_blocks_startup(init_result: object) -> bool:
+ browser_install = getattr(init_result, "browser_install", None)
+ return bool(
+ getattr(init_result, "run_local", False)
+ and getattr(browser_install, "required", False)
+ and not getattr(browser_install, "ready", True)
+ )
+
+
def _run_server_quickstart(
*,
no_postgres: bool,
@@ -60,16 +69,35 @@ def _run_server_quickstart(
# Initialize Skyvern (pip install path)
console.print("\n[bold blue]Initializing Skyvern...[/bold blue]")
- run_local = init_env(
+ init_result = init_env(
no_postgres=no_postgres,
database_string=database_string,
skip_browser_install=skip_browser_install,
+ return_result=True,
)
+ run_local = bool(init_result)
if run_local:
_configure_cdp_livestreaming_defaults()
# Start services
if run_local:
+ if _browser_install_blocks_startup(init_result):
+ console.print(
+ Panel(
+ "[bold yellow]Skyvern setup is saved, but the browser install is incomplete.[/bold yellow]\n\n"
+ "Quickstart will not start services yet because the selected browser mode launches "
+ "Playwright-managed Chromium.\n\n"
+ "Finish the browser install, then start Skyvern:\n"
+ "[cyan]playwright install chromium[/cyan]\n"
+ "[cyan]skyvern run server[/cyan]\n\n"
+ "If you want to use an existing Chrome over CDP instead, rerun quickstart and choose "
+ "Local browser -> Use actual browser, or pass [cyan]--skip-browser-install[/cyan] "
+ "after configuring CDP.",
+ border_style="yellow",
+ )
+ )
+ return
+
start_now = typer.confirm("\nDo you want to start Skyvern services now?", default=True)
if start_now:
console.print("\n[bold blue]Starting Skyvern services...[/bold blue]")
diff --git a/tests/unit/test_quickstart_browser_install.py b/tests/unit/test_quickstart_browser_install.py
new file mode 100644
index 000000000..85f17fa38
--- /dev/null
+++ b/tests/unit/test_quickstart_browser_install.py
@@ -0,0 +1,102 @@
+from __future__ import annotations
+
+import subprocess
+
+import pytest
+
+from skyvern.cli import init_command
+from skyvern.cli import quickstart as quickstart_module
+from skyvern.cli.init_command import BrowserInstallStatus, InitEnvResult
+
+
+def test_cdp_mode_skips_playwright_chromium_install(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ init_command,
+ "_is_playwright_chromium_installed",
+ lambda: (_ for _ in ()).throw(AssertionError("should not check Chromium")),
+ )
+ monkeypatch.setattr(
+ init_command.subprocess,
+ "run",
+ lambda *_args, **_kwargs: (_ for _ in ()).throw(AssertionError("should not install Chromium")),
+ )
+
+ status = init_command._ensure_playwright_chromium("cdp-connect", skip_browser_install=False)
+
+ assert status.required is False
+ assert status.ready is True
+ assert status.skipped is True
+
+
+def test_installed_playwright_chromium_skips_download(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(init_command, "_is_playwright_chromium_installed", lambda: True)
+ monkeypatch.setattr(
+ init_command.subprocess,
+ "run",
+ lambda *_args, **_kwargs: (_ for _ in ()).throw(AssertionError("should not install Chromium")),
+ )
+
+ status = init_command._ensure_playwright_chromium("chromium-headful", skip_browser_install=False)
+
+ assert status.required is True
+ assert status.ready is True
+ assert status.already_installed is True
+
+
+def test_playwright_chromium_install_failure_is_recoverable(monkeypatch: pytest.MonkeyPatch) -> None:
+ events: list[tuple[str, bool | None, str | None]] = []
+
+ def fake_capture(event: str, success: bool | None = None, error_message: str | None = None, **_kwargs) -> None:
+ events.append((event, success, error_message))
+
+ def fake_run(*_args, **_kwargs):
+ raise subprocess.CalledProcessError(
+ returncode=1,
+ cmd=["playwright", "install", "chromium"],
+ stderr="network failed",
+ )
+
+ monkeypatch.setattr(init_command, "_is_playwright_chromium_installed", lambda: False)
+ monkeypatch.setattr(init_command, "capture_setup_event", fake_capture)
+ monkeypatch.setattr(init_command.subprocess, "run", fake_run)
+
+ status = init_command._ensure_playwright_chromium("chromium-headful", skip_browser_install=False)
+
+ assert status.required is True
+ assert status.ready is False
+ assert status.attempted is True
+ assert status.error == "network failed"
+ assert ("playwright-install-fail", False, "network failed") in events
+
+
+def test_quickstart_does_not_start_services_when_required_browser_is_missing(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ init_result = InitEnvResult(
+ run_local=True,
+ browser_type="chromium-headful",
+ browser_install=BrowserInstallStatus(required=True, ready=False, attempted=True, error="network failed"),
+ )
+
+ monkeypatch.setattr(quickstart_module, "check_docker_compose_file", lambda: False)
+ monkeypatch.setattr(quickstart_module, "_has_server_quickstart_extra", lambda: True)
+ monkeypatch.setattr(init_command, "init_env", lambda **_kwargs: init_result)
+ monkeypatch.setattr(quickstart_module, "_configure_cdp_livestreaming_defaults", lambda: None)
+ monkeypatch.setattr(
+ quickstart_module.typer,
+ "confirm",
+ lambda *_args, **_kwargs: (_ for _ in ()).throw(AssertionError("should not prompt to start")),
+ )
+ monkeypatch.setattr(
+ "skyvern.cli.utils.start_services",
+ lambda *_args, **_kwargs: (_ for _ in ()).throw(AssertionError("should not start services")),
+ )
+
+ quickstart_module.quickstart(
+ ctx=None, # type: ignore[arg-type]
+ no_postgres=False,
+ database_string="",
+ skip_browser_install=False,
+ server_only=False,
+ docker_compose=False,
+ )