# Browsing
**Rust-native browser automation — 20+ CDP managers, MCP server, zero AI deps**
| **Binary size** | ~2–5 MB release (LTO + strip + `opt-level = "z"`) |
| **Test coverage** | 360+ tests, all passing |
| **CDP domains covered** | Page, Network, Fetch, Emulation, Tracing, Profiler, CSS, DOM, Runtime, Target, ServiceWorker, Input, Browser, Console |
| **Zero** | LLM dependencies, `Box::leak`, recursive async retry |
## 🗺️ Where Does Browsing Fit?
| Selenium | Java/Python | Legacy testing | Heavy WebDriver | Indirect |
| Puppeteer | JavaScript | Chrome scripts | ~50 MB Node | Thin wrapper |
| Playwright | JS/Python | Cross-browser tests | ~200 MB | Batteries-included, opinionated |
| browser-use | Python | LLM agents | Python + AI deps | Hidden behind agent loop |
| **Browsing** | **Rust** | **Fast, embeddable automation** | **~2–5 MB** | **Raw + 20 typed managers** |
Browsing gives you Playwright's feature coverage (dialogs, file choosers, device presets, permissions, HAR, tracing, touch, workers, service workers) in a Rust-native, zero-bloat package with an MCP server for LLM integration.
## 🎯 Key Features
### 🏗️ Architecture
- **Trait-based** — `BrowserClient`, `DOMProcessor`, `ActionHandler` for mocking and backends
- **20+ typed managers** — Each wraps a CDP domain: Dialog, FileChooser, Permissions, HAR, Interceptor, Performance, Coverage, Tracing, Touch, Worker, ServiceWorker, Viewport (with device presets, color scheme, vision deficiency, locale), Auth, Console, Cookies, PDF
- **Headless by default** — 17+ lightweight Chrome flags; `BrowserProfile::default()` runs `--headless=new`
- **Raw CDP access** — `Browser::raw_cdp_command()` for anything the managers don't cover
- **Zero AI dependencies** — Pure Rust, no LLM lock-in
## 📦 Installation
### As a Library
```toml
[dependencies]
browsing = "0.1"
tokio = { version = "1.40", features = ["full"] }
```
### As a CLI Tool
```bash
cargo install --path . --bin browsing
```
### As an MCP Server
```bash
cargo build --release --bin browsing-mcp
```
## 🚀 Quick Start
### 1️⃣ CLI Usage
```bash
# Run a browser automation task (headless by default)
browsing run "Navigate to example.com and extract content" --url https://news.ycombinator.com
# Run with visible browser
browsing run "Navigate to example.com and extract content" --url https://news.ycombinator.com --no-headless
# Launch a headless browser and get CDP URL (headless by default)
browsing launch
# Launch with visible browser
browsing launch --no-headless
# Connect to existing browser
browsing connect ws://localhost:9222/devtools/browser/abc123
```
**📖 [Full CLI Documentation](docs/CLI_USAGE.md)**
### 2️⃣ MCP Server Usage
Configure in Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"browsing": {
"command": "/path/to/browsing/target/release/browsing-mcp",
"env": {
"BROWSER_USE_HEADLESS": "true"
}
}
}
}
```
Then ask Claude:
```
"Navigate to rust-lang.org, get the links, follow the second link, and screenshot the main content area"
```
**📖 [Full MCP Documentation](docs/MCP_USAGE.md)**
### 3️⃣ Library Usage
```rust
use anyhow::Result;
use browsing::Browser;
use browsing::browser::BrowserProfile;
#[tokio::main]
async fn main() -> Result<()> {
browsing::init();
let mut browser = Browser::new(BrowserProfile::default());
browser.start().await?;
browser.navigate("https://example.com").await?;
let title = browser.get_current_page_title().await?;
println!("Title: {}", title);
let _ = browser.stop().await;
Ok(())
}
```
**📖 [Full Library Documentation](docs/LIBRARY_USAGE.md)**
### Browser Launch Options
```rust
use browsing::{Browser, BrowserProfile};
// Option 1: Auto-launch headless browser (default)
let profile = BrowserProfile::default(); // headless = true by default
let browser = Browser::new(profile);
// Option 2: Launch with visible browser
let profile = BrowserProfile::default().with_headless(false);
let browser = Browser::new(profile);
// Option 3: Connect to existing browser
let browser = Browser::new(BrowserProfile::default())
.with_cdp_url("http://localhost:9222".to_string());
// Option 4: Custom browser executable
use browsing::browser::launcher::BrowserLauncher;
let launcher = BrowserLauncher::new(profile)
.with_executable_path(std::path::PathBuf::from("/path/to/chrome"));
```
## 📚 Quick Example
```rust
use browsing::browser::{Browser, BrowserProfile};
#[tokio::main]
async fn main() -> browsing::Result<()> {
let mut browser = Browser::new(BrowserProfile::default());
browser.start().await?;
browser.navigate("https://example.com").await?;
// Use any manager
let viewport = browser.viewport_manager()?;
viewport.preset_device(&browsing::DevicePreset::iphone_15()).await?;
// Or send raw CDP
let result = browser
.raw_cdp_command("Runtime.evaluate", json!({"expression": "1+1"}))
.await?;
Ok(())
}
```
**More examples:** See [`examples/`](examples/) — device emulation, dialog handling, HAR capture, permissions, touch gestures, raw CDP access.
## 🏗️ Architecture
```
┌──────────┬──────────────┬────────────────────────┐
│ Browser │ DOMProcessor │ Tools │
│ (trait) │ (trait) │ │
└────┬─────┴──────┬───────┴───────────────┬────────┘
│ │ │
┌────▼────┐ ┌───▼────┐ ┌─────────▼──────┐
│ Browser │ │ DomSvc │ │ Handlers │
│ Session │ │ │ │ (nav, click, │
│ + 20+ │ │ CDP │ │ tabs, content)│
│ managers│ │ HTML │ │ │
└─────────┘ └────────┘ └────────────────┘
```
See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for full design.
## 📁 Project Structure
```
browsing/
├── src/
│ ├── agent/ # Agent view types (used by tools layer)
│ │ ├── views.rs # Data types
│ │ └── memory.rs # Session memory types
│ ├── browser/ # Browser management
│ │ ├── session.rs # Browser session (BrowserClient impl)
│ │ ├── tab_manager.rs # Tab operations
│ │ ├── navigation.rs # Navigation operations
│ │ ├── screenshot.rs # Screenshot operations
│ │ ├── cdp.rs # CDP WebSocket client
│ │ ├── launcher.rs # Browser launcher
│ │ ├── profile.rs # Browser configuration
│ │ ├── auth.rs # HTTP auth / proxy / extra headers
│ │ ├── console.rs # Console log capture
│ │ ├── cookies.rs # Cookie management
│ │ ├── coverage.rs # JS/CSS coverage tracking
│ │ ├── dialog.rs # Dialog handling (alert/confirm/prompt)
│ │ ├── download.rs # Download monitoring
│ │ ├── filechooser.rs # File chooser interception
│ │ ├── har.rs # Network traffic HAR capture
│ │ ├── interceptor.rs # Network request interception
│ │ ├── pdf.rs # PDF export
│ │ ├── performance.rs # Performance metrics
│ │ ├── permissions.rs # Browser permissions API
│ │ ├── serviceworker.rs # Service worker management
│ │ ├── touch.rs # Touch gesture emulation
│ │ ├── tracing.rs # Chrome tracing / CPU profiling
│ │ ├── viewport.rs # Viewport / device emulation
│ │ ├── worker.rs # Web worker management
│ │ └── views.rs # Data types
│ ├── dom/ # DOM processing
│ │ ├── processor.rs # DOMProcessor trait impl
│ │ ├── serializer.rs # Text serialization
│ │ ├── tree_builder.rs # DOM tree construction
│ │ ├── cdp_client.rs # CDP wrapper for DOM
│ │ └── html_converter.rs # HTML to markdown
│ ├── tools/ # Action system
│ │ ├── service.rs # Tools registry
│ │ ├── handlers/ # Action handlers
│ │ │ ├── navigation.rs
│ │ │ ├── interaction.rs
│ │ │ ├── tabs.rs
│ │ │ ├── content.rs
│ │ │ └── advanced.rs
│ │ └── params.rs # Parameter extraction
│ ├── traits/ # Core trait abstractions
│ │ ├── browser_client.rs # BrowserClient trait
│ │ └── dom_processor.rs # DOMProcessor trait
│ ├── actor/ # Low-level interactions
│ │ ├── page.rs # Page operations
│ │ ├── element.rs # Element operations
│ │ ├── mouse.rs # Mouse interactions
│ │ └── keyboard.rs # Keyboard input
│ ├── config.rs # Configuration
│ ├── error.rs # Error types
│ ├── logging.rs # Logging setup
│ ├── metrics.rs # Metrics collection
│ ├── utils.rs # Utilities
│ └── views.rs # Shared data types
└── Cargo.toml
```
## 🧪 Testing
```bash
# Run all tests
cargo test
# Run with output
cargo test -- --nocapture
# Run specific test
cargo test test_browser_navigation
# Run integration tests only
cargo test --test integration
```
### Test Coverage
**360+ tests**, all passing, 0 ignored. Every manager has unit tests. Mock implementations for deterministic testing without real browsers.
| Actor | 29 | Page, Element, Mouse, Keyboard |
| Browser | 154 | All 20+ managers + lifecycle |
| Tools | 67 | Action handlers + registry |
| Traits | 27 | BrowserClient, DOMProcessor mocks |
| Utils | 52 | URL extraction, signals |
| Integration | 115+ | End-to-end workflows |
## ⚠️ Data Retention
Browser data is **never deleted** to prevent accidental loss of real profiles. Temp directories in `/tmp/browser-use-*` are left for inspection; clean them manually.
```bash
rm -rf /tmp/browser-use-*
```
## 🔧 Configuration
```rust
use browsing::BrowserProfile;
let profile = BrowserProfile::default(); // headless, lightweight flags
let profile = BrowserProfile::default().with_headless(false); // visible
let profile = BrowserProfile {
user_data_dir: Some("/path/to/profile".into()),
..Default::default()
};
```
## 📖 API Documentation
Generate and view API docs:
```bash
cargo doc --open
```
