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

> Probe browser availability in patent-disclosure-skill with python tools/shared/browser.py --probe. Get a JSON report on Playwright's ability to launch Chrome, Edge, or Chromium for headless automation.

- Repository: [handsomestWei/patent-disclosure-skill](https://github.com/handsomestWei/patent-disclosure-skill)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/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.

```bash
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

```text
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`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/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.

```python
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`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/tools/shared/mermaid_render.py) and [`tools/crawl/cnipa_epub_search.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/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`:

```bash

# 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`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/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`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/tools/crawl/cnipa_epub_search.py)** – Checks browser availability before initiating CNIPA patent searches
- **[`tests/shared/test_mermaid_browser.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/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`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/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`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/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`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/INSTALL.md) at lines 70–84.