Skip to content

browser.md

Latest commit

 

History

History
147 lines (99 loc) · 4.15 KB

browser.md

File metadata and controls

147 lines (99 loc) · 4.15 KB
Raw

Browser v0.5

PyAgentCLI includes a first local page inspection tool:

inspect_page(url, max_chars=2000)
browser_dom_snapshot(url, max_chars=2000)
browser_query_selector(url, selector, max_results=20)
browser_console_logs(url, wait_ms=500)
browser_screenshot(url, output_path=".pyagent/browser/screenshot.png")
browser_interact(url, actions, max_chars=2000)
browser_network_logs(url, wait_ms=500, max_entries=50)
browser_assert(url, expected_text, selector, expected_status, wait_ms=500)

This is a deliberately local-first browser slice. It lets the agent inspect local HTML pages and localhost web apps without opening arbitrary external websites.

Supported URLs

Allowed:

  • workspace-relative HTML paths, such as site/index.html
  • file:// URLs inside the workspace
  • http://localhost:*
  • http://127.0.0.1:*
  • http://[::1]:*

Denied by default:

  • external HTTP or HTTPS URLs
  • unsupported schemes
  • file:// URLs outside the workspace

Output

inspect_page returns:

  • final URL
  • page title
  • normalized text snapshot

It skips script, style, and noscript content.

browser_dom_snapshot returns a more UI-oriented static snapshot:

  • final URL
  • page title
  • headings
  • links
  • controls
  • normalized text snapshot

browser_query_selector supports simple read-only lookup for:

  • tag selectors such as main
  • id selectors such as #app
  • class selectors such as .status

Complex CSS selectors are intentionally rejected in this static parser slice.

browser_assert checks local pages against expected conditions:

  • expected text in the page body
  • selector presence
  • main page status

Without Playwright, it uses a static local HTML fallback for workspace files and localhost HTML. Static selector fallback supports tag, #id, and .class selectors. With Playwright installed, it uses the rendered page after wait_ms, so CSS selectors and JavaScript-updated DOM text can be checked.

browser_console_logs, browser_screenshot, browser_interact, and browser_network_logs are optional Playwright-backed tools. If Playwright is not installed, they return a clear failure explaining that optional browser dependencies are missing.

browser_network_logs returns request and response summaries:

  • method
  • URL
  • status
  • resource type
  • failure reason

It does not record request bodies, response bodies, or headers.

browser_interact supports approved local interactions:

  • click with a selector
  • type or fill with a selector and text
  • wait with wait_ms

It is classified as EXECUTE risk, so it goes through the same approval path as other side-effecting tools. It returns the resulting title and normalized body text after all actions run.

Example:

URL: file:///path/to/site/index.html
Title: Demo Page

Text:
Hello PyAgent Status READY

Optional Playwright Support

Browser v0.5 keeps Playwright optional:

  • no browser dependency is required for the core CLI
  • DOM snapshots and static browser assertions work without Playwright for local HTML
  • console logs, screenshots, and network logs require Playwright when available
  • rendered DOM assertions use Playwright when available
  • click/type/wait interactions require Playwright and approval
  • screenshot output is restricted to .pyagent/browser/

Check local browser capability status:

pyagent --check-browser

Install optional browser support:

python -m pip install -e ".[browser]"
python -m playwright install chromium

Install and browser binary setup are intentionally explicit, not automatic.

Optional success-path verification:

.venv/bin/python -m pytest tests/test_browser_playwright_optional.py

Those tests are skipped when the Playwright Python package is missing. If the package is installed but Chromium has not been installed yet, they also skip with a browser-binary message.

Eval Coverage

pyagent --eval includes browser assertion evals that run without Playwright:

  • local static HTML expected text, selector, and status assertions
  • external URL denial

The report writes these as browser_assertion JSONL rows.

Non-Goals

Browser v0.5 does not yet include:

  • complex CSS selector support
  • external website browsing