firefox-webdriver 0.2.1

High-performance Firefox WebDriver in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

//! Firefox WebDriver - Undetectable browser automation library.
//!
//! This library provides a high-level API for automating Firefox browser
//! using a custom WebExtension-based architecture.
//!
//! # Architecture
//!
//! The driver follows a client-server model:
//!
//! - **Local End (Rust)**: Sends commands, receives events via WebSocket
//! - **Remote End (Extension)**: Executes commands in Firefox, emits events
//!
//! Key design principles:
//!
//! - [`Driver`] owns a shared [`ConnectionPool`](transport::ConnectionPool) (single WebSocket port)
//! - Each [`Window`] owns: Firefox process + profile, references shared pool
//! - Protocol uses `module.methodName` format (BiDi-inspired)
//! - Elements stored by reference in content script `Map` (undetectable)
//! - Event-driven architecture (no polling)
//!
//! # Quick Start
//!
//! ```no_run
//! use firefox_webdriver::{Driver, Result};
//!
//! #[tokio::main]
//! async fn main() -> Result<()> {
//!     // Build driver with Firefox binary and extension paths
//!     let driver = Driver::builder()
//!         .binary("/path/to/firefox")
//!         .extension("/path/to/extension")
//!         .build()
//!         .await?;
//!
//!     // Spawn a headless browser window
//!     let window = driver.window().headless().spawn().await?;
//!     let tab = window.tab();
//!
//!     // Navigate and interact
//!     tab.goto("https://example.com").await?;
//!     let title = tab.get_title().await?;
//!     println!("Page title: {}", title);
//!
//!     Ok(())
//! }
//! ```
//!
//! # Modules
//!
//! | Module | Description |
//! |--------|-------------|
//! | [`browser`] | Browser entities: [`Window`], [`Tab`], [`Element`] |
//! | [`driver`] | Driver factory and configuration |
//! | [`error`] | Error types and [`Result`] alias |
//! | [`identifiers`] | Type-safe ID wrappers |
//! | [`protocol`] | WebSocket message types (internal) |
//! | [`transport`] | WebSocket transport layer (internal) |
//!
//! # Features
//!
//! - **Undetectable**: No `navigator.webdriver` flag, no detectable globals
//! - **Event-driven**: DOM mutations, network events push to client
//! - **CSP bypass**: Script execution via `browser.scripting` API
//! - **Parallel automation**: 300+ concurrent windows supported

// ============================================================================
// Modules
// ============================================================================

/// Browser entities: Window, Tab, Element.
///
/// This module contains the core types for browser automation:
///
/// - [`Window`] - Browser window (owns Firefox process)
/// - [`Tab`] - Browser tab with frame context
/// - [`Element`] - DOM element reference
pub mod browser;

/// Driver factory and configuration.
///
/// Use [`Driver::builder()`] to create a configured driver instance.
pub mod driver;

/// Error types and result aliases.
///
/// All fallible operations return [`Result<T>`] which uses [`Error`].
pub mod error;

/// Type-safe identifiers for browser entities.
///
/// Newtype wrappers prevent mixing incompatible IDs at compile time.
pub mod identifiers;

/// WebSocket protocol message types.
///
/// Internal module defining command/response/event structures.
pub mod protocol;

/// WebSocket transport layer.
///
/// Internal module handling WebSocket server and connection management.
pub mod transport;

// ============================================================================
// Re-exports
// ============================================================================

// Browser types
pub use browser::{
    BodyAction, By, Cookie, Element, FrameInfo, HeadersAction, ImageFormat, InterceptedRequest,
    InterceptedRequestBody, InterceptedRequestHeaders, InterceptedResponse,
    InterceptedResponseBody, Key, ProxyConfig, ProxyType, RequestAction, RequestBody,
    ResponseBodyData, ScreenshotBuilder, Tab, Window,
};

// Driver types
pub use driver::{Driver, DriverBuilder, ExtensionSource, FirefoxOptions, Profile};

// Error types
pub use error::{Error, Result};

// Identifier types
pub use identifiers::{
    ElementId, FrameId, InterceptId, RequestId, ScriptId, SessionId, SubscriptionId, TabId,
};