Skip to content

Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai

fix: install and pre-check patchright's chromium, which playwright install does not provide (#67)

Francois du Plessis488fe87a37e3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3783200..31b5ced 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,16 @@
## [Unreleased]
+- **Browser setup installs (and pre-checks) patchright's chromium when
+ patchright is present.** The stealth adapter (`UndetectedAdapter`) launches
+ patchright's pinned chromium, which lives in a separate registry from plain
+ playwright's, so `playwright install chromium` alone produces a machine
+ where every preflight passes and every browser fetch dies at launch with a
+ missing-executable error, while the PDF lane keeps working. Both setup
+ surfaces (`hyperresearch setup` and `install`) now check against the stack
+ the provider actually launches and prefer `python -m patchright install
+ chromium`, falling back to plain playwright for non-stealth installs; the
+ manual-install hint names both commands.
- **Collision note ids survive the frontmatter re-parse** (an orphan-note
foreign-key crash). `write_note()` appended `-2` to a slug already sitting on
`slugify()`'s 80-char cap, producing an 82-char id whose next parse
diff --git a/src/hyperresearch/cli/install.py b/src/hyperresearch/cli/install.py
index d15387b..30b44f9 100644
--- a/src/hyperresearch/cli/install.py
+++ b/src/hyperresearch/cli/install.py
@@ -235,9 +235,15 @@ def _setup_crawl4ai(vault) -> str:
vault.config.web_provider = "crawl4ai"
vault.config.save(vault.config_path)
- # Check if browser is already installed
+ # Check if the browser is already installed -- against the stack the
+ # provider will actually launch: patchright (stealth adapter) pins its
+ # own chromium build, so a passing plain-playwright check can mask a
+ # missing patchright browser.
try:
- from playwright.sync_api import sync_playwright
+ try:
+ from patchright.sync_api import sync_playwright
+ except ImportError:
+ from playwright.sync_api import sync_playwright
pw = sync_playwright().start()
browser = pw.chromium.launch(headless=True)
@@ -247,16 +253,27 @@ def _setup_crawl4ai(vault) -> str:
except Exception:
pass
- # Try to install the browser
+ # Try to install the browser. The stealth (patchright) adapter pins its
+ # OWN chromium build with a separate registry -- `playwright install`
+ # does not provide it, and the provider then dies at launch with a
+ # missing-executable error. Install patchright's browser when patchright
+ # is present; plain playwright is the fallback for non-stealth setups.
+ import importlib.util
import subprocess
import sys
- try:
- subprocess.run(
- [sys.executable, "-m", "playwright", "install", "chromium"],
- check=True,
- capture_output=True,
- )
- return "browser_installed"
- except (subprocess.CalledProcessError, FileNotFoundError):
- return "configured" # best effort — user can install manually
+ installers = []
+ if importlib.util.find_spec("patchright") is not None:
+ installers.append("patchright")
+ installers.append("playwright")
+ for mod in installers:
+ try:
+ subprocess.run(
+ [sys.executable, "-m", mod, "install", "chromium"],
+ check=True,
+ capture_output=True,
+ )
+ return "browser_installed"
+ except (subprocess.CalledProcessError, FileNotFoundError):
+ continue
+ return "configured" # best effort — user can install manually
diff --git a/src/hyperresearch/cli/setup.py b/src/hyperresearch/cli/setup.py
index 2936f26..8ffbf6a 100644
--- a/src/hyperresearch/cli/setup.py
+++ b/src/hyperresearch/cli/setup.py
@@ -284,9 +284,18 @@ def _check_crawl4ai() -> bool:
def _ensure_browser() -> None:
- """Check if Chromium is installed, install if needed."""
+ """Check if Chromium is installed, install if needed.
+
+ Checks against the stack the provider will actually launch: the stealth
+ adapter uses patchright, which pins its OWN chromium build in a separate
+ registry, so a passing plain-playwright check can mask a missing
+ patchright browser and every fetch then dies at launch.
+ """
try:
- from playwright.sync_api import sync_playwright
+ try:
+ from patchright.sync_api import sync_playwright
+ except ImportError:
+ from playwright.sync_api import sync_playwright
pw = sync_playwright().start()
browser = pw.chromium.launch(headless=True)
@@ -295,17 +304,27 @@ def _ensure_browser() -> None:
console.print(" [dim]Browser ready[/]")
except Exception:
console.print(" [yellow]Installing Chromium browser...[/]")
+ import importlib.util
import subprocess
- try:
- subprocess.run(
- [sys.executable, "-m", "playwright", "install", "chromium"],
- check=True,
- capture_output=True,
- )
- console.print(" [green]Chromium installed[/]")
- except (subprocess.CalledProcessError, FileNotFoundError):
+ installers = []
+ if importlib.util.find_spec("patchright") is not None:
+ installers.append("patchright")
+ installers.append("playwright")
+ for mod in installers:
+ try:
+ subprocess.run(
+ [sys.executable, "-m", mod, "install", "chromium"],
+ check=True,
+ capture_output=True,
+ )
+ console.print(" [green]Chromium installed[/]")
+ break
+ except (subprocess.CalledProcessError, FileNotFoundError):
+ continue
+ else:
console.print(
" [red]Could not install browser automatically.[/]\n"
- " Run: playwright install chromium"
+ " Run: playwright install chromium\n"
+ " (stealth adapter setups need: python -m patchright install chromium)"
)
diff --git a/tests/test_cli/test_install_browser.py b/tests/test_cli/test_install_browser.py
new file mode 100644
index 0000000..0d1def3
--- /dev/null
+++ b/tests/test_cli/test_install_browser.py
@@ -0,0 +1,72 @@
+"""Browser-setup installer preference: patchright's chromium when present.
+
+The stealth adapter (UndetectedAdapter) launches patchright's pinned chromium,
+which lives in a separate registry from plain playwright's. A setup that only
+runs `playwright install chromium` produces a machine where every preflight
+passes and every browser fetch dies at launch. These tests pin the installer
+order without touching the network or any real browser registry.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import pytest
+
+pytest.importorskip("crawl4ai", reason="crawl4ai extra not installed")
+
+from hyperresearch.cli.install import _setup_crawl4ai
+
+
+def _no_working_browser(monkeypatch):
+ """Force the availability check down the install path: both sync_api
+ imports fail, so _setup_crawl4ai must decide which installer to run."""
+ monkeypatch.setitem(sys.modules, "patchright.sync_api", None)
+ monkeypatch.setitem(sys.modules, "playwright.sync_api", None)
+
+
+def _capture_installs(monkeypatch, fail_mods=()):
+ calls: list[str] = []
+
+ def fake_run(cmd, check, capture_output):
+ mod = cmd[2]
+ calls.append(mod)
+ if mod in fail_mods:
+ import subprocess
+
+ raise subprocess.CalledProcessError(1, cmd)
+ return None
+
+ monkeypatch.setattr("subprocess.run", fake_run)
+ return calls
+
+
+def test_patchright_chromium_preferred_when_patchright_present(
+ tmp_vault, monkeypatch, _no_working_browser):
+ monkeypatch.setattr("importlib.util.find_spec", lambda name: object())
+ calls = _capture_installs(monkeypatch)
+
+ assert _setup_crawl4ai(tmp_vault) == "browser_installed"
+ assert calls == ["patchright"], (
+ "with patchright installed, its own chromium must be installed first; "
+ "plain `playwright install chromium` does not provide it"
+ )
+
+
+def test_plain_playwright_used_when_patchright_absent(
+ tmp_vault, monkeypatch, _no_working_browser):
+ monkeypatch.setattr("importlib.util.find_spec", lambda name: None)
+ calls = _capture_installs(monkeypatch)
+
+ assert _setup_crawl4ai(tmp_vault) == "browser_installed"
+ assert calls == ["playwright"]
+
+
+def test_failed_patchright_install_falls_back_to_playwright(
+ tmp_vault, monkeypatch, _no_working_browser):
+ monkeypatch.setattr("importlib.util.find_spec", lambda name: object())
+ calls = _capture_installs(monkeypatch, fail_mods=("patchright",))
+
+ assert _setup_crawl4ai(tmp_vault) == "browser_installed"
+ assert calls == ["patchright", "playwright"]