browser_commander/
lib.rs

1//! Browser Commander - Universal Browser Automation Library
2//!
3//! A Rust library for browser automation that provides a unified API
4//! for different browser automation engines.
5//!
6//! # Features
7//!
8//! - Unified API across multiple browser engines
9//! - Built-in navigation safety handling
10//! - Element visibility and scroll management
11//! - Click, fill, and other interaction support with verification
12//! - Async/await support with Tokio
13//!
14//! # Example
15//!
16//! ```rust,no_run
17//! use browser_commander::browser::{launch_browser, LaunchOptions};
18//!
19//! #[tokio::main]
20//! async fn main() -> anyhow::Result<()> {
21//!     // Start the installed browser the way a person would, with a fresh
22//!     // temporary profile, and attach the engine to it.
23//!     let options = LaunchOptions::chromiumoxide().headless(true);
24//!     let result = launch_browser(options).await?;
25//!
26//!     // The returned `page` is an `Arc<dyn EngineAdapter>` and can be
27//!     // passed to any of the crate's navigation / interaction helpers.
28//!     let page = result.page.as_ref();
29//!     page.goto("https://example.com").await?;
30//!     println!("Current URL: {}", page.url().await?);
31//!
32//!     // Stops the browser and deletes the temporary profile.
33//!     result.close().await?;
34//!     Ok(())
35//! }
36//! ```
37//!
38//! # Modules
39//!
40//! - [`core`] - Core types and traits (constants, engine adapter, logger)
41//! - [`elements`] - Element operations (selectors, visibility, content)
42//! - [`interactions`] - User interactions (click, scroll, fill)
43//! - [`browser`] - Browser management (launcher, navigation)
44//! - [`downloads`] - Managed, persistent downloads (manager, store, sources)
45//! - [`fingerprint`] - Fingerprint parity with a hand-started browser (profiles,
46//!   presets, automation parity)
47//! - [`puppeteer`] - Typed Puppeteer API over the JavaScript CLI's bridge
48//! - [`traces`] - Recording, reading and exporting privacy-aware portable trace
49//!   bundles
50//! - [`utilities`] - General utilities (URL handling, wait operations)
51//! - [`high_level`] - High-level DRY utilities
52
53pub mod browser;
54pub mod core;
55pub mod downloads;
56pub mod elements;
57pub mod fingerprint;
58pub mod high_level;
59pub mod interactions;
60pub mod playwright;
61pub mod puppeteer;
62pub mod traces;
63pub mod utilities;
64
65pub use browser::extension_relay::{
66    attach_via_extension, write_extension_directory, ExtensionRelay, RelayError, RelayEvent,
67    RelayExtension, RelayOptions, RelaySession, RelayTab,
68};
69pub use browser::parity;
70pub use browser::webdriver::{
71    launch_webdriver, launch_webdriver_snapshot, ManagedWebDriver, WebDriverBrowser,
72    WebDriverClient, WebDriverOptions, WebDriverSnapshotResult,
73};
74pub use parity::{measure_parity, measure_session_parity, MeasureParityOptions, ParityReport};
75
76// Re-export commonly used items at crate root
77pub use browser::snapshot::{
78    launch_snapshot, snapshot_user_data_dir, SnapshotLaunchResult, SnapshotOptions, SnapshotReport,
79};
80pub use browser::{
81    build_real_browser_args, clear_browser_cookie_memory_cache, connect_browser, emulate_media,
82    launch_and_connect_real_browser, launch_browser, launch_real_browser, launch_restrictions,
83    list_browser_profiles, read_browser_cookies, resolve_restrictions, save_storage_state, Browser,
84    BrowserCookie, BrowserCookieReadOptions, BrowserProcess, BrowserProfile, BrowserProfileOptions,
85    ChromiumoxidePage, ColorScheme, ConnectOptions, EmulateMediaOptions, LaunchMode, LaunchOptions,
86    LaunchRestriction, LaunchResult, NodeBridgePage, PlaywrightConnect, PlaywrightDriverPage,
87    PlaywrightLaunch, RealBrowserLaunchResult, RealBrowserOptions, StorageEntry, StorageOrigin,
88    StorageState, StorageStateInput, LAUNCH_MODES, SUPPORTED_COOKIE_BROWSERS,
89};
90pub use core::{
91    DialogEvent, DialogManager, DialogType, EngineAdapter, EngineError, EngineType, Logger,
92    LoggerOptions, PdfOptions, Timing, CHROME_ARGS, TIMING,
93};
94pub use downloads::{
95    attach_downloads, normalize_download_options, supported_engine, CaptureOptions,
96    DownloadArtifact, DownloadConflict, DownloadError, DownloadEvent, DownloadManager,
97    DownloadNamer, DownloadNaming, DownloadOptions, DownloadSetting, DownloadValidator,
98    DEFAULT_CAPTURE_TIMEOUT,
99};
100// `fingerprint::ColorScheme` is the CSS preference a page reads, while
101// `browser::ColorScheme` is the one `emulate_media` writes, so the fingerprint
102// one is re-exported under a qualified name instead of shadowing it.
103pub use fingerprint::{
104    apply_automation_parity_args, apply_fingerprint, build_cdp_emulation_commands,
105    build_fingerprint_init_script, build_init_script_config, create_default_fingerprint_preset,
106    create_fingerprint_preset, derive_user_agent_data, detect_automation_controlled_triggers,
107    disables_automation_controlled, find_fingerprint_limitation, fingerprint_field_mechanism,
108    parity_ignored_default_args, relevant_fingerprint_limitations, resolve_fingerprint_profile,
109    AppliedFingerprint, ApplyOptions, AutomationTrigger, BrandVersion, CdpCommand, CdpTransport,
110    ColorScheme as FingerprintColorScheme, DetectedTrigger, FieldMechanism, FingerprintLimitation,
111    FingerprintProfile, ForcedColors, GeolocationProfile, InitScriptOptions, LimitationContext,
112    LimitationEvidence, LimitationSeverity, ReducedMotion, ScreenProfile, UserAgentData,
113    ViewportProfile, WebglProfile, AUTOMATION_CONTROLLED_OFF_ARG, AUTOMATION_CONTROLLED_TRIGGERS,
114    DEFAULT_CHROME_VERSION, FINGERPRINT_FIELD_MECHANISMS, FINGERPRINT_LIMITATIONS,
115    FINGERPRINT_LIMITATIONS_SOURCE, FINGERPRINT_PAYLOAD_SOURCE, FINGERPRINT_PRESET_NAMES,
116    PLAYWRIGHT_HEADLESS_POINTER_ARG, PLAYWRIGHT_SOFTWARE_WEBGL_ARG,
117};
118
119// Reading trace bundles needs no engine, so the reader is available at the
120// crate root like any other pure helper; recording sits beside it.
121pub use traces::{
122    diff_control_state, parse_ndjson, read_trace, ControlChange, ControlChangeKind, ParsedNdjson,
123    Trace, TraceCheckpoint, TraceCheckpointReason, TraceError, TraceEvent, TraceFiles,
124    TraceLiveState, TraceManifest, TraceMode, TraceMutationKind, TraceOutcome, TraceReplaySupport,
125    TRACE_EVENT_SOURCES, TRACE_FORMAT, TRACE_SCHEMA_VERSION,
126};
127pub use traces::{
128    start_trace, trace_links, write_trace_links, write_trace_viewer, AdapterTracePage,
129    TraceCheckpointOptions, TraceLinksOptions, TraceOptions, TraceRecordError, TraceRecorder,
130    TraceResult, TraceStopOptions,
131};
132
133/// Prelude module for convenient imports.
134///
135/// Import everything commonly needed with:
136/// ```rust
137/// use browser_commander::prelude::*;
138/// ```
139pub mod prelude {
140    pub use crate::browser::{
141        clear_browser_cookie_memory_cache, connect_browser, emulate_media, goto,
142        launch_and_connect_real_browser, launch_browser, launch_real_browser,
143        list_browser_profiles, read_browser_cookies, verify_navigation, wait_for_navigation,
144        wait_for_url_stabilization, Browser, BrowserCookie, BrowserCookieReadOptions,
145        BrowserProcess, BrowserProfile, BrowserProfileOptions, ColorScheme, ConnectOptions,
146        EmulateMediaOptions, LaunchMode, LaunchOptions, LaunchResult, NavigationOptions,
147        NavigationResult, RealBrowserLaunchResult, RealBrowserOptions, WaitUntil,
148    };
149    pub use crate::core::{
150        is_navigation_error, is_timeout_error, DialogEvent, DialogManager, DialogType,
151        EngineAdapter, EngineError, EngineType, Logger, LoggerOptions, PdfOptions, Timing,
152        CHROME_ARGS, TIMING,
153    };
154    pub use crate::downloads::{
155        attach_downloads, normalize_download_options, CaptureOptions, DownloadArtifact,
156        DownloadConflict, DownloadError, DownloadEvent, DownloadManager, DownloadOptions,
157        DownloadSetting,
158    };
159    pub use crate::elements::{
160        count, get_attribute, input_value, is_enabled, is_visible, normalize_selector,
161        text_content, ParsedSelector,
162    };
163    pub use crate::fingerprint::{
164        apply_automation_parity_args, apply_fingerprint, build_cdp_emulation_commands,
165        build_fingerprint_init_script, build_init_script_config, create_default_fingerprint_preset,
166        create_fingerprint_preset, derive_user_agent_data, detect_automation_controlled_triggers,
167        disables_automation_controlled, find_fingerprint_limitation, fingerprint_field_mechanism,
168        parity_ignored_default_args, relevant_fingerprint_limitations, resolve_fingerprint_profile,
169        AppliedFingerprint, ApplyOptions, AutomationTrigger, BrandVersion, CdpCommand,
170        CdpTransport, ColorScheme as FingerprintColorScheme, DetectedTrigger, FieldMechanism,
171        FingerprintLimitation, FingerprintProfile, ForcedColors, GeolocationProfile,
172        InitScriptOptions, LimitationContext, LimitationEvidence, LimitationSeverity,
173        ReducedMotion, ScreenProfile, UserAgentData, ViewportProfile, WebglProfile,
174        AUTOMATION_CONTROLLED_OFF_ARG, AUTOMATION_CONTROLLED_TRIGGERS, DEFAULT_CHROME_VERSION,
175        FINGERPRINT_FIELD_MECHANISMS, FINGERPRINT_LIMITATIONS, FINGERPRINT_LIMITATIONS_SOURCE,
176        FINGERPRINT_PAYLOAD_SOURCE, FINGERPRINT_PRESET_NAMES, PLAYWRIGHT_HEADLESS_POINTER_ARG,
177        PLAYWRIGHT_SOFTWARE_WEBGL_ARG,
178    };
179    pub use crate::high_level::{
180        check_and_clear_flag, find_toggle_button, install_click_listener, wait_for_url_condition,
181    };
182    pub use crate::interactions::{
183        click_button, click_element, fill_text_area, key_down, key_up, perform_fill, press_key,
184        scroll_into_view, scroll_into_view_if_needed, type_text, ActivationOptions,
185        ClickActionability, ClickActivation, ClickDispatchError, ClickEffect, ClickOptions,
186        ClickResult, ClickScroll, ClickStatus, Evidence, FillOptions, FillResult, ScrollBehavior,
187        ScrollOptions, ScrollResult,
188    };
189    pub use crate::traces::{
190        diff_control_state, parse_ndjson, read_trace, start_trace, write_trace_viewer,
191        AdapterTracePage, ControlChange, ControlChangeKind, Trace, TraceCheckpoint,
192        TraceCheckpointReason, TraceError, TraceEvent, TraceFiles, TraceLiveState, TraceManifest,
193        TraceMode, TraceMutationKind, TraceOptions, TraceOutcome, TraceRecorder,
194        TraceReplaySupport, TRACE_SCHEMA_VERSION,
195    };
196    pub use crate::utilities::{
197        evaluate, get_domain, get_url, parse_url, safe_evaluate, same_origin, unfocus_address_bar,
198        wait, wait_with_cancel, WaitResult,
199    };
200}
browser_commander/lib.rs

browser_commander/
lib.rs
