mirror of
https://github.com/hanzoai/python-sdk.git
synced 2026-10-23 20:23:00 +00:00
zeekay
d381e6ea02
Add detailed documentation with examples for: - hanzo-tools-fs: read, write, edit, tree, find, search, ast - hanzo-tools-shell: cmd, ps, zsh, bash, auto-backgrounding - hanzo-tools-browser: 70+ Playwright actions, device emulation - hanzo-tools-memory: memories, facts, knowledge bases, scopes - hanzo-tools-reasoning: think and critic tools - hanzo-tools-lsp: go-to-definition, references, rename, hover - hanzo-tools-refactor: rename, extract, inline, batch operations - hanzo-tools-agent: multi-agent orchestration, consensus, swarm - hanzo-tools-llm: unified LLM interface with 100+ models Each doc includes: - Installation instructions - Quick start examples - Full API reference - Usage examples - Best practices
351 lines
8.4 KiB
Markdown
351 lines
8.4 KiB
Markdown
# hanzo-tools-browser
|
|
|
|
Complete browser automation with full Playwright API. Provides 70+ actions for navigation, forms, mouse control, assertions, and more.
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install hanzo-tools-browser
|
|
playwright install chromium
|
|
```
|
|
|
|
Or as part of the full toolkit:
|
|
|
|
```bash
|
|
pip install hanzo-mcp[tools-all]
|
|
playwright install chromium
|
|
```
|
|
|
|
## Overview
|
|
|
|
`hanzo-tools-browser` provides comprehensive browser automation:
|
|
|
|
- **Navigation**: navigate, reload, go_back, go_forward
|
|
- **Input**: click, type, fill, press, select_option
|
|
- **Mouse**: hover, drag, scroll, mouse_move
|
|
- **Touch**: tap, swipe, pinch (mobile emulation)
|
|
- **Assertions**: expect_visible, expect_text, expect_url
|
|
- **Content**: get_text, get_attribute, screenshot
|
|
- **Storage**: cookies, localStorage, sessionStorage
|
|
- **Network**: route (mock/block requests)
|
|
|
|
## Quick Start
|
|
|
|
```python
|
|
# Navigate to page
|
|
browser(action="navigate", url="https://example.com")
|
|
|
|
# Click a button
|
|
browser(action="click", selector="button.submit")
|
|
|
|
# Fill a form
|
|
browser(action="fill", selector="input[name='email']", text="[email protected]")
|
|
|
|
# Take screenshot
|
|
browser(action="screenshot", full_page=True)
|
|
```
|
|
|
|
## Device Emulation
|
|
|
|
Built-in device presets for responsive testing:
|
|
|
|
```python
|
|
# User-friendly aliases
|
|
browser(action="emulate", device="mobile") # iPhone-like (390x844)
|
|
browser(action="emulate", device="tablet") # iPad-like (1024x1366)
|
|
browser(action="emulate", device="laptop") # MacBook-like (1440x900)
|
|
browser(action="emulate", device="desktop") # Full HD (1920x1080)
|
|
|
|
# Specific devices
|
|
browser(action="emulate", device="iphone_14")
|
|
browser(action="emulate", device="pixel_7")
|
|
browser(action="emulate", device="ipad_pro")
|
|
```
|
|
|
|
## Navigation
|
|
|
|
```python
|
|
# Basic navigation
|
|
browser(action="navigate", url="https://example.com")
|
|
browser(action="reload")
|
|
browser(action="go_back")
|
|
browser(action="go_forward")
|
|
|
|
# Get page info
|
|
browser(action="url") # Current URL
|
|
browser(action="title") # Page title
|
|
browser(action="content") # HTML content
|
|
```
|
|
|
|
## Input Actions
|
|
|
|
```python
|
|
# Click variants
|
|
browser(action="click", selector="button")
|
|
browser(action="dblclick", selector=".item")
|
|
browser(action="right_click", selector=".context-menu")
|
|
|
|
# Text input
|
|
browser(action="type", selector="input", text="Hello", interval=0.1)
|
|
browser(action="fill", selector="input", text="Instant fill")
|
|
browser(action="clear", selector="input")
|
|
|
|
# Keyboard
|
|
browser(action="press", key="Enter")
|
|
browser(action="press", key="Control+c")
|
|
```
|
|
|
|
## Form Handling
|
|
|
|
```python
|
|
# Select dropdowns
|
|
browser(action="select_option", selector="select", value="option1")
|
|
|
|
# Checkboxes
|
|
browser(action="check", selector="input[type='checkbox']")
|
|
browser(action="uncheck", selector="input[type='checkbox']")
|
|
|
|
# File uploads
|
|
browser(action="upload", selector="input[type='file']", files=["./doc.pdf"])
|
|
```
|
|
|
|
## Mouse Control
|
|
|
|
```python
|
|
# Hover
|
|
browser(action="hover", selector=".menu-item")
|
|
|
|
# Drag and drop
|
|
browser(action="drag", selector=".draggable", target_selector=".dropzone")
|
|
|
|
# Scroll
|
|
browser(action="scroll", delta_y=500)
|
|
browser(action="scroll", selector=".container", delta_y=300)
|
|
|
|
# Mouse coordinates
|
|
browser(action="mouse_move", x=100, y=200)
|
|
browser(action="mouse_down")
|
|
browser(action="mouse_up")
|
|
```
|
|
|
|
## Touch & Mobile
|
|
|
|
```python
|
|
# Touch actions
|
|
browser(action="tap", selector="button")
|
|
browser(action="swipe", direction="up", distance=300)
|
|
browser(action="pinch", scale=0.5) # Zoom out
|
|
browser(action="pinch", scale=2.0) # Zoom in
|
|
```
|
|
|
|
## Locators
|
|
|
|
```python
|
|
# CSS/XPath
|
|
browser(action="locator", selector="div.class")
|
|
browser(action="locator", selector="//button[@id='submit']")
|
|
|
|
# Semantic locators
|
|
browser(action="get_by_role", role="button", name="Submit")
|
|
browser(action="get_by_text", text="Click me")
|
|
browser(action="get_by_label", text="Email")
|
|
browser(action="get_by_placeholder", text="Enter email")
|
|
browser(action="get_by_test_id", text="submit-btn")
|
|
|
|
# Composition
|
|
browser(action="first", selector=".items")
|
|
browser(action="last", selector=".items")
|
|
browser(action="nth", selector=".items", index=2)
|
|
browser(action="filter", selector=".items", has_text="Important")
|
|
```
|
|
|
|
## Assertions
|
|
|
|
```python
|
|
# Element assertions
|
|
browser(action="expect_visible", selector=".modal")
|
|
browser(action="expect_hidden", selector=".loading")
|
|
browser(action="expect_enabled", selector="button")
|
|
browser(action="expect_text", selector="h1", expected="Welcome")
|
|
browser(action="expect_count", selector=".items", index=5)
|
|
|
|
# Page assertions
|
|
browser(action="expect_url", expected="*/dashboard*")
|
|
browser(action="expect_title", expected="Dashboard")
|
|
|
|
# Negative assertions
|
|
browser(action="expect_visible", selector=".loading", not_=True)
|
|
```
|
|
|
|
## Content Extraction
|
|
|
|
```python
|
|
# Get text content
|
|
browser(action="get_text", selector="h1")
|
|
browser(action="get_inner_text", selector=".content")
|
|
|
|
# Get attributes
|
|
browser(action="get_attribute", selector="a", attribute="href")
|
|
browser(action="get_value", selector="input")
|
|
|
|
# Get HTML
|
|
browser(action="get_html", selector=".container")
|
|
|
|
# Get bounding box
|
|
browser(action="get_bounding_box", selector=".element")
|
|
```
|
|
|
|
## State Checking
|
|
|
|
```python
|
|
browser(action="is_visible", selector=".modal")
|
|
browser(action="is_hidden", selector=".loading")
|
|
browser(action="is_enabled", selector="button")
|
|
browser(action="is_editable", selector="input")
|
|
browser(action="is_checked", selector="input[type='checkbox']")
|
|
```
|
|
|
|
## Screenshots & PDFs
|
|
|
|
```python
|
|
# Screenshots
|
|
browser(action="screenshot")
|
|
browser(action="screenshot", full_page=True)
|
|
browser(action="screenshot", selector=".chart")
|
|
|
|
# PDF export
|
|
browser(action="pdf")
|
|
```
|
|
|
|
## Wait Operations
|
|
|
|
```python
|
|
# Wait for load states
|
|
browser(action="wait_for_load", state="networkidle")
|
|
browser(action="wait_for_url", url="*/success*")
|
|
|
|
# Wait for elements
|
|
browser(action="wait", selector=".loaded", state="visible")
|
|
browser(action="wait", timeout=5000)
|
|
|
|
# Wait for events
|
|
browser(action="wait_for_event", event="download")
|
|
browser(action="wait_for_response", pattern="*/api/*")
|
|
```
|
|
|
|
## Network Interception
|
|
|
|
```python
|
|
# Mock API responses
|
|
browser(
|
|
action="route",
|
|
pattern="*/api/users*",
|
|
response={"users": [{"name": "Mock User"}]},
|
|
status_code=200
|
|
)
|
|
|
|
# Block requests
|
|
browser(action="route", pattern="*.png", block=True)
|
|
|
|
# Remove route
|
|
browser(action="unroute", pattern="*/api/users*")
|
|
```
|
|
|
|
## Storage
|
|
|
|
```python
|
|
# Cookies
|
|
browser(action="cookies")
|
|
browser(action="cookies", cookies=[{"name": "token", "value": "abc"}])
|
|
browser(action="clear_cookies")
|
|
|
|
# Local/Session storage
|
|
browser(action="storage", storage_type="local")
|
|
browser(action="storage", storage_type="session", storage_data={"key": "value"})
|
|
|
|
# Save/restore auth state
|
|
browser(action="storage_state", auth_file="./auth.json")
|
|
```
|
|
|
|
## Tab Management
|
|
|
|
```python
|
|
# Multiple tabs
|
|
browser(action="new_tab", url="https://example.com")
|
|
browser(action="tabs") # List all tabs
|
|
browser(action="close_tab", tab_index=1)
|
|
```
|
|
|
|
## Parallel Agents
|
|
|
|
For parallel execution, create isolated contexts:
|
|
|
|
```python
|
|
# Create new context (isolated cookies/storage)
|
|
browser(action="new_context")
|
|
|
|
# Each agent uses separate context
|
|
# One Chrome process, many parallel sessions
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Headless Mode
|
|
|
|
```python
|
|
# Toggle headless mode
|
|
browser(action="set_headless", headless=True)
|
|
browser(action="set_headless", headless=False) # Show browser
|
|
```
|
|
|
|
### CDP Connection
|
|
|
|
Share browser instance across MCPs:
|
|
|
|
```bash
|
|
BROWSER_CDP_ENDPOINT=http://localhost:9222 hanzo-mcp
|
|
```
|
|
|
|
## Examples
|
|
|
|
### Login Flow
|
|
|
|
```python
|
|
# Navigate to login
|
|
browser(action="navigate", url="https://app.example.com/login")
|
|
|
|
# Fill credentials
|
|
browser(action="fill", selector="input[name='email']", text="[email protected]")
|
|
browser(action="fill", selector="input[name='password']", text="password123")
|
|
|
|
# Submit
|
|
browser(action="click", selector="button[type='submit']")
|
|
|
|
# Wait for redirect
|
|
browser(action="wait_for_url", url="*/dashboard*")
|
|
|
|
# Verify login
|
|
browser(action="expect_visible", selector=".user-menu")
|
|
```
|
|
|
|
### E2E Test
|
|
|
|
```python
|
|
# Test shopping cart
|
|
browser(action="navigate", url="https://shop.example.com")
|
|
browser(action="click", selector=".product-card:first-child button")
|
|
browser(action="expect_text", selector=".cart-count", expected="1")
|
|
browser(action="click", selector=".cart-icon")
|
|
browser(action="expect_visible", selector=".cart-modal")
|
|
browser(action="expect_text", selector=".total", expected="$99.00")
|
|
```
|
|
|
|
### Screenshot Comparison
|
|
|
|
```python
|
|
# Capture baseline
|
|
browser(action="navigate", url="https://example.com")
|
|
browser(action="screenshot", full_page=True)
|
|
# Returns base64 image for comparison
|
|
```
|