cdp-browser-lite

Total lifecycle control for Chrome instances, seamlessly integrating with cdp-lite.

Overview

cdp-browser-lite provides the ability to spawn, attach, and manage Google Chrome or Chromium instances, ensuring correct cleanup, avoiding zombie processes, and offering a reliable interface for Headless Chrome automation.

It re-exports the complete interface of cdp-lite for convenient access to the Chrome DevTools Protocol.

Quickstart

use cdp_browser_lite::browser::Browser;
use cdp_browser_lite::config::{BrowserConfig, LaunchMode};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = BrowserConfig::builder()
        .mode(LaunchMode::LaunchNew)
        .port(0) // Auto ephemeral port
        .headless(true)
        .build();

    let browser = Browser::ensure(config).await?;
    let mut client = browser.client().await?;
    
    let version = client.send_raw_command("Browser.getVersion", serde_json::json!({})).await?;
    println!("Chrome Version: {}", version.result.as_ref().unwrap()["product"]);

    browser.stop().await?;
    Ok(())
}

Launch Modes

• LaunchNew: Always spawns a new managed browser process.
• AttachOnly: Attaches to an already running instance.
• Auto: Tries to attach first, and if unavailable, launches a new instance.

Profile Modes

• Ephemeral: Creates a temporary profile that is cleaned up when dropped.
• Persistent: Uses a persistent directory.
• UserDefault: Omits the profile flag, using the system's default Chrome profile.

Troubleshooting

• CHROME_PATH: Set CHROME_PATH to specify a custom Chrome executable location.
• Docker/Sandbox: If running in Docker, you may need to add .no_sandbox(true) to BrowserConfigBuilder.

Supported Platforms

Every push and pull request is validated by CI, which lints (clippy, rustfmt), builds and runs the full test suite on the three major operating systems, and then proves the library links into runnable executables by building native binaries for each target:

Pushing a version tag (vX.Y.Z) triggers the release workflow, which packages the compiled binaries for each platform and attaches them to the corresponding GitHub Release.