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//! - [`downloads`] - Managed, persistent downloads (manager, store, sources)
42//! - [`fingerprint`] - Fingerprint parity with a hand-started browser (profiles,
43//!   presets, automation parity)
44//! - [`traces`] - Reading privacy-aware portable trace bundles
45//! - [`utilities`] - General utilities (URL handling, wait operations)
46//! - [`high_level`] - High-level DRY utilities
47
48pub mod browser;
49pub mod core;
50pub mod downloads;
51pub mod elements;
52pub mod fingerprint;
53pub mod high_level;
54pub mod interactions;
55pub mod traces;
56pub mod utilities;
57
58// Re-export commonly used items at crate root
59pub use browser::{
60    build_real_browser_args, clear_browser_cookie_memory_cache, connect_browser, emulate_media,
61    launch_and_connect_real_browser, launch_browser, launch_real_browser, list_browser_profiles,
62    read_browser_cookies, Browser, BrowserCookie, BrowserCookieReadOptions, BrowserProcess,
63    BrowserProfile, BrowserProfileOptions, ChromiumoxidePage, ColorScheme, ConnectOptions,
64    EmulateMediaOptions, LaunchOptions, LaunchResult, NodeBridgePage, RealBrowserLaunchResult,
65    RealBrowserOptions, SUPPORTED_COOKIE_BROWSERS,
66};
67pub use core::{
68    DialogEvent, DialogManager, DialogType, EngineAdapter, EngineError, EngineType, Logger,
69    LoggerOptions, PdfOptions, Timing, CHROME_ARGS, TIMING,
70};
71pub use downloads::{
72    attach_downloads, normalize_download_options, supported_engine, CaptureOptions,
73    DownloadArtifact, DownloadConflict, DownloadError, DownloadEvent, DownloadManager,
74    DownloadNamer, DownloadNaming, DownloadOptions, DownloadSetting, DownloadValidator,
75    DEFAULT_CAPTURE_TIMEOUT,
76};
77// `fingerprint::ColorScheme` is the CSS preference a page reads, while
78// `browser::ColorScheme` is the one `emulate_media` writes, so the fingerprint
79// one is re-exported under a qualified name instead of shadowing it.
80pub use fingerprint::{
81    apply_automation_parity_args, apply_fingerprint, build_cdp_emulation_commands,
82    build_fingerprint_init_script, build_init_script_config, create_default_fingerprint_preset,
83    create_fingerprint_preset, derive_user_agent_data, detect_automation_controlled_triggers,
84    disables_automation_controlled, find_fingerprint_limitation, fingerprint_field_mechanism,
85    parity_ignored_default_args, relevant_fingerprint_limitations, resolve_fingerprint_profile,
86    AppliedFingerprint, ApplyOptions, AutomationTrigger, BrandVersion, CdpCommand, CdpTransport,
87    ColorScheme as FingerprintColorScheme, DetectedTrigger, FieldMechanism, FingerprintLimitation,
88    FingerprintProfile, ForcedColors, GeolocationProfile, InitScriptOptions, LimitationContext,
89    LimitationEvidence, LimitationSeverity, ReducedMotion, ScreenProfile, UserAgentData,
90    ViewportProfile, WebglProfile, AUTOMATION_CONTROLLED_OFF_ARG, AUTOMATION_CONTROLLED_TRIGGERS,
91    DEFAULT_CHROME_VERSION, FINGERPRINT_FIELD_MECHANISMS, FINGERPRINT_LIMITATIONS,
92    FINGERPRINT_LIMITATIONS_SOURCE, FINGERPRINT_PAYLOAD_SOURCE, FINGERPRINT_PRESET_NAMES,
93    PLAYWRIGHT_HEADLESS_POINTER_ARG, PLAYWRIGHT_SOFTWARE_WEBGL_ARG,
94};
95
96// Reading trace bundles needs no engine, so the reader is available at the
97// crate root like any other pure helper.
98pub use traces::{
99    diff_control_state, parse_ndjson, read_trace, ControlChange, ControlChangeKind, ParsedNdjson,
100    Trace, TraceCheckpoint, TraceError, TraceEvent, TraceFiles, TraceManifest, TraceMode,
101    TraceOutcome, TRACE_EVENT_SOURCES, TRACE_FORMAT, TRACE_SCHEMA_VERSION,
102};
103
104/// Prelude module for convenient imports.
105///
106/// Import everything commonly needed with:
107/// ```rust
108/// use browser_commander::prelude::*;
109/// ```
110pub mod prelude {
111    pub use crate::browser::{
112        clear_browser_cookie_memory_cache, connect_browser, emulate_media, goto,
113        launch_and_connect_real_browser, launch_browser, launch_real_browser,
114        list_browser_profiles, read_browser_cookies, verify_navigation, wait_for_navigation,
115        wait_for_url_stabilization, Browser, BrowserCookie, BrowserCookieReadOptions,
116        BrowserProcess, BrowserProfile, BrowserProfileOptions, ColorScheme, ConnectOptions,
117        EmulateMediaOptions, LaunchOptions, LaunchResult, NavigationOptions, NavigationResult,
118        RealBrowserLaunchResult, RealBrowserOptions, WaitUntil,
119    };
120    pub use crate::core::{
121        is_navigation_error, is_timeout_error, DialogEvent, DialogManager, DialogType,
122        EngineAdapter, EngineError, EngineType, Logger, LoggerOptions, PdfOptions, Timing,
123        CHROME_ARGS, TIMING,
124    };
125    pub use crate::downloads::{
126        attach_downloads, normalize_download_options, CaptureOptions, DownloadArtifact,
127        DownloadConflict, DownloadError, DownloadEvent, DownloadManager, DownloadOptions,
128        DownloadSetting,
129    };
130    pub use crate::elements::{
131        count, get_attribute, input_value, is_enabled, is_visible, normalize_selector,
132        text_content, ParsedSelector,
133    };
134    pub use crate::fingerprint::{
135        apply_automation_parity_args, apply_fingerprint, build_cdp_emulation_commands,
136        build_fingerprint_init_script, build_init_script_config, create_default_fingerprint_preset,
137        create_fingerprint_preset, derive_user_agent_data, detect_automation_controlled_triggers,
138        disables_automation_controlled, find_fingerprint_limitation, fingerprint_field_mechanism,
139        parity_ignored_default_args, relevant_fingerprint_limitations, resolve_fingerprint_profile,
140        AppliedFingerprint, ApplyOptions, AutomationTrigger, BrandVersion, CdpCommand,
141        CdpTransport, ColorScheme as FingerprintColorScheme, DetectedTrigger, FieldMechanism,
142        FingerprintLimitation, FingerprintProfile, ForcedColors, GeolocationProfile,
143        InitScriptOptions, LimitationContext, LimitationEvidence, LimitationSeverity,
144        ReducedMotion, ScreenProfile, UserAgentData, ViewportProfile, WebglProfile,
145        AUTOMATION_CONTROLLED_OFF_ARG, AUTOMATION_CONTROLLED_TRIGGERS, DEFAULT_CHROME_VERSION,
146        FINGERPRINT_FIELD_MECHANISMS, FINGERPRINT_LIMITATIONS, FINGERPRINT_LIMITATIONS_SOURCE,
147        FINGERPRINT_PAYLOAD_SOURCE, FINGERPRINT_PRESET_NAMES, PLAYWRIGHT_HEADLESS_POINTER_ARG,
148        PLAYWRIGHT_SOFTWARE_WEBGL_ARG,
149    };
150    pub use crate::high_level::{
151        check_and_clear_flag, find_toggle_button, install_click_listener, wait_for_url_condition,
152    };
153    pub use crate::interactions::{
154        click_button, click_element, fill_text_area, key_down, key_up, perform_fill, press_key,
155        scroll_into_view, scroll_into_view_if_needed, type_text, ActivationOptions,
156        ClickActionability, ClickActivation, ClickDispatchError, ClickEffect, ClickOptions,
157        ClickResult, ClickScroll, ClickStatus, Evidence, FillOptions, FillResult, ScrollBehavior,
158        ScrollOptions, ScrollResult,
159    };
160    pub use crate::traces::{
161        diff_control_state, parse_ndjson, read_trace, ControlChange, ControlChangeKind, Trace,
162        TraceCheckpoint, TraceError, TraceEvent, TraceFiles, TraceManifest, TraceMode,
163        TraceOutcome, TRACE_SCHEMA_VERSION,
164    };
165    pub use crate::utilities::{
166        evaluate, get_domain, get_url, parse_url, safe_evaluate, same_origin, unfocus_address_bar,
167        wait, wait_with_cancel, WaitResult,
168    };
169}
browser_commander/lib.rs

browser_commander/
lib.rs
