firefox-webdriver 0.1.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
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181

# Firefox-WebDriver

High-performance Firefox WebDriver in Rust

## Features

| Feature      | Description                                          |
| ------------ | ---------------------------------------------------- |
| Undetectable | No `navigator.webdriver` flag, no detectable globals |
| Event-driven | DOM mutations and network events push to client      |
| CSP bypass   | Script execution via `browser.scripting` API         |
| Parallel     | 300+ concurrent Windows supported                    |

## Architecture

```
Rust Application
    │
    ├── Driver ──► ConnectionPool (single WebSocket port)
    │                   │
    │                   ├── Window 1 ──► Tab ──► Element
    │                   ├── Window 2 ──► Tab ──► Element
    │                   └── Window N ──► Tab ──► Element
    │
    └── All windows share one WebSocket server
            │
            ▼
Firefox + Extension (multiple instances)
    │
    ├── Background Script (command router)
    └── Content Script (DOM access)
```

Each Window owns:

- One Firefox process
- Reference to shared ConnectionPool
- One profile directory

## Requirements

- Rust 1.92+
- Firefox 148+
- tokio 1.48+

## Installation

```toml
[dependencies]
firefox-webdriver = "0.1.1"
tokio = { version = "1.48", features = ["full"] }
```

## Commands

### Build

| Command      | Description            |
| ------------ | ---------------------- |
| `make build` | Build release          |
| `make check` | Check without building |
| `make doc`   | Generate docs          |

### Test

| Command            | Description                           |
| ------------------ | ------------------------------------- |
| `make test`        | Run tests                             |
| `make run-example` | Run example (EXAMPLE=01_basic_launch) |

### Quality

| Command       | Description |
| ------------- | ----------- |
| `make format` | Format code |
| `make lint`   | Run clippy  |

### Clean

| Command      | Description     |
| ------------ | --------------- |
| `make clean` | Clean artifacts |

## Usage

```rust
use firefox_webdriver::{Driver, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let driver = Driver::builder()
        .binary("/usr/bin/firefox")
        .extension("./extension")
        .build()
        .await?;

    let window = driver.window().headless().spawn().await?;
    let tab = window.tab();

    // Navigate to example.com
    tab.goto("https://example.com").await?;
    let title = tab.get_title().await?;
    println!("Title: {}", title);

    // Find the main heading
    let heading = tab.find_element("h1").await?;
    let text = heading.get_text().await?;
    println!("Heading: {}", text);

    // Find the link on the page
    let link = tab.find_element("a").await?;
    let href = link.get_attribute("href").await?;
    println!("Link href: {:?}", href);

    window.close().await?;
    Ok(())
}
```

## Examples

| Example                      | Description                        |
| ---------------------------- | ---------------------------------- |
| `001_basic_launch.rs`        | Driver setup, window, profile      |
| `002_navigation.rs`          | Navigate, back, forward, reload    |
| `003_script_execution.rs`    | Sync/async JavaScript execution    |
| `004_element_query.rs`       | Find elements, properties          |
| `005_element_interaction.rs` | Click, type, focus, blur           |
| `006_storage.rs`             | Cookies, localStorage              |
| `007_frame_switching.rs`     | iframe navigation                  |
| `008_element_observer.rs`    | MutationObserver, wait_for_element |
| `009_proxy.rs`               | HTTP/SOCKS5 proxy configuration    |
| `010_network_intercept.rs`   | Block rules, request interception  |
| `011_canvas_fingerprint.rs`  | Canvas randomization test          |
| `012_multi_window.rs`        | Multi-window stress test           |

```bash
cargo run --example 001_basic_launch
cargo run --example 001_basic_launch -- --no-wait  # Auto-close
cargo run --example 001_basic_launch -- --debug    # Debug logging
```

## Benchmarks

Performance benchmarks for multi-window operations.

### Run Benchmarks

```bash
# Run benchmark suite (outputs CSV)
cargo run --release --example bench_runner

# Generate plots (requires matplotlib)
pip install matplotlib
python3 benches/plot_results.py
```

### Results

Benchmarks run with varying window counts (50, 100) and durations (15s, 30s, 60s, 120s).

#### Window Spawn Time

![Window Spawn Benchmark](docs/images/benchmark_spawn.png)

#### Sustained Operations

![Operations Benchmark](docs/images/benchmark_ops.png)

## Documentation

| Document                                   | Description            |
| ------------------------------------------ | ---------------------- |
| [Getting Started](docs/getting-started.md) | Quick start guide      |
| [API Reference](docs/api/)                 | Type and method docs   |
| [Guides](docs/guides/)                     | How-to guides          |
| [Architecture](ARCHITECTURE.md)            | Protocol specification |

## License

Apache-2.0 - see [LICENSE](LICENSE)