Struct BrowserSession 

pub struct BrowserSession { /* private fields */ }

Implementations

impl BrowserSession

pub async fn click_at( &self, x: f64, y: f64, ) -> BrowserResult<CoordinateClickOutcome>

Click exact frame-local viewport coordinates. This is an explicit, policy-gated escape hatch for canvas and map surfaces where no DOM control can be published. Coordinates are validated against the live viewport and are never adjusted to a nearby element.

pub async fn scroll(&self, dx: f64, dy: f64) -> BrowserResult<ActionOutcome>

Scroll the viewport by the given pixel offsets.

Positive dy scrolls down; positive dx scrolls right.

pub async fn snapshot(&self) -> BrowserResult<AccessibilitySnapshot>

Capture the full accessibility tree snapshot for the current page.

Returns the page info, accessibility roots, and all interactive elements. Prefer observe for compact observations in agent workflows.

pub async fn click(&self, target: &str) -> BrowserResult<ActionOutcome>

Click an element and return its structured action outcome.

pub async fn double_click(&self, target: &str) -> BrowserResult<ActionOutcome>

Double-click an element with the same target, scroll, and pointer contract as a single click.

pub async fn hover(&self, target: &str) -> BrowserResult<ActionOutcome>

Hover the pointer over an element without clicking.

Resolves the target, moves the pointer to the element’s center using the configured interaction mode, then returns an ActionOutcome.

pub async fn drag( &self, source: &str, destination: &str, ) -> BrowserResult<ActionOutcome>

Drag an element from source to destination.

Performs a mouse-press on the source element, moves the pointer to the destination element, then releases.

pub async fn key_down(&self, key: &str) -> BrowserResult<ActionOutcome>

Press and hold a keyboard key.

Dispatches a rawKeyDown CDP event for the given key.

pub async fn key_up(&self, key: &str) -> BrowserResult<ActionOutcome>

Release a keyboard key.

Dispatches a keyUp CDP event for the given key.

pub async fn key_press(&self, key: &str) -> BrowserResult<ActionOutcome>

Press and release a keyboard key.

Dispatches rawKeyDown, char (for single-character keys), and keyUp CDP events.

pub async fn shortcut(&self, shortcut: &str) -> BrowserResult<ActionOutcome>

Execute a keyboard shortcut with modifier keys.

Parses shortcuts like "Ctrl+C" or "Meta+V" and dispatches the corresponding key events with the specified modifiers.

pub async fn clear(&self, target: &str) -> BrowserResult<ActionOutcome>

Clear the contents of an editable element.

Clicks the target, selects all content, then presses Backspace. Verifies the element is empty afterward.

pub async fn check(&self, target: &str) -> BrowserResult<ActionOutcome>

Check a checkbox or radio button.

Ensures the target element’s checked property is set to true.

pub async fn uncheck(&self, target: &str) -> BrowserResult<ActionOutcome>

Uncheck a checkbox.

Ensures the target element’s checked property is set to false.

pub async fn select_option( &self, target: &str, value: &str, ) -> BrowserResult<ActionOutcome>

Select an option from a <select> element by value.

value must be 1–4096 bytes. Fires input and change events.

pub async fn upload_files( &self, target: &str, paths: &[PathBuf], ) -> BrowserResult<ActionOutcome>

pub async fn type_text( &self, text: &str, target: Option<&str>, ) -> BrowserResult<ActionOutcome>

Type text into the page.

If target is provided, clicks the target element first to focus it, then inserts the text via CDP Input.insertText. Otherwise types at the current focus.

impl BrowserSession

pub async fn run_batch( &self, steps: &[BatchStep], ) -> BrowserResult<BatchOutcome>

Execute an ordered batch of typed operations. Policy is pre-flighted for every step before any step executes. Fails fast on the first error; ambiguity always fails closed.

pub async fn run_batch_with_options( &self, steps: &[BatchStep], atomic: bool, ) -> BrowserResult<BatchOutcome>

Execute a batch with optional atomic locator pre-resolution.

impl BrowserSession

pub async fn observe_delta(&self) -> BrowserResult<ObservationDelta>

Return a bounded delta between the cached compact observation and a fresh observation on the same route. Historical snapshots are not retained beyond this request.

