How to Probe for Browser Availability in patent-disclosure-skill

Run python tools/shared/browser.py --probe to check if Playwright can launch Chrome, Edge, or Chromium, returning a JSON report that indicates whether headless browser automation is available.

The patent-disclosure-skill repository relies on browser automation for generating Mermaid diagram screenshots and crawling CNIPA patent data. Before executing these tasks, the codebase verifies that a Chromium-compatible browser can actually launch on the host machine using a dedicated probe mechanism implemented in tools/shared/browser.py.

Command-Line Probe Usage

The simplest way to verify browser availability is through the built-in CLI probe. From the repository root, execute the probe command to attempt launching a browser in headless mode and receive an immediate diagnostic report.

python tools/shared/browser.py --probe

The command produces two distinct outputs:

• stderr – A human-readable one-line status (e.g., PROBE: ok=true channel=chrome …)
• stdout – A JSON object for programmatic parsing

PROBE: ok=true channel=chrome error=
{"playwright":true,"channel":"chrome","ok":true,"error":null,"hint":null}

If the launch fails, the JSON includes an error field and a hint field with installation instructions, such as prompting the user to install Google Chrome or Microsoft Edge, or to run python -m playwright install chromium.

Anatomy of the Probe Report

The probe_launch() function in tools/shared/browser.py orchestrates the check by first calling playwright_installed() to verify the package is importable, then attempting launch_chromium() with headless=True. The function returns a dictionary with the following keys:

• playwright – Boolean indicating if the Playwright package is installed
• channel – The specific browser that succeeded (chrome, msedge, or chromium)
• ok – Boolean indicating whether a browser instance was successfully launched
• error – Error message string if launching failed, otherwise null
• hint – User-friendly installation guidance when ok is false

The launch order follows the internal _AUTO_CHANNELS constant: Chrome → Edge → bundled Chromium.

Programmatic Integration

Other tools throughout the repository import the shared browser module to check availability before attempting screenshot generation. You can integrate the probe into Python scripts by invoking the CLI via subprocess or by importing the module directly.

import json
import subprocess
import sys
from pathlib import Path

def probe_browser() -> dict:
    """Run the probe script and return the parsed JSON report."""
    script = Path("tools/shared/browser.py")
    proc = subprocess.run(
        [sys.executable, str(script), "--probe"],
        capture_output=True,
        text=True,
        check=False,
    )
    try:
        report = json.loads(proc.stdout.strip())
    except json.JSONDecodeError:
        raise RuntimeError(f"Probe failed, cannot parse JSON: {proc.stdout!r}")
    return report

if __name__ == "__main__":
    result = probe_browser()
    if result["ok"]:
        print(f"✅ Browser ready (channel={result['channel']})")
    else:
        print(f"❌ Cannot start browser: {result['error']}")
        print(f"Hint: {result['hint']}")

Scripts like tools/shared/mermaid_render.py and tools/crawl/cnipa_epub_search.py use this pattern to decide whether to generate PNG images or fall back to SVG-only output when browser automation is unavailable.

Configuring Browser Channel and Headless Mode

You can influence probe behavior using environment variables before running the command.

Force a specific browser instead of relying on auto-detection by setting PATENT_BROWSER_CHANNEL:

# Force Microsoft Edge

PATENT_BROWSER_CHANNEL=msedge python tools/shared/browser.py --probe

Control UI visibility for other Playwright operations (note that the probe itself always runs headless):

• PLAYWRIGHT_HEADED=1 (or true/yes) forces Playwright to run with a visible UI for actual screenshot tasks
• The probe ignores this variable because its purpose is detecting launch capability without opening windows

Where the Probe Is Used

The browser probe is integrated into several components across the codebase:

• tools/shared/mermaid_render.py – Uses the probe to determine if Mermaid diagrams can be rendered as PNG screenshots
• tools/crawl/cnipa_epub_search.py – Checks browser availability before initiating CNIPA patent searches
• tests/shared/test_mermaid_browser.py – Unit tests that verify the probe_launch() and launch_chromium() logic

Summary

• Run python tools/shared/browser.py --probe to verify Playwright installation and browser launch capability
• The probe attempts Chrome, then Edge, then bundled Chromium automatically based on the _AUTO_CHANNELS order
• JSON output includes ok, channel, playwright, error, and installation hint fields for robust error handling
• Set PATENT_BROWSER_CHANNEL=chrome|msedge|chromium to force a specific browser channel instead of auto-detection
• Consumer tools like mermaid_render.py rely on this probe to gracefully fall back to SVG output when browser automation is unavailable

Frequently Asked Questions

What does it mean if the probe returns "ok": false?

This indicates that launch_chromium() failed to start any browser channel after trying Chrome, Edge, and bundled Chromium. The error field contains the specific exception message, while the hint field provides actionable next steps, such as installing Google Chrome or running python -m playwright install chromium to download the bundled browser.

Can I force the probe to use a specific browser like Edge instead of Chrome?

Yes. Set the PATENT_BROWSER_CHANNEL environment variable to msedge, chrome, or chromium before running the probe. This bypasses the automatic detection logic and attempts to launch only the specified browser channel.

Does the probe open a visible browser window on my screen?

No. The probe always executes with headless=True regardless of the PLAYWRIGHT_HEADED environment variable setting. This design ensures the detection process runs silently in the background without UI interruption. The PLAYWRIGHT_HEADED variable only affects subsequent screenshot or automation tasks, not the availability probe itself.

Where is the probe logic implemented in the source code?

The core logic resides in tools/shared/browser.py, specifically within the probe_launch() function for the diagnostic report and launch_chromium() for the actual browser instantiation. The playwright_installed() function handles the initial Python package check. Installation documentation referencing the probe can be found in INSTALL.md at lines 70–84.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}