Automate browser based workflows with AI
Python aiapiautomationbrowserbrowser-automationcomputergptllmplaywrightpowerautomatepuppeteerpythonrpaseleniumvisionworkflow
Add interactive ngrok guided setup for browser serve --tunnel (#4986)
Marc Kelechava5a5db62bfa78
diff --git a/skyvern/cli/commands/browser.py b/skyvern/cli/commands/browser.pyindex b96c41bce..5c452731a 100644--- a/skyvern/cli/commands/browser.py+++ b/skyvern/cli/commands/browser.py@@ -2,7 +2,6 @@ from __future__ import annotationsimport asyncioimport json-import shutilimport subprocessimport sysfrom dataclasses import asdict, dataclass@@ -31,6 +30,7 @@ from skyvern.cli.core.guards import (validate_button,validate_wait_until,)+from skyvern.cli.core.ngrok import check_ngrok_auth, detect_ngrok, offer_install_ngrok, offer_setup_authfrom skyvern.cli.core.session_ops import do_session_close, do_session_create, do_session_listfrom skyvern.cli.mcp_tools.browser import skyvern_login as tool_loginfrom skyvern.cli.mcp_tools.browser import skyvern_run_task as tool_run_task@@ -1244,31 +1244,23 @@ async def _maybe_start_ngrok_tunnel(port: int, browser_path: str, *, auto: bool)return None# Check if ngrok is installed- ngrok_path = shutil.which("ngrok")+ ngrok_path = detect_ngrok()if not ngrok_path:- console.print()- console.print(" [bold red]ngrok not found.[/bold red]")- console.print()- console.print(" [bold]1.[/bold] Install ngrok:")- console.print(" [green]brew install ngrok[/green] [dim](macOS)[/dim]")- console.print(" [cyan]https://ngrok.com/download[/cyan] [dim](other platforms)[/dim]")- console.print()- console.print(" [bold]2.[/bold] Sign up for a free account:")- console.print(" [cyan]https://dashboard.ngrok.com/signup[/cyan]")- console.print()- console.print(" [bold]3.[/bold] Add your authtoken:")- console.print(" [green]ngrok config add-authtoken <your-token>[/green]")- console.print(- " [dim]Get your token at[/dim] [cyan]https://dashboard.ngrok.com/get-started/your-authtoken[/cyan]"- )- console.print()- console.print(" [bold]4.[/bold] Re-run:")- console.print(" [green]skyvern browser serve --tunnel[/green]")- console.print()- if auto:- # --tunnel was explicit — don't silently continue without a tunnel- raise SystemExit(1)- return None+ # When auto=True (--tunnel in CI), skip interactive prompts and fail fast+ ngrok_path = offer_install_ngrok(interactive=not auto)+ if not ngrok_path:+ if auto:+ raise SystemExit(1)+ return None++ # Check if ngrok auth token is configured+ # Note: check_ngrok_auth is best-effort (validates config syntax, not token+ # validity). The real validation happens when ngrok tries to start a tunnel.+ if not check_ngrok_auth(ngrok_path):+ if not offer_setup_auth(ngrok_path, interactive=not auto):+ if auto:+ raise SystemExit(1)+ return Noneconsole.print()console.print(f" Starting ngrok tunnel on port [cyan]{port}[/cyan]...")diff --git a/skyvern/cli/core/ngrok.py b/skyvern/cli/core/ngrok.pynew file mode 100644index 000000000..ff93edf8e--- /dev/null+++ b/skyvern/cli/core/ngrok.py@@ -0,0 +1,153 @@+"""ngrok detection, installation, and auth token setup helpers.++Used by ``_maybe_start_ngrok_tunnel`` in ``skyvern.cli.commands.browser`` to+provide an interactive guided setup when ngrok is missing or unconfigured.+"""++from __future__ import annotations++import platform+import shutil+import subprocess+import webbrowser++from rich.prompt import Confirm, Prompt++from skyvern.cli.console import console+++def detect_ngrok() -> str | None:+ """Return the path to the ngrok binary, or ``None`` if not found."""+ return shutil.which("ngrok")+++def detect_os() -> str:+ """Return ``'macos'``, ``'linux'``, or ``'windows'``."""+ system = platform.system().lower()+ if system == "darwin":+ return "macos"+ if system == "linux":+ return "linux"+ return "windows"+++def offer_install_ngrok(*, interactive: bool = True) -> str | None:+ """Interactively offer to install ngrok. Returns the path on success, else ``None``.++ When *interactive* is ``False`` (e.g. ``--tunnel`` in CI), skip prompts+ and just print the error message.+ """+ if not interactive:+ console.print()+ console.print(" [bold red]ngrok not found.[/bold red]")+ console.print(" Install from: [cyan]https://ngrok.com/download[/cyan]")+ console.print(" Then re-run: [green]skyvern browser serve --tunnel[/green]")+ console.print()+ return None++ os_type = detect_os()++ # macOS: try Homebrew first+ if os_type == "macos" and shutil.which("brew"):+ want = Confirm.ask(+ "[bold red]ngrok not found.[/bold red] Install via Homebrew?",+ default=True,+ )+ if want:+ try:+ console.print(" Installing ngrok via Homebrew...")+ subprocess.run(["brew", "install", "ngrok"], check=True)+ path = shutil.which("ngrok")+ if path:+ console.print(" [green]ngrok installed successfully.[/green]")+ return path+ except subprocess.CalledProcessError as exc:+ console.print(f" [red]Homebrew install failed (exit {exc.returncode}).[/red]")+ # Fall through to download page+ else:+ # User declined brew — skip the redundant "ngrok not found" message+ console.print()+ console.print(" Install manually from: [cyan]https://ngrok.com/download[/cyan]")+ console.print(" Then re-run: [green]skyvern browser serve --tunnel[/green]")+ console.print()+ want_open = Confirm.ask("Open ngrok download page in browser?", default=True)+ if want_open:+ open_url("https://ngrok.com/download")+ return None++ # Fallback: direct the user to the download page+ console.print()+ console.print(" [bold red]ngrok not found.[/bold red]")+ console.print(" Install from: [cyan]https://ngrok.com/download[/cyan]")+ console.print(" Then re-run: [green]skyvern browser serve --tunnel[/green]")+ console.print()++ want = Confirm.ask("Open ngrok download page in browser?", default=True)+ if want:+ open_url("https://ngrok.com/download")++ return None+++def check_ngrok_auth(ngrok_path: str) -> bool:+ """Return ``True`` if ngrok has a valid configuration with an auth token.++ Note: ``ngrok config check`` validates config file syntax, not the presence+ of an auth token specifically. Some ngrok versions exit 0 with no token.+ This is a best-effort check — the real validation happens when ngrok tries+ to start a tunnel.+ """+ try:+ result = subprocess.run(+ [ngrok_path, "config", "check"],+ capture_output=True,+ text=True,+ timeout=5,+ )+ return result.returncode == 0+ except (subprocess.TimeoutExpired, FileNotFoundError, OSError):+ return False+++def offer_setup_auth(ngrok_path: str, *, interactive: bool = True) -> bool:+ """Guide the user through configuring their ngrok auth token. Returns ``True`` on success.++ When *interactive* is ``False`` (e.g. ``--tunnel`` in CI), skip prompts+ and just print the error message.+ """+ console.print()+ console.print(" [bold yellow]ngrok auth token not configured.[/bold yellow]")++ if not interactive:+ console.print(" Run: [green]ngrok config add-authtoken <your-token>[/green]")+ console.print(" Get a token at: [cyan]https://dashboard.ngrok.com/get-started/your-authtoken[/cyan]")+ console.print()+ return False++ console.print()++ want = Confirm.ask("Open ngrok dashboard to get a free auth token?", default=True)+ if want:+ open_url("https://dashboard.ngrok.com/get-started/your-authtoken")++ token = Prompt.ask("Paste your ngrok auth token (or press Enter to skip)", default="")+ if not token.strip():+ return False++ result = subprocess.run(+ [ngrok_path, "config", "add-authtoken", token.strip()],+ capture_output=True,+ text=True,+ timeout=10,+ )+ if result.returncode == 0:+ console.print(" [green]Auth token configured successfully.[/green]")+ return True++ console.print(f" [red]Failed to set auth token: {result.stderr.strip()}[/red]")+ return False+++def open_url(url: str) -> None:+ """Open *url* in the user's default browser."""+ webbrowser.open(url)diff --git a/tests/unit/test_ngrok_helpers.py b/tests/unit/test_ngrok_helpers.pynew file mode 100644index 000000000..ec0ee1667--- /dev/null+++ b/tests/unit/test_ngrok_helpers.py@@ -0,0 +1,111 @@+from __future__ import annotations++import subprocess+from unittest.mock import patch++from skyvern.cli.core.ngrok import (+ check_ngrok_auth,+ detect_ngrok,+ detect_os,+ offer_install_ngrok,+ offer_setup_auth,+)+++def test_detect_ngrok_found() -> None:+ with patch("skyvern.cli.core.ngrok.shutil.which", return_value="/usr/local/bin/ngrok"):+ assert detect_ngrok() == "/usr/local/bin/ngrok"+++def test_detect_ngrok_missing() -> None:+ with patch("skyvern.cli.core.ngrok.shutil.which", return_value=None):+ assert detect_ngrok() is None+++def test_detect_os_platforms() -> None:+ for system, expected in [("Darwin", "macos"), ("Linux", "linux"), ("Windows", "windows")]:+ with patch("skyvern.cli.core.ngrok.platform.system", return_value=system):+ assert detect_os() == expected+++def test_check_ngrok_auth_success() -> None:+ with patch("skyvern.cli.core.ngrok.subprocess.run") as mock_run:+ mock_run.return_value = subprocess.CompletedProcess(args=[], returncode=0)+ assert check_ngrok_auth("/usr/local/bin/ngrok") is True+++def test_check_ngrok_auth_failures() -> None:+ # Non-zero exit+ with patch("skyvern.cli.core.ngrok.subprocess.run") as mock_run:+ mock_run.return_value = subprocess.CompletedProcess(args=[], returncode=1)+ assert check_ngrok_auth("/usr/local/bin/ngrok") is False++ # Timeout+ with patch(+ "skyvern.cli.core.ngrok.subprocess.run",+ side_effect=subprocess.TimeoutExpired(cmd="ngrok", timeout=5),+ ):+ assert check_ngrok_auth("/usr/local/bin/ngrok") is False+++def test_offer_install_brew_success() -> None:+ with (+ patch("skyvern.cli.core.ngrok.detect_os", return_value="macos"),+ patch("skyvern.cli.core.ngrok.shutil.which", side_effect=["/opt/homebrew/bin/brew", "/opt/homebrew/bin/ngrok"]),+ patch("skyvern.cli.core.ngrok.subprocess.run", return_value=subprocess.CompletedProcess(args=[], returncode=0)),+ patch("skyvern.cli.core.ngrok.Confirm.ask", return_value=True),+ ):+ assert offer_install_ngrok() == "/opt/homebrew/bin/ngrok"+++def test_offer_install_brew_declined() -> None:+ """When user declines brew, should show manual install info without redundant 'ngrok not found'."""+ with (+ patch("skyvern.cli.core.ngrok.detect_os", return_value="macos"),+ patch("skyvern.cli.core.ngrok.shutil.which", return_value="/opt/homebrew/bin/brew"),+ patch("skyvern.cli.core.ngrok.Confirm.ask", side_effect=[False, False]),+ patch("skyvern.cli.core.ngrok.console") as mock_console,+ ):+ result = offer_install_ngrok()+ assert result is None+ # Should NOT print "ngrok not found" again after user declined+ printed = " ".join(str(c) for c in mock_console.print.call_args_list)+ assert "ngrok not found" not in printed+++def test_offer_install_non_interactive() -> None:+ """Non-interactive mode (--tunnel in CI) prints error and returns None without prompting."""+ with patch("skyvern.cli.core.ngrok.console") as mock_console:+ result = offer_install_ngrok(interactive=False)+ assert result is None+ printed = " ".join(str(c) for c in mock_console.print.call_args_list)+ assert "ngrok not found" in printed+++def test_offer_setup_auth_success() -> None:+ with (+ patch("skyvern.cli.core.ngrok.subprocess.run", return_value=subprocess.CompletedProcess(args=[], returncode=0)),+ patch("skyvern.cli.core.ngrok.open_url"),+ patch("skyvern.cli.core.ngrok.Confirm.ask", return_value=True),+ patch("skyvern.cli.core.ngrok.Prompt.ask", return_value="my-token"),+ ):+ assert offer_setup_auth("/usr/local/bin/ngrok") is True+++def test_offer_setup_auth_skipped() -> None:+ with (+ patch("skyvern.cli.core.ngrok.open_url"),+ patch("skyvern.cli.core.ngrok.Confirm.ask", return_value=False),+ patch("skyvern.cli.core.ngrok.Prompt.ask", return_value=""),+ ):+ assert offer_setup_auth("/usr/local/bin/ngrok") is False+++def test_offer_setup_auth_non_interactive() -> None:+ """Non-interactive mode prints instructions and returns False without prompting."""+ with patch("skyvern.cli.core.ngrok.console") as mock_console:+ result = offer_setup_auth("/usr/local/bin/ngrok", interactive=False)+ assert result is False+ printed = " ".join(str(c) for c in mock_console.print.call_args_list)+ assert "auth token not configured" in printed+ assert "add-authtoken" in printed