pub async fn reconcile_references( &self, from_revision: u64, refs: &[String], ) -> BrowserResult<ReconciliationOutcome>

Reconcile prior references against the current page revision. Maps old refs (r<fromRevision>:b<id>) to current refs via backend node identity or stable role+name matching.

pub async fn reconcile_references_with_options( &self, from_revision: u64, refs: &[String], options: &ReconciliationOptions, ) -> BrowserResult<ReconciliationOutcome>

Reconcile revisioned references with bounded stable hints and an optional scope. Hints are only used after backend identity and the prior role/name identity fail; ambiguity always remains a loss.

pub async fn export_checkpoint(&self) -> BrowserResult<CheckpointV1>

Export a session checkpoint for cross-process resume. Returns JSON bounded to ≤ 4 KiB. No cookies, passwords, or form values.

pub async fn import_checkpoint( &self, checkpoint: &CheckpointV1, ) -> BrowserResult<()>

Import a checkpoint and validate its topology. Does NOT auto-click — only restores target/frame selection context.

impl BrowserSession

pub async fn clipboard_read(&self) -> BrowserResult<String>

Read text from the system clipboard.

Grants the clipboardReadWrite permission temporarily, then evaluates navigator.clipboard.readText(). Returns up to 8 KiB of text.

pub async fn clipboard_write(&self, text: &str) -> BrowserResult<()>

Write text to the system clipboard.

Grants the clipboardReadWrite permission temporarily, then writes via navigator.clipboard.writeText(). Text is truncated to 8 KiB before writing.

impl BrowserSession

pub async fn dismiss_consent(&self) -> BrowserResult<ConsentDismissalOutcome>

Dismiss a visible OneTrust/Cookiebot consent control, if recognized. This only clicks documented consent controls; it does not bypass bot protection or search arbitrary page buttons.

impl BrowserSession

pub async fn diagnostics( &self, duration: Duration, ) -> BrowserResult<DiagnosticReport>

Collect explicitly scoped, bounded, secret-redacted browser evidence.

impl BrowserSession

pub async fn pending_dialog(&self) -> Option<PendingDialog>

Return the currently pending JavaScript dialog content, if any.

Agents should read this before calling accept_dialog or dismiss_dialog to determine the dialog type, message, and default value. The dialog is cleared when it is handled or closed.

pub async fn accept_dialog(&self) -> BrowserResult<()>

Accept (confirm) the currently pending JavaScript dialog.

For prompt dialogs, the default prompt value is submitted. Invalidates the observation cache after handling.

pub async fn dismiss_dialog(&self) -> BrowserResult<()>

Dismiss (cancel) the currently pending JavaScript dialog.

Invalidates the observation cache after handling.

impl BrowserSession

pub async fn diff_observation( &self, before: &CompactAccessibilitySnapshot, ) -> BrowserResult<AccessibilityDiff>

Observe the current page and diff against a prior snapshot.

Takes a fresh observation and computes an AccessibilityDiff comparing it to before. Useful for verifying UI state changes after performing actions.

impl BrowserSession

pub async fn wait_for_download( &self, destination: &Path, deadline: Duration, ) -> BrowserResult<DownloadOutcome>

Wait for one explicitly authorized download lifecycle.

impl BrowserSession

pub async fn set_network_conditions( &self, conditions: Option<&NetworkConditions>, ) -> BrowserResult<()>

Apply session-scoped network throttling. Call with None to reset.

pub async fn set_cpu_throttling(&self, rate: Option<f64>) -> BrowserResult<()>

Apply a session-scoped CPU throttling multiplier. None resets to 1.

pub async fn set_user_agent( &self, user_agent: Option<&str>, accept_language: Option<&str>, platform: Option<&str>, ) -> BrowserResult<()>

Override the user agent and optional Accept-Language for this session. Passing None restores Chrome’s default user agent.

pub async fn print_to_pdf(&self, options: &PdfOptions) -> BrowserResult<String>

Generate a PDF of the current page. Returns base64-encoded PDF data.

Uses CDP Page.printToPDF. All PdfOptions fields are optional; omitted fields use the browser’s default values.

pub async fn set_geolocation( &self, location: Option<&GeoLocation>, ) -> BrowserResult<()>

Override the browser’s reported geolocation.

