# How to Set Up the Browser Environment for Patent-Disclosure-Skill

> Learn how to set up the browser environment for patent-disclosure-skill. Configure Playwright and environment variables for automated browser control, ensuring seamless operation.

- Repository: [handsomestWei/patent-disclosure-skill](https://github.com/handsomestWei/patent-disclosure-skill)
- Tags: getting-started
- Published: 2026-09-05

---

**The patent-disclosure-skill uses Playwright to drive a Chromium-based browser, with automatic fallback from system Chrome → Edge → bundled Chromium, controlled via environment variables `PATENT_BROWSER_CHANNEL` and `PLAYWRIGHT_HEADED`.**

Setting up the browser environment for patent-disclosure-skill enables automated web-based patent searches through the CNIPA and other sources. This guide walks through installation, configuration, and verification based on the actual implementation in `handsomestWei/patent-disclosure-skill`.

## Prerequisites

Before configuring the browser, ensure your system meets these requirements:

- **Python 3.9+** — required by the project's dependencies
- **Playwright** — listed in [`requirements.txt`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/requirements.txt) and installed via pip
- **System Chrome or Microsoft Edge** (optional but recommended) — the skill prefers these over downloading bundled Chromium

## Install Dependencies

Start with the core Python packages.

```bash
pip install -r requirements.txt

```

This installs `playwright` along with other required libraries.

If you do not have system Chrome or Edge installed, download the bundled Chromium binary:

```bash
python -m playwright install chromium

```

## Configure Browser Channel Selection

The skill automatically detects available browsers, but you can override this behavior with environment variables.

### Automatic Detection (Default)

When `PATENT_BROWSER_CHANNEL` is unset, [`browser.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/browser.py) iterates through `_AUTO_CHANNELS` in this order:

1. `chrome` — system Google Chrome
2. `msedge` — system Microsoft Edge  
3. `chromium` — Playwright's bundled Chromium

The `launch_chromium()` function in [`skills/patent-search/tools/browser.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/skills/patent-search/tools/browser.py) attempts each channel until one succeeds.

### Force a Specific Channel

Set `PATENT_BROWSER_CHANNEL` to skip auto-detection:

```bash
export PATENT_BROWSER_CHANNEL=chrome   # Use system Chrome

export PATENT_BROWSER_CHANNEL=msedge   # Use system Edge

export PATENT_BROWSER_CHANNEL=chromium # Use bundled Chromium

```

The `_forced_channel()` helper at lines 52–60 in [`browser.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/browser.py) reads this variable and validates it against allowed values.

## Control Headless vs. Headed Mode

By default, the browser runs headlessly (no visible window). To enable the GUI:

```bash
export PLAYWRIGHT_HEADED=1

```

The `headed()` function (lines 32–38) checks for `1`, `true`, or `yes` in this variable. When `headless=None` is passed to `launch_chromium()`, this environment variable controls the actual behavior.

## Verify Your Setup

Run the built-in probe to confirm everything works:

```bash
python -m skills.patent-search.tools.browser --probe

```

Expected output:

```json
{"playwright": true, "channel": "chrome", "ok": true, "error": null, "hint": null}

```

The `probe_launch()` function (lines 21–28) performs a temporary headless launch and reports status. If `ok` is `false`, the `hint` field contains troubleshooting guidance in Chinese: "请安装 Google Chrome 或 Microsoft Edge 后重试；若均无，再执行：python -m playwright install chromium".

## Programmatic Browser Launch

Import the helper in your own scripts:

```python
from playwright.sync_api import sync_playwright
from skills.patent_search.tools.browser import launch_chromium, headed

with sync_playwright() as p:
    browser, label = launch_chromium(p, headless=None)
    print(f"Successfully launched: {label}")
    
    page = browser.new_page()
    page.goto("https://patents.google.com")
    print(page.title())
    browser.close()

```

The `launch_chromium()` function (lines 67–100) applies these default arguments:
- `--disable-blink-features=AutomationControlled` — reduces bot detection
- `--no-sandbox` — required for containerized environments

## Troubleshooting Common Issues

**Playwright not found**

The `playwright_installed()` check (lines 40–45) raises a clear error suggesting `pip install playwright`.

**All browser channels fail**

If Chrome, Edge, and Chromium all fail to launch, `launch_chromium()` raises `RuntimeError` with a hint to install system browsers or run `python -m playwright install chromium`.

**Permission errors in Docker**

Ensure `--no-sandbox` is passed (automatic) and the container has sufficient `/dev/shm` size for Chromium.

## Summary

- Install dependencies: `pip install -r requirements.txt` and optionally `python -m playwright install chromium`
- Control browser selection via `PATENT_BROWSER_CHANNEL` (chrome/msedge/chromium)
- Toggle visibility with `PLAYWRIGHT_HEADED=1`
- Verify with `python -m skills.patent-search.tools.browser --probe`
- Core logic lives in [`skills/patent-search/tools/browser.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/skills/patent-search/tools/browser.py) with `launch_chromium()`, `headed()`, and `playwright_installed()`

## Frequently Asked Questions

### What browsers does patent-disclosure-skill support?

The skill supports Google Chrome, Microsoft Edge, and Playwright's bundled Chromium. The [`browser.py`](https://github.com/handsomestWei/patent-disclosure-skill/blob/main/browser.py) module prioritizes system-installed Chrome or Edge for faster startup, falling back to downloaded Chromium only when necessary.

### Do I need to install Chrome or Edge if I have Playwright?

No. The bundled Chromium works standalone. However, system browsers launch faster and avoid the ~100MB download. If neither Chrome nor Edge is installed, the skill automatically uses `chromium` after running `python -m playwright install chromium`.

### How do I run the browser in visible mode for debugging?

Set `PLAYWRIGHT_HEADED=1` in your environment before running the skill. This forces `launch_chromium()` to launch with `headless=False`, showing the browser window for interactive debugging or visual confirmation.

### What does the `--probe` flag do?

The probe mode starts a temporary browser instance and outputs JSON status to stdout. It is implemented in `probe_launch()` and called from `main()` when `--probe` is passed. Use it in CI pipelines or agent setups to verify browser availability before invoking full patent searches.