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//!     // Launch a browser
22//!     let options = LaunchOptions::chromiumoxide().headless(true);
23//!     let result = launch_browser(options).await?;
24//!
25//!     // The returned `page` is an `Arc<dyn EngineAdapter>` and can be
26//!     // passed to any of the crate's navigation / interaction helpers.
27//!     let page = result.page.as_ref();
28//!     page.goto("https://example.com").await?;
29//!     println!("Current URL: {}", page.url().await?);
30//!
31//!     Ok(())
32//! }
33//! ```
34//!
35//! # Modules
36//!
37//! - [`core`] - Core types and traits (constants, engine adapter, logger)
38//! - [`elements`] - Element operations (selectors, visibility, content)
39//! - [`interactions`] - User interactions (click, scroll, fill)
40//! - [`browser`] - Browser management (launcher, navigation)
41//! - [`fingerprint`] - Fingerprint parity with a hand-started browser (profiles,
42//!   presets, automation parity)
43//! - [`utilities`] - General utilities (URL handling, wait operations)
44//! - [`high_level`] - High-level DRY utilities
45
46pub mod browser;
47pub mod core;
48pub mod elements;
49pub mod fingerprint;
50pub mod high_level;
51pub mod interactions;
52pub mod utilities;
53
54// Re-export commonly used items at crate root
55pub use browser::{
56    build_real_browser_args, clear_browser_cookie_memory_cache, connect_browser, emulate_media,
57    launch_and_connect_real_browser, launch_browser, launch_real_browser, list_browser_profiles,
58    read_browser_cookies, Browser, BrowserCookie, BrowserCookieReadOptions, BrowserProcess,
59    BrowserProfile, BrowserProfileOptions, ChromiumoxidePage, ColorScheme, ConnectOptions,
60    EmulateMediaOptions, LaunchOptions, LaunchResult, NodeBridgePage, RealBrowserLaunchResult,
61    RealBrowserOptions, SUPPORTED_COOKIE_BROWSERS,
62};
63pub use core::{
64    DialogEvent, DialogManager, DialogType, EngineAdapter, EngineError, EngineType, Logger,
65    LoggerOptions, PdfOptions, Timing, CHROME_ARGS, TIMING,
66};
67// `fingerprint::ColorScheme` is the CSS preference a page reads, while
68// `browser::ColorScheme` is the one `emulate_media` writes, so the fingerprint
69// one is re-exported under a qualified name instead of shadowing it.
70pub use fingerprint::{
71    apply_automation_parity_args, apply_fingerprint, build_cdp_emulation_commands,
72    build_fingerprint_init_script, build_init_script_config, create_default_fingerprint_preset,
73    create_fingerprint_preset, derive_user_agent_data, detect_automation_controlled_triggers,
74    disables_automation_controlled, find_fingerprint_limitation, fingerprint_field_mechanism,
75    parity_ignored_default_args, relevant_fingerprint_limitations, resolve_fingerprint_profile,
76    AppliedFingerprint, ApplyOptions, AutomationTrigger, BrandVersion, CdpCommand, CdpTransport,
77    ColorScheme as FingerprintColorScheme, DetectedTrigger, FieldMechanism, FingerprintLimitation,
78    FingerprintProfile, ForcedColors, GeolocationProfile, InitScriptOptions, LimitationContext,
79    LimitationEvidence, LimitationSeverity, ReducedMotion, ScreenProfile, UserAgentData,
80    ViewportProfile, WebglProfile, AUTOMATION_CONTROLLED_OFF_ARG, AUTOMATION_CONTROLLED_TRIGGERS,
81    DEFAULT_CHROME_VERSION, FINGERPRINT_FIELD_MECHANISMS, FINGERPRINT_LIMITATIONS,
82    FINGERPRINT_LIMITATIONS_SOURCE, FINGERPRINT_PAYLOAD_SOURCE, FINGERPRINT_PRESET_NAMES,
83    PLAYWRIGHT_HEADLESS_POINTER_ARG, PLAYWRIGHT_SOFTWARE_WEBGL_ARG,
84};
85
86/// Prelude module for convenient imports.
87///
88/// Import everything commonly needed with:
89/// ```rust
90/// use browser_commander::prelude::*;
91/// ```
92pub mod prelude {
93    pub use crate::browser::{
94        clear_browser_cookie_memory_cache, connect_browser, emulate_media, goto,
95        launch_and_connect_real_browser, launch_browser, launch_real_browser,
96        list_browser_profiles, read_browser_cookies, verify_navigation, wait_for_navigation,
97        wait_for_url_stabilization, Browser, BrowserCookie, BrowserCookieReadOptions,
98        BrowserProcess, BrowserProfile, BrowserProfileOptions, ColorScheme, ConnectOptions,
99        EmulateMediaOptions, LaunchOptions, LaunchResult, NavigationOptions, NavigationResult,
100        RealBrowserLaunchResult, RealBrowserOptions, WaitUntil,
101    };
102    pub use crate::core::{
103        is_navigation_error, is_timeout_error, DialogEvent, DialogManager, DialogType,
104        EngineAdapter, EngineError, EngineType, Logger, LoggerOptions, PdfOptions, Timing,
105        CHROME_ARGS, TIMING,
106    };
107    pub use crate::elements::{
108        count, get_attribute, input_value, is_enabled, is_visible, normalize_selector,
109        text_content, ParsedSelector,
110    };
111    pub use crate::fingerprint::{
112        apply_automation_parity_args, apply_fingerprint, build_cdp_emulation_commands,
113        build_fingerprint_init_script, build_init_script_config, create_default_fingerprint_preset,
114        create_fingerprint_preset, derive_user_agent_data, detect_automation_controlled_triggers,
115        disables_automation_controlled, find_fingerprint_limitation, fingerprint_field_mechanism,
116        parity_ignored_default_args, relevant_fingerprint_limitations, resolve_fingerprint_profile,
117        AppliedFingerprint, ApplyOptions, AutomationTrigger, BrandVersion, CdpCommand,
118        CdpTransport, ColorScheme as FingerprintColorScheme, DetectedTrigger, FieldMechanism,
119        FingerprintLimitation, FingerprintProfile, ForcedColors, GeolocationProfile,
120        InitScriptOptions, LimitationContext, LimitationEvidence, LimitationSeverity,
121        ReducedMotion, ScreenProfile, UserAgentData, ViewportProfile, WebglProfile,
122        AUTOMATION_CONTROLLED_OFF_ARG, AUTOMATION_CONTROLLED_TRIGGERS, DEFAULT_CHROME_VERSION,
123        FINGERPRINT_FIELD_MECHANISMS, FINGERPRINT_LIMITATIONS, FINGERPRINT_LIMITATIONS_SOURCE,
124        FINGERPRINT_PAYLOAD_SOURCE, FINGERPRINT_PRESET_NAMES, PLAYWRIGHT_HEADLESS_POINTER_ARG,
125        PLAYWRIGHT_SOFTWARE_WEBGL_ARG,
126    };
127    pub use crate::high_level::{
128        check_and_clear_flag, find_toggle_button, install_click_listener, wait_for_url_condition,
129    };
130    pub use crate::interactions::{
131        click_button, click_element, fill_text_area, key_down, key_up, perform_fill, press_key,
132        scroll_into_view, scroll_into_view_if_needed, type_text, ClickOptions, ClickResult,
133        FillOptions, FillResult, ScrollBehavior, ScrollOptions, ScrollResult,
134    };
135    pub use crate::utilities::{
136        evaluate, get_domain, get_url, parse_url, safe_evaluate, same_origin, unfocus_address_bar,
137        wait, wait_with_cancel, WaitResult,
138    };
139}
browser_commander/lib.rs

browser_commander/
lib.rs