Pass Some(GeoLocation) to set coordinates; pass None to clear the override and restore the real position.

pub async fn set_timezone(&self, timezone_id: Option<&str>) -> BrowserResult<()>

Override the browser’s reported timezone.

Accepts IANA timezone IDs (e.g. "America/New_York"). Pass None to clear the override and restore the system timezone.

impl BrowserSession

pub async fn fill_form( &self, fields: &[(&str, &str)], ) -> BrowserResult<FillFormOutcome>

Fill multiple form fields atomically.

First resolves all locators (failing atomically on any resolution error), then applies the appropriate action per field based on its role: text inputs get typed, checkboxes/radios get checked/unchecked, selects/combo boxes get option selection.

Bounded to 16 fields per call.

impl BrowserSession

pub async fn list_frames(&self) -> BrowserResult<Vec<FrameInfo>>

List all frames in the active target’s frame tree.

Discovers iframe/out-of-process frames and marks the currently active frame. Call this before select_frame to discover available frame IDs.

pub async fn select_frame(&self, frame_id: &str) -> BrowserResult<FrameInfo>

Select a frame as the active context for subsequent operations.

The frame must exist in the current target’s frame tree. Selecting an iframe creates an isolated execution context for JavaScript evaluation. Invalidates the observation cache.

impl BrowserSession

pub async fn start_network_recording(&self) -> BrowserResult<NetworkRecorder>

Start recording network traffic for the active page session.

Returns a NetworkRecorder guard. Call NetworkRecorder::drain to collect events and NetworkRecorder::stop to finalize.

impl BrowserSession

pub fn sign_http_request( &self, identity: &AgentIdentity, method: &str, target_uri: &str, content_digest: Option<&str>, created: i64, ) -> BrowserResult<SignedHttpRequest>

Sign an explicitly supplied request after policy approval.

impl BrowserSession

pub async fn intercept_request( &self, pattern: &RequestPattern, ) -> BrowserResult<InterceptGuard>

Enable CDP Fetch domain interception for the active page session.

Returns a scoped guard that disables interception on drop. While active, matching requests fire Fetch.requestPaused events. Distinct from the built-in policy Fetch interception.

impl BrowserSession

pub async fn preflight(&self, target: &str) -> PreflightOutcome

pub async fn preflight_with_action( &self, target: &str, action: PreflightAction, ) -> PreflightOutcome

impl BrowserSession

pub async fn page_info(&self) -> BrowserResult<PageInfo>

Return the current page’s URL, title, and ready state.

Evaluates location.href, document.title, and document.readyState in the active page context. Includes the current target and frame IDs.

pub async fn navigate(&self, url: &str) -> BrowserResult<PageInfo>

Navigate the active target to a URL with a 20-second deadline.

Waits for the Page.loadEventFired lifecycle event before returning. The URL is normalized and validated against the active policy.

pub async fn navigate_with_deadline( &self, url: &str, deadline: Duration, ) -> BrowserResult<PageInfo>

Navigate to a URL with an explicit deadline.

Like navigate, but with a caller-specified timeout. deadline must be between 1 ms and 30 seconds.

pub async fn evaluate(&self, expression: &str) -> BrowserResult<Value>

Evaluate arbitrary JavaScript in the active page context.

Policy-gated: requires the Evaluate capability. Invalidates the observation cache after execution since arbitrary JS may mutate DOM.

impl BrowserSession

pub async fn text(&self) -> BrowserResult<String>

Return the visible text content of the current page.

Evaluates document.body.innerText and truncates the result to COMPACT_TEXT_MAX_BYTES (16 KiB).

pub async fn deep_dom(&self) -> BrowserResult<DomNode>

Fetch the full DOM only for an explicit deep-inspection operation.

pub async fn observe(&self) -> BrowserResult<PageContext>

Collect compact page context without a deep DOM or screenshot.

pub async fn observe_with_dom(&self) -> BrowserResult<PageContext>

Collect compact context and explicitly include the full DOM tree.

pub async fn observe_with_screenshot(&self) -> BrowserResult<PageContext>

Collect structured context and explicitly include a current screenshot.

pub async fn observe_with_dom_and_screenshot( &self, ) -> BrowserResult<PageContext>

Collect context with both explicitly requested deep DOM and screenshot data.

