pub struct BrowserSession { /* private fields */ }Expand description
A browser automation session backed by CDP.
Manages an optional child process (auto-spawned Lightpanda) and a direct CDP WebSocket connection for interaction.
The session is designed to be held behind Arc<tokio::sync::Mutex<Option<BrowserSession>>>
for shared access across async tool calls. All public methods take &self.
§Process lifecycle
When created via launch(), the Lightpanda process is
spawned with kill_on_drop(true) and additionally killed in the Drop
impl. This ensures cleanup even if close() is not called.
Implementations§
Source§impl BrowserSession
impl BrowserSession
Sourcepub async fn launch() -> Result<Self>
pub async fn launch() -> Result<Self>
Spawn a Lightpanda process and connect to it via CDP.
- Finds a free TCP port by binding to
127.0.0.1:0 - Starts
lightpanda serve --host 127.0.0.1 --port <port> - Polls the port until CDP accepts connections (up to 10 seconds)
- Connects via WebSocket and opens a blank page
If lightpanda is not found on PATH, it is automatically downloaded
from GitHub releases and installed to ~/.local/bin/.
§Errors
BrowserError::InstallFailedif auto-installation failsBrowserError::SpawnFailediflightpandafails to start after installationBrowserError::Timeoutif CDP doesn’t become available within 10 secondsBrowserError::ConnectionFailedif WebSocket handshake fails
Sourcepub async fn connect(cdp_url: &str) -> Result<Self>
pub async fn connect(cdp_url: &str) -> Result<Self>
Connect to an existing CDP endpoint.
Use this when the browser is managed externally (e.g. headless Chromium started by systemd, or a shared Lightpanda instance).
§Arguments
cdp_url— WebSocket URL (e.g.ws://127.0.0.1:9222/).
§Errors
BrowserError::ConnectionFailedif the endpoint is unreachable
Navigate to a URL. Returns the page title after load.
§Errors
BrowserError::NavigationFailedon invalid URL or network error
Sourcepub async fn extract(&self, selector: Option<&str>) -> Result<String>
pub async fn extract(&self, selector: Option<&str>) -> Result<String>
Extract text content from the page or a specific element.
selector = None→ returnsdocument.body.innerText(full page text)selector = Some("h1")→ returns text of the first matching element
§Errors
BrowserError::ElementNotFoundif the selector matches nothingBrowserError::EvalFailedif text extraction fails
Sourcepub async fn click(&self, selector: &str) -> Result<()>
pub async fn click(&self, selector: &str) -> Result<()>
Click an element by CSS selector.
Dispatches a full MouseEvent (not just el.click()) so that
framework event listeners (React, Vue, etc.) see the event.
For submit buttons, also calls form.requestSubmit() to ensure
form submission fires correctly.
§Errors
BrowserError::ElementNotFoundif the selector matches nothing
Sourcepub async fn type_text(&self, selector: &str, text: &str) -> Result<()>
pub async fn type_text(&self, selector: &str, text: &str) -> Result<()>
Type text into an element identified by CSS selector.
Uses the native HTMLInputElement value setter to bypass React’s
internal value tracker, then dispatches input and change events
so both React controlled inputs and plain HTML inputs update correctly.
§Errors
BrowserError::ElementNotFoundif the selector matches nothing
Sourcepub async fn evaluate(&self, js: &str) -> Result<String>
pub async fn evaluate(&self, js: &str) -> Result<String>
Execute JavaScript on the page and return the result as a string.
String values are returned as-is. Numbers, booleans, objects, and arrays
are serialized via serde_json::Value::to_string().
§Errors
BrowserError::EvalFailedon syntax errors or runtime exceptions
Sourcepub fn is_auto_spawned(&self) -> bool
pub fn is_auto_spawned(&self) -> bool
Returns true if this session was auto-spawned (vs. connected to an
external endpoint).