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, TraceCheckpointReason, TraceError, TraceEvent, TraceFiles,
101    TraceLiveState, TraceManifest, TraceMode, TraceMutationKind, TraceOutcome, TraceReplaySupport,
102    TRACE_EVENT_SOURCES, TRACE_FORMAT, TRACE_SCHEMA_VERSION,
103};
104
105/// Prelude module for convenient imports.
106///
107/// Import everything commonly needed with:
108/// ```rust
109/// use browser_commander::prelude::*;
110/// ```
111pub mod prelude {
112    pub use crate::browser::{
113        clear_browser_cookie_memory_cache, connect_browser, emulate_media, goto,
114        launch_and_connect_real_browser, launch_browser, launch_real_browser,
115        list_browser_profiles, read_browser_cookies, verify_navigation, wait_for_navigation,
116        wait_for_url_stabilization, Browser, BrowserCookie, BrowserCookieReadOptions,
117        BrowserProcess, BrowserProfile, BrowserProfileOptions, ColorScheme, ConnectOptions,
118        EmulateMediaOptions, LaunchOptions, LaunchResult, NavigationOptions, NavigationResult,
119        RealBrowserLaunchResult, RealBrowserOptions, WaitUntil,
120    };
121    pub use crate::core::{
122        is_navigation_error, is_timeout_error, DialogEvent, DialogManager, DialogType,
123        EngineAdapter, EngineError, EngineType, Logger, LoggerOptions, PdfOptions, Timing,
124        CHROME_ARGS, TIMING,
125    };
126    pub use crate::downloads::{
127        attach_downloads, normalize_download_options, CaptureOptions, DownloadArtifact,
128        DownloadConflict, DownloadError, DownloadEvent, DownloadManager, DownloadOptions,
129        DownloadSetting,
130    };
131    pub use crate::elements::{
132        count, get_attribute, input_value, is_enabled, is_visible, normalize_selector,
133        text_content, ParsedSelector,
134    };
135    pub use crate::fingerprint::{
136        apply_automation_parity_args, apply_fingerprint, build_cdp_emulation_commands,
137        build_fingerprint_init_script, build_init_script_config, create_default_fingerprint_preset,
138        create_fingerprint_preset, derive_user_agent_data, detect_automation_controlled_triggers,
139        disables_automation_controlled, find_fingerprint_limitation, fingerprint_field_mechanism,
140        parity_ignored_default_args, relevant_fingerprint_limitations, resolve_fingerprint_profile,
141        AppliedFingerprint, ApplyOptions, AutomationTrigger, BrandVersion, CdpCommand,
142        CdpTransport, ColorScheme as FingerprintColorScheme, DetectedTrigger, FieldMechanism,
143        FingerprintLimitation, FingerprintProfile, ForcedColors, GeolocationProfile,
144        InitScriptOptions, LimitationContext, LimitationEvidence, LimitationSeverity,
145        ReducedMotion, ScreenProfile, UserAgentData, ViewportProfile, WebglProfile,
146        AUTOMATION_CONTROLLED_OFF_ARG, AUTOMATION_CONTROLLED_TRIGGERS, DEFAULT_CHROME_VERSION,
147        FINGERPRINT_FIELD_MECHANISMS, FINGERPRINT_LIMITATIONS, FINGERPRINT_LIMITATIONS_SOURCE,
148        FINGERPRINT_PAYLOAD_SOURCE, FINGERPRINT_PRESET_NAMES, PLAYWRIGHT_HEADLESS_POINTER_ARG,
149        PLAYWRIGHT_SOFTWARE_WEBGL_ARG,
150    };
151    pub use crate::high_level::{
152        check_and_clear_flag, find_toggle_button, install_click_listener, wait_for_url_condition,
153    };
154    pub use crate::interactions::{
155        click_button, click_element, fill_text_area, key_down, key_up, perform_fill, press_key,
156        scroll_into_view, scroll_into_view_if_needed, type_text, ActivationOptions,
157        ClickActionability, ClickActivation, ClickDispatchError, ClickEffect, ClickOptions,
158        ClickResult, ClickScroll, ClickStatus, Evidence, FillOptions, FillResult, ScrollBehavior,
159        ScrollOptions, ScrollResult,
160    };
161    pub use crate::traces::{
162        diff_control_state, parse_ndjson, read_trace, ControlChange, ControlChangeKind, Trace,
163        TraceCheckpoint, TraceCheckpointReason, TraceError, TraceEvent, TraceFiles, TraceLiveState,
164        TraceManifest, TraceMode, TraceMutationKind, TraceOutcome, TraceReplaySupport,
165        TRACE_SCHEMA_VERSION,
166    };
167    pub use crate::utilities::{
168        evaluate, get_domain, get_url, parse_url, safe_evaluate, same_origin, unfocus_address_bar,
169        wait, wait_with_cancel, WaitResult,
170    };
171}
browser_commander/lib.rs

browser_commander/
lib.rs