pub async fn observe_fresh(&self) -> BrowserResult<PageContext>

Collect fresh compact context, bypassing the compact-context cache.

pub async fn observe_with_form_values(&self) -> BrowserResult<PageContext>

Collect compact context with form field values included. Requires ReadFormValues policy capability in hardened mode.

pub async fn observe_fresh_with_dom(&self) -> BrowserResult<PageContext>

Collect fresh context and explicitly include the full DOM tree.

pub async fn observe_fresh_with_screenshot(&self) -> BrowserResult<PageContext>

Collect fresh structured context and explicitly include a screenshot.

pub async fn observe_fresh_with_dom_and_screenshot( &self, ) -> BrowserResult<PageContext>

Collect fresh context with both explicitly requested deep DOM and screenshot data.

pub async fn observe_with_ranking( &self, ranking: ObservationRanking, ) -> BrowserResult<PageContext>

Collect compact context with an explicit truncation ordering.

impl BrowserSession

pub async fn click_expect_popup( &self, target: &str, ) -> BrowserResult<PopupClickOutcome>

Click a target that is expected to open a popup window.

Monitors target creation events during the click, identifies the new popup target, and returns both the click outcome and the popup’s PageTargetInfo. If no popup appears within the witness window, returns a PopupClickError.

impl BrowserSession

pub async fn click_with_retry( &self, target: &str, policy: &RetryPolicy, ) -> BrowserResult<ActionOutcome>

Click one element with retry on transport/CDP errors. Targeting ambiguity always fails immediately.

pub async fn navigate_with_retry( &self, url: &str, policy: &RetryPolicy, ) -> BrowserResult<PageInfo>

Navigate to a URL with retry on transport/CDP errors.

impl BrowserSession

pub async fn cookies(&self) -> BrowserResult<Vec<Cookie>>

Read all browser cookies for the current page URL.

Uses CDP Network.getCookies. Policy-gated: requires PersistentProfile capability.

pub async fn set_cookies(&self, cookies: &[Cookie]) -> BrowserResult<()>

Set browser cookies.

Each cookie must have at least name, value, and domain. Uses CDP Network.setCookies. Requires PersistentProfile.

pub async fn clear_cookies(&self) -> BrowserResult<()>

Clear all browser cookies.

Uses CDP Network.clearBrowserCookies. Requires PersistentProfile.

pub async fn local_storage(&self) -> BrowserResult<StorageItems>

Read localStorage items for the current page.

Bounded to 64 entries; each value capped at 1 KiB. Requires PersistentProfile.

pub async fn session_storage(&self) -> BrowserResult<StorageItems>

Read sessionStorage items for the current page.

Bounded to 64 entries; each value capped at 1 KiB. Requires PersistentProfile.

impl BrowserSession

pub async fn list_targets(&self) -> BrowserResult<Vec<PageTargetInfo>>

List all open page targets in the browser.

Returns the target ID, URL, title, opener relationship, and whether each target is currently active. Capped at 32 targets.

pub async fn topology_events(&self) -> Vec<TopologyEventSummary>

Return recent topology change events for diagnostic purposes.

Each event includes a sequence number, kind (e.g. targetCreated), and the affected target/frame ID. Bounded to 64 recent events.

pub async fn create_target(&self, url: &str) -> BrowserResult<PageTargetInfo>

Open a new page target navigating to the given URL.

The URL is normalized and validated against the active policy. The new target is discoverable via list_targets but does not become the active target automatically.

pub async fn select_target( &self, target_id: &str, ) -> BrowserResult<PageTargetInfo>

Select a page target as the active context.

Attaches to the target via CDP, selects its main frame, and detaches from the previously active target. Invalidates the observation cache.

pub async fn close_target(&self, target_id: &str) -> BrowserResult<()>

Close a page target by ID.

If the closed target was the active target, the session’s active target, session, and frame state are cleared.

impl BrowserSession

pub async fn with_targets<F, Fut>( &self, n: usize, f: F, ) -> BrowserResult<Fut::Output>

where F: FnOnce(Vec<PageTargetInfo>) -> Fut, Fut: Future,

Open n page targets, execute an async closure with concurrent access, then close all opened targets.

The closure receives the list of opened target infos. Targets are closed automatically when the closure returns (or panics). Bounded to 4 concurrent targets.

