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    browser_family, browser_for_identifier, browser_ids, browser_sources, build_real_browser_args,
82    clear_browser_cookie_memory_cache, connect_browser, default_browser_identifiers,
83    default_run_command, emulate_media, find_browser_source, is_default_browser_keyword,
84    is_single_profile_browser, launch_and_connect_real_browser, launch_browser,
85    launch_real_browser, launch_restrictions, list_browser_profiles, list_cookie_sources,
86    normalize_browser_id, parse_mac_launch_services_handler, parse_windows_prog_id,
87    read_browser_cookies, resolve_browser_roots, resolve_default_browser, resolve_import_source,
88    resolve_restrictions, resolve_source_browser, safe_storage_identity, save_storage_state,
89    Browser, BrowserCookie, BrowserCookieReadOptions, BrowserProcess, BrowserProfile,
90    BrowserProfileOptions, BrowserSource, ChromiumoxidePage, ColorScheme, ConnectOptions,
91    CookieSourceListing, EmulateMediaOptions, Environment, ImportSource, LaunchMode, LaunchOptions,
92    LaunchRestriction, LaunchResult, NodeBridgePage, PlaywrightConnect, PlaywrightDriverPage,
93    PlaywrightLaunch, RealBrowserLaunchResult, RealBrowserOptions, RunCommand, SafeStorageIdentity,
94    StorageEntry, StorageOrigin, StorageState, StorageStateInput, LAUNCH_MODES,
95    SUPPORTED_COOKIE_BROWSERS,
96};
97pub use core::{
98    DialogEvent, DialogManager, DialogType, EngineAdapter, EngineError, EngineType, Logger,
99    LoggerOptions, PdfOptions, Timing, CHROME_ARGS, TIMING,
100};
101pub use downloads::{
102    attach_downloads, normalize_download_options, supported_engine, CaptureOptions,
103    DownloadArtifact, DownloadConflict, DownloadError, DownloadEvent, DownloadManager,
104    DownloadNamer, DownloadNaming, DownloadOptions, DownloadSetting, DownloadValidator,
105    DEFAULT_CAPTURE_TIMEOUT,
106};
107// `fingerprint::ColorScheme` is the CSS preference a page reads, while
108// `browser::ColorScheme` is the one `emulate_media` writes, so the fingerprint
109// one is re-exported under a qualified name instead of shadowing it.
110pub use fingerprint::{
111    apply_automation_parity_args, apply_fingerprint, build_cdp_emulation_commands,
112    build_fingerprint_init_script, build_init_script_config, create_default_fingerprint_preset,
113    create_fingerprint_preset, derive_user_agent_data, detect_automation_controlled_triggers,
114    disables_automation_controlled, find_fingerprint_limitation, fingerprint_field_mechanism,
115    parity_ignored_default_args, relevant_fingerprint_limitations, resolve_fingerprint_profile,
116    AppliedFingerprint, ApplyOptions, AutomationTrigger, BrandVersion, CdpCommand, CdpTransport,
117    ColorScheme as FingerprintColorScheme, DetectedTrigger, FieldMechanism, FingerprintLimitation,
118    FingerprintProfile, ForcedColors, GeolocationProfile, InitScriptOptions, LimitationContext,
119    LimitationEvidence, LimitationSeverity, ReducedMotion, ScreenProfile, UserAgentData,
120    ViewportProfile, WebglProfile, AUTOMATION_CONTROLLED_OFF_ARG, AUTOMATION_CONTROLLED_TRIGGERS,
121    DEFAULT_CHROME_VERSION, FINGERPRINT_FIELD_MECHANISMS, FINGERPRINT_LIMITATIONS,
122    FINGERPRINT_LIMITATIONS_SOURCE, FINGERPRINT_PAYLOAD_SOURCE, FINGERPRINT_PRESET_NAMES,
123    PLAYWRIGHT_HEADLESS_POINTER_ARG, PLAYWRIGHT_SOFTWARE_WEBGL_ARG,
124};
125
126// Reading trace bundles needs no engine, so the reader is available at the
127// crate root like any other pure helper; recording sits beside it.
128pub use traces::{
129    diff_control_state, parse_ndjson, read_trace, ControlChange, ControlChangeKind, ParsedNdjson,
130    Trace, TraceCheckpoint, TraceCheckpointReason, TraceError, TraceEvent, TraceFiles,
131    TraceLiveState, TraceManifest, TraceMode, TraceMutationKind, TraceOutcome, TraceReplaySupport,
132    TRACE_EVENT_SOURCES, TRACE_FORMAT, TRACE_SCHEMA_VERSION,
133};
134pub use traces::{
135    start_trace, trace_links, write_trace_links, write_trace_viewer, AdapterTracePage,
136    TraceCheckpointOptions, TraceLinksOptions, TraceOptions, TraceRecordError, TraceRecorder,
137    TraceResult, TraceStopOptions,
138};
139
140/// Prelude module for convenient imports.
141///
142/// Import everything commonly needed with:
143/// ```rust
144/// use browser_commander::prelude::*;
145/// ```
146pub mod prelude {
147    pub use crate::browser::{
148        clear_browser_cookie_memory_cache, connect_browser, emulate_media, goto,
149        launch_and_connect_real_browser, launch_browser, launch_real_browser,
150        list_browser_profiles, read_browser_cookies, verify_navigation, wait_for_navigation,
151        wait_for_url_stabilization, Browser, BrowserCookie, BrowserCookieReadOptions,
152        BrowserProcess, BrowserProfile, BrowserProfileOptions, ColorScheme, ConnectOptions,
153        EmulateMediaOptions, LaunchMode, LaunchOptions, LaunchResult, NavigationOptions,
154        NavigationResult, RealBrowserLaunchResult, RealBrowserOptions, WaitUntil,
155    };
156    pub use crate::core::{
157        is_navigation_error, is_timeout_error, DialogEvent, DialogManager, DialogType,
158        EngineAdapter, EngineError, EngineType, Logger, LoggerOptions, PdfOptions, Timing,
159        CHROME_ARGS, TIMING,
160    };
161    pub use crate::downloads::{
162        attach_downloads, normalize_download_options, CaptureOptions, DownloadArtifact,
163        DownloadConflict, DownloadError, DownloadEvent, DownloadManager, DownloadOptions,
164        DownloadSetting,
165    };
166    pub use crate::elements::{
167        count, get_attribute, input_value, is_enabled, is_visible, normalize_selector,
168        text_content, ParsedSelector,
169    };
170    pub use crate::fingerprint::{
171        apply_automation_parity_args, apply_fingerprint, build_cdp_emulation_commands,
172        build_fingerprint_init_script, build_init_script_config, create_default_fingerprint_preset,
173        create_fingerprint_preset, derive_user_agent_data, detect_automation_controlled_triggers,
174        disables_automation_controlled, find_fingerprint_limitation, fingerprint_field_mechanism,
175        parity_ignored_default_args, relevant_fingerprint_limitations, resolve_fingerprint_profile,
176        AppliedFingerprint, ApplyOptions, AutomationTrigger, BrandVersion, CdpCommand,
177        CdpTransport, ColorScheme as FingerprintColorScheme, DetectedTrigger, FieldMechanism,
178        FingerprintLimitation, FingerprintProfile, ForcedColors, GeolocationProfile,
179        InitScriptOptions, LimitationContext, LimitationEvidence, LimitationSeverity,
180        ReducedMotion, ScreenProfile, UserAgentData, ViewportProfile, WebglProfile,
181        AUTOMATION_CONTROLLED_OFF_ARG, AUTOMATION_CONTROLLED_TRIGGERS, DEFAULT_CHROME_VERSION,
182        FINGERPRINT_FIELD_MECHANISMS, FINGERPRINT_LIMITATIONS, FINGERPRINT_LIMITATIONS_SOURCE,
183        FINGERPRINT_PAYLOAD_SOURCE, FINGERPRINT_PRESET_NAMES, PLAYWRIGHT_HEADLESS_POINTER_ARG,
184        PLAYWRIGHT_SOFTWARE_WEBGL_ARG,
185    };
186    pub use crate::high_level::{
187        check_and_clear_flag, find_toggle_button, install_click_listener, wait_for_url_condition,
188    };
189    pub use crate::interactions::{
190        click_button, click_element, fill_text_area, key_down, key_up, perform_fill, press_key,
191        scroll_into_view, scroll_into_view_if_needed, type_text, ActivationOptions,
192        ClickActionability, ClickActivation, ClickDispatchError, ClickEffect, ClickOptions,
193        ClickResult, ClickScroll, ClickStatus, Evidence, FillOptions, FillResult, ScrollBehavior,
194        ScrollOptions, ScrollResult,
195    };
196    pub use crate::traces::{
197        diff_control_state, parse_ndjson, read_trace, start_trace, write_trace_viewer,
198        AdapterTracePage, ControlChange, ControlChangeKind, Trace, TraceCheckpoint,
199        TraceCheckpointReason, TraceError, TraceEvent, TraceFiles, TraceLiveState, TraceManifest,
200        TraceMode, TraceMutationKind, TraceOptions, TraceOutcome, TraceRecorder,
201        TraceReplaySupport, TRACE_SCHEMA_VERSION,
202    };
203    pub use crate::utilities::{
204        evaluate, get_domain, get_url, parse_url, safe_evaluate, same_origin, unfocus_address_bar,
205        wait, wait_with_cancel, WaitResult,
206    };
207}
browser_commander/lib.rs

browser_commander/
lib.rs
