firefox_webdriver/
lib.rs

1//! Firefox WebDriver - Undetectable browser automation library.
2//!
3//! This library provides a high-level API for automating Firefox browser
4//! using a custom WebExtension-based architecture.
5//!
6//! # Architecture
7//!
8//! The driver follows a client-server model:
9//!
10//! - **Local End (Rust)**: Sends commands, receives events via WebSocket
11//! - **Remote End (Extension)**: Executes commands in Firefox, emits events
12//!
13//! Key design principles:
14//!
15//! - [`Driver`] owns a shared [`ConnectionPool`](transport::ConnectionPool) (single WebSocket port)
16//! - Each [`Window`] owns: Firefox process + profile, references shared pool
17//! - Protocol uses `module.methodName` format (BiDi-inspired)
18//! - Elements stored by reference in content script `Map` (undetectable)
19//! - Event-driven architecture (no polling)
20//!
21//! # Quick Start
22//!
23//! ```no_run
24//! use firefox_webdriver::{Driver, Result};
25//!
26//! #[tokio::main]
27//! async fn main() -> Result<()> {
28//!     // Build driver with Firefox binary and extension paths
29//!     let driver = Driver::builder()
30//!         .binary("/path/to/firefox")
31//!         .extension("/path/to/extension")
32//!         .build()
33//!         .await?;
34//!
35//!     // Spawn a headless browser window
36//!     let window = driver.window().headless().spawn().await?;
37//!     let tab = window.tab();
38//!
39//!     // Navigate and interact
40//!     tab.goto("https://example.com").await?;
41//!     let title = tab.get_title().await?;
42//!     println!("Page title: {}", title);
43//!
44//!     Ok(())
45//! }
46//! ```
47//!
48//! # Modules
49//!
50//! | Module | Description |
51//! |--------|-------------|
52//! | [`browser`] | Browser entities: [`Window`], [`Tab`], [`Element`] |
53//! | [`driver`] | Driver factory and configuration |
54//! | [`error`] | Error types and [`Result`] alias |
55//! | [`identifiers`] | Type-safe ID wrappers |
56//! | [`protocol`] | WebSocket message types (internal) |
57//! | [`transport`] | WebSocket transport layer (internal) |
58//!
59//! # Features
60//!
61//! - **Undetectable**: No `navigator.webdriver` flag, no detectable globals
62//! - **Event-driven**: DOM mutations, network events push to client
63//! - **CSP bypass**: Script execution via `browser.scripting` API
64//! - **Parallel automation**: 300+ concurrent windows supported
65
66// ============================================================================
67// Modules
68// ============================================================================
69
70/// Browser entities: Window, Tab, Element.
71///
72/// This module contains the core types for browser automation:
73///
74/// - [`Window`] - Browser window (owns Firefox process)
75/// - [`Tab`] - Browser tab with frame context
76/// - [`Element`] - DOM element reference
77pub mod browser;
78
79/// Driver factory and configuration.
80///
81/// Use [`Driver::builder()`] to create a configured driver instance.
82pub mod driver;
83
84/// Error types and result aliases.
85///
86/// All fallible operations return [`Result<T>`] which uses [`Error`].
87pub mod error;
88
89/// Type-safe identifiers for browser entities.
90///
91/// Newtype wrappers prevent mixing incompatible IDs at compile time.
92pub mod identifiers;
93
94/// WebSocket protocol message types.
95///
96/// Internal module defining command/response/event structures.
97pub mod protocol;
98
99/// WebSocket transport layer.
100///
101/// Internal module handling WebSocket server and connection management.
102pub mod transport;
103
104// ============================================================================
105// Re-exports
106// ============================================================================
107
108// Browser types
109pub use browser::{
110    BodyAction, Cookie, Element, FrameInfo, HeadersAction, InterceptedRequest,
111    InterceptedRequestBody, InterceptedRequestHeaders, InterceptedResponse,
112    InterceptedResponseBody, ProxyConfig, ProxyType, RequestAction, RequestBody, ResponseAction,
113    Tab, Window,
114};
115
116// Driver types
117pub use driver::{Driver, DriverBuilder, ExtensionSource, FirefoxOptions, Profile};
118
119// Error types
120pub use error::{Error, Result};
121
122// Identifier types
123pub use identifiers::{
124    ElementId, FrameId, InterceptId, RequestId, ScriptId, SessionId, SubscriptionId, TabId,
125};
firefox_webdriver/lib.rs

firefox_webdriver/
lib.rs
