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

browser_commander/
lib.rs