The active target before calling this method is restored after all opened targets are closed.

impl BrowserSession

pub async fn screenshot_png(&self) -> BrowserResult<Vec<u8>>

Capture a PNG screenshot and return the raw PNG bytes.

Policy-gated: requires the Screenshot capability. Base64-decodes the CDP payload for direct file writing or image processing.

pub async fn screenshot_base64(&self) -> BrowserResult<String>

Capture a PNG while preserving CDP’s base64 payload for image APIs.

pub async fn capture_visual( &self, options: &VisualCaptureOptions, ) -> BrowserResult<VisualCapture>

Capture exact opt-in visual evidence with explicit effective metadata.

pub async fn start_screencast( &self, format: VisualFormat, quality: u8, max_width: u32, max_height: u32, ) -> BrowserResult<ScreencastScope>

impl BrowserSession

pub async fn wait( &self, condition: WaitCondition, deadline: Duration, ) -> BrowserResult<WaitOutcome>

Wait for a condition to be satisfied on the page.

Supported conditions include lifecycle events ("complete", "interactive"), URL matching, target visibility/enabled/stability, text presence, JavaScript expressions, and network quiet. Returns a WaitOutcome on success or a WaitTimeout error if the deadline expires.

impl BrowserSession

pub async fn enable_webauthn( &self, options: &WebAuthnOptions, ) -> BrowserResult<WebAuthnGuard>

Enable a virtual WebAuthn authenticator for the session.

Returns a WebAuthnGuard scoped to this session. Use WebAuthnGuard::add_credential to provision credentials before navigating to the page under test.

impl BrowserSession

pub fn owned_chrome_pid(&self) -> Option<u32>

PID of Chrome launched by this session, absent for attached sessions.

pub fn cdp_request_count(&self) -> u64

Number of CDP commands issued by this session’s page connection.

pub fn cdp_wait_nanos(&self) -> u64

Total time spent awaiting responses from the page’s CDP connection.

pub async fn measure_cdp_wait<F>(&self, future: F) -> (F::Output, u64)

where F: Future,

Measure CDP response wait time initiated by one async operation.

pub async fn start(options: &SessionOptions) -> BrowserResult<Self>

pub async fn start_with_policy( options: &SessionOptions, policy: BrowserPolicy, ) -> BrowserResult<Self>

pub fn raw_cdp(&self) -> BrowserResult<&CdpClient>

Explicit privileged escape hatch for benchmark and protocol diagnostics. Hardened sessions deny it unless raw-cdp is deliberately allowed.

pub fn profile_name(&self) -> &str

pub fn policy(&self) -> &BrowserPolicy

pub fn is_attached(&self) -> bool

Whether the Chrome process was explicitly attached rather than launched by this session.

pub fn owns_chrome(&self) -> bool

Whether this session owns the Chrome process and will stop it on close.

pub async fn set_viewport( &self, width: i64, height: i64, device_scale_factor: Option<f64>, is_mobile: Option<bool>, ) -> BrowserResult<()>

Override the viewport metrics for device emulation.

Uses CDP Emulation.setDeviceMetricsOverride. Reset on session close or call with width: 0, height: 0 to clear.

pub async fn failure_trace( &self, outcome: ActionOutcome, error: impl Into<String>, ) -> FailureTracePack

Build a bounded failure-trace pack suitable for agent self-correction.

The returned bundle includes the last compact observation, an action outcome, an error message, and the active topology state. It is deliberately bounded (≤ 8 KiB), redacted for secrets, and excludes DOM/expression/screenshot payloads. Agents can use this to decide whether to re-observe, select a different target, or escalate without a full DOM round-trip.

pub async fn failure_trace_for( &self, action: ActionKind, error: impl Into<String>, ) -> FailureTracePack

Build a failure trace for an operation that did not produce an ActionOutcome, such as navigation, waiting, or invalid input.

pub fn audit_log(&self) -> Vec<AuditEntry>

Return a snapshot of the current session audit log.

The log records high-risk operations (navigate, evaluate, upload, download, attach) with bounded, redacted detail. It is only populated when --audit is set on session start. Entries are bounded to MAX_AUDIT_ENTRIES; the oldest are dropped on overflow.

pub async fn close(self) -> BrowserResult<()>