Rustenium

A modern, high-performance WebDriver BiDi automation library for Rust.

Rustenium provides a powerful and ergonomic API for browser automation using the WebDriver BiDi protocol. It offers both low-level control and high-level abstractions for common automation tasks.

Features

• WebDriver BiDi Protocol: Built on the modern BiDi protocol for bidirectional communication
• Chrome Support: First-class support for Chrome/Chromium browsers
• Flexible Input Methods:
  • BidiMouse: Direct, precise mouse movements for fast automation
  • HumanMouse: Realistic mouse movements with Bezier curves and jitter to mimic human behavior
  • Keyboard: Full keyboard support with modifier keys
  • Touchscreen: Multi-touch gesture support for mobile testing
• CSS & XPath Selectors: Convenient macros (css!(), xpath!()) for element location
• Screenshot Capture: Take screenshots of elements or entire pages
• Network Interception: Monitor and intercept network requests
• Event System: Subscribe to browser events in real-time
• Type-Safe API: Leverages Rust's type system for compile-time safety

Installation

Add Rustenium to your Cargo.toml:

[dependencies]
rustenium = "0.1.1"
tokio = { version = "1", features = ["full"] }

Quick Start

use rustenium::browsers::{ChromeBrowser, ChromeConfig, create_chrome_browser};
use rustenium::css;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a Chrome browser instance
    let config = ChromeConfig::default();
    let browser = create_chrome_browser(config, None).await?;

    // Navigate to a page
    browser.navigate("https://example.com").await?;

    // Find and interact with elements
    let search_box = browser.find_element(css!("input[type='search']")).await?;
    search_box.send_keys("Rustenium").await?;

    let submit_button = browser.find_element(css!("button[type='submit']")).await?;
    submit_button.click().await?;

    // Take a screenshot
    browser.screenshot(None, None, Some("screenshot.png")).await?;

    // Close the browser
    browser.close().await?;

    Ok(())
}

Examples

Browser Setup and Navigation

use rustenium::browsers::{ChromeConfig, create_chrome_browser, ChromeCapabilities};

// Create custom configuration
let mut config = ChromeConfig::default();
config.headless = true;

// Configure capabilities
let mut caps = ChromeCapabilities::default();
caps.add_arg("--disable-gpu")
    .add_arg("--window-size=1920,1080")
    .accept_insecure_certs(true);

// Create browser with custom config
let browser = create_chrome_browser(config, Some(caps)).await?;

// Navigate and wait for load
browser.navigate("https://example.com").await?;

Finding Elements

use rustenium::css;
use rustenium::xpath;

// Using CSS selectors
let element = browser.find_element(css!("#my-id")).await?;
let buttons = browser.find_elements(css!(".btn-primary")).await?;

// Using XPath
let header = browser.find_element(xpath!("//h1[@class='title']")).await?;

Mouse Input - Precise Movements

use rustenium::input::{BidiMouse, Point};

let mouse = BidiMouse::new(session);

// Instant, precise movements
mouse.move_to(Point { x: 100.0, y: 200.0 }, &context, None).await?;
mouse.click(None, &context, None).await?;

// Double-click
mouse.click(
    Some(Point { x: 300.0, y: 400.0 }),
    &context,
    Some(MouseClickOptions {
        count: Some(2),
        ..Default::default()
    })
).await?;

Mouse Input - Human-Like Movements

use rustenium::input::{BidiMouse, HumanMouse, Point};

let bidi_mouse = BidiMouse::new(session);
let human_mouse = HumanMouse::new(bidi_mouse);

// Realistic movements with Bezier curves and jitter
human_mouse.move_to(Point { x: 500.0, y: 300.0 }, &context, None).await?;
human_mouse.click(None, &context, None).await?;

// Scroll with natural delays
human_mouse.wheel(&context, Some(MouseWheelOptions {
    delta_y: Some(100),
    ..Default::default()
})).await?;

Keyboard Input

use rustenium::input::Keyboard;

let keyboard = Keyboard::new(session);

// Type text
keyboard.type_text("Hello, World!", &context, None).await?;

// Press special keys
keyboard.press("Enter", &context, None).await?;
keyboard.press("Tab", &context, None).await?;

// Modifier key combinations
keyboard.down("Control", &context).await?;
keyboard.press("a", &context, None).await?; // Ctrl+A
keyboard.up("Control", &context).await?;

Multi-Touch Gestures

use rustenium::input::Touchscreen;
use std::sync::Arc;

let touchscreen = Arc::new(Touchscreen::new(session));

// Pinch gesture with two fingers
let touch1 = touchscreen.touch_start(100.0, 200.0, &context, None).await?;
let touch2 = touchscreen.touch_start(300.0, 200.0, &context, None).await?;

// Move fingers closer together
touch1.move_to(150.0, 200.0, &context).await?;
touch2.move_to(250.0, 200.0, &context).await?;

// Release touches
touch1.end(&context).await?;
touch2.end(&context).await?;

Screenshots

use rustenium_bidi_commands::browsing_context::types::OriginUnion;

// Capture full viewport
browser.screenshot(None, None, Some("viewport.png")).await?;

// Capture specific element
let element = browser.find_element(css!("#content")).await?;
element.screenshot(None, None, Some("element.png")).await?;

Network Interception

// Intercept and handle network requests
browser.on_request_bidi(|request| async move {
    println!("Request URL: {}", request.params.base_parameters.request.url);

    // Block requests to specific domains
    if request.params.base_parameters.request.url.contains("ads.example.com") {
        let _ = request.abort().await;
    }
}).await?;

// Add authentication handler
browser.add_authentication(|params| async move {
    // Return credentials for authentication challenges
    AuthenticationCredentials {
        username: "user".to_string(),
        password: "pass".to_string(),
    }
}).await?;

Documentation

Full API documentation is available on docs.rs.

Browser Support

Currently supported browsers:

• Chrome/Chromium (stable, beta, dev, canary)

Support for Firefox and other browsers is planned for future releases.

Requirements

• Rust 1.75 or later
• Chrome/Chromium browser installed (for Chrome automation)

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.