Surf AI - Browser Automation Library

A modular browser automation library designed for AI agents and automated testing.

Features

• 🚀 Fast & Reliable: Built on Chrome DevTools Protocol for stable browser control
• 🤖 AI-Friendly: Designed specifically for AI agents with smart element detection
• 🔧 Modular Architecture: Clean separation of concerns with pluggable components
• 📱 Cross-Platform: Works on Windows, macOS, and Linux
• 🎯 Element Highlighting: Visual element identification for debugging
• 🔄 Session Management: Save and restore browser sessions
• 📸 Screenshots: Built-in screenshot capabilities

Quick Start

Add this to your Cargo.toml:

[dependencies]
surf-ai = "0.1.0"
tokio = { version = "1.0", features = ["full"] }

Basic usage:

use surf_ai::{BrowserSession, ChromeBrowser, Config};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a browser session
    let mut session = BrowserSession::demo_mode().await?;

    // Navigate to a website
    session.navigate_and_wait_reactive("https://www.google.com").await?;

    // Highlight interactive elements
    let highlights = session.highlight_interactive_elements().await?;
    println!("Found {} interactive elements", highlights.len());

    // Type in a search box
    session.type_in_element_by_number(1, "Hello World").await?;

    // Click a button
    session.click_element_by_number(2).await?;

    Ok(())
}

Examples

Google Search

use surf_ai::BrowserSession;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut session = BrowserSession::demo_mode().await?;

    session.navigate_and_wait_reactive("https://www.google.com").await?;
    session.highlight_interactive_elements().await?;

    // Type in search box (usually element #1)
    session.type_in_element_by_number(1, "Rust programming").await?;

    // Press search button or enter
    session.click_element_by_number(2).await?;

    tokio::time::sleep(tokio::time::Duration::from_secs(3)).await;
    Ok(())
}

Session Management

use surf_ai::{BrowserSession, LoginConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut session = BrowserSession::demo_mode().await?;

    // Auto-login and save session
    let session_data = session.auto_login_and_extract_session(
        "https://example.com/login",
        "username",
        "password",
        LoginConfig::default()
    ).await?;

    // Later, restore the session
    session.inject_session(session_data).await?;

    Ok(())
}

Architecture

• Core: Abstract traits and configuration
• Browser: Browser implementations (Chrome, Firefox support planned)
• DOM: Smart DOM processing and element detection
• Actions: Extensible action system
• Session: Session management and state persistence

Requirements

• Chrome/Chromium browser installed
• Rust 1.70+