Struct Browser 

pub struct Browser { /* private fields */ }

Browser instance. Manages contexts, pages, and browser lifecycle.

Clone is cheap — all clones share the same underlying browser process and state via Arc. This enables exposing browser as a test fixture.

Implementations

impl Browser

pub fn from_state(state: BrowserState) -> Browser

Infra constructor: wrap a BrowserState whose ensure_browser() has already completed. BrowserType::launch is the user-facing path; this entry point exists for ferridriver-internal callers (the test runner / test fixtures / MCP server) that build a crate::options::LaunchPlan directly and need a matching Browser handle.

Safety contract

The caller MUST have awaited state.ensure_browser() (or an equivalent ensure_instance(...) call) before handing the state in — otherwise version() will return "Unknown" until a subsequent ensure.

pub fn from_shared_state(state: Arc<RwLock<BrowserState>>) -> Browser

Wrap an existing shared state as a Browser handle. Used by MCP server and other contexts that already manage browser state.

The version string is read once from the state’s default instance; if the instance has not been launched yet, version() returns "Unknown" until a subsequent ensure_browser fills it in.

pub fn new_context(&self, options: Option<BrowserContextOptions>) -> ContextRef

Create a new isolated browser context. Mirrors Playwright’s browser.newContext(options?) — /tmp/playwright/packages/playwright-core/types/types.d.ts:22229. Pass None for the no-options case (Playwright’s zero-arg form).

Options are stored on the shared crate::state::BrowserState::context_options registry keyed by composite session key and consumed by ContextRef::new_page as each page is opened. The registry itself is a plain std::sync::Mutex clone-handle on self so this setter stays sync regardless of whether an async writer holds the outer RwLock<BrowserState>.

pub fn default_context(&self) -> ContextRef

Get the default browser context.

pub fn supports_isolated_contexts(&self) -> bool

Whether this backend exposes isolated browser contexts (i.e. new_context() actually opens a fresh container vs. silently returning a handle that resolves to the persistent default).

Mirrors Playwright’s behaviour where chromium, firefox, and webkit all support multiple contexts. Stock WKWebView (ferridriver’s WebKit backend) only exposes the persistent default context — there’s no public API for additional containers without a private framework or a custom WKProcessPool fork. Callers that need to share the persistent default in that case can branch on this method.

pub fn backend_kind(&self) -> BackendKind

Backend kind cached at construction. The state’s backend_kind is set once at with_plan and never mutated, so this always matches the live state.

pub fn is_headless(&self) -> bool

Whether the browser was launched in headless mode. Cached at construction; the launch plan never flips this after the fact.

pub async fn new_page(&self) -> Result<Arc<Page>, FerriError>

Shorthand: create a new page in the default context. Equivalent to browser.default_context().new_page().

Errors

Returns an error if page creation fails.

pub async fn new_page_with_url( &self, url: &str, ) -> Result<Arc<Page>, FerriError>

Shorthand: create a new page and navigate to URL.

Errors

Returns an error if page creation or navigation fails.

pub async fn page(&self) -> Result<Arc<Page>, FerriError>

Shorthand: get the active page in the default context. Creates a page if none exists.

Errors

Returns an error if page creation or retrieval fails.

pub async fn close( &self, opts: Option<BrowserCloseOptions>, ) -> Result<(), FerriError>

Close the browser.

Close the browser. Accepts Option<crate::options::BrowserCloseOptions> — mirrors Playwright’s browser.close({ reason }). The reason, if set, is surfaced on TargetClosed errors emitted to any in-flight operation on pages/contexts from this browser. Pass None for the common no-options case.

Errors

Returns an error if the browser cannot be closed cleanly.

pub fn state(&self) -> &Arc<RwLock<BrowserState>>

Access the internal state (for MCP server integration).

pub fn contexts(&self) -> Vec<ContextRef>

List all browser contexts. Sync — mirrors Playwright’s browser.contexts(): BrowserContext[]. Reads the in-memory name registry (default + every new_context); no state lock, no per-page round-trip.

pub fn version(&self) -> &str

Real product version string for the running browser — mirrors Playwright’s synchronous browser.version().

Captured once from CDP Browser.getVersion().product at handshake (e.g. "HeadlessChrome/120.0.6099.109" or "Chrome/120.0.6099.109"). For WebKit returns "WebKit" until we plumb WKWebView’s version through the IPC; for BiDi returns "Firefox". Returns "Unknown" if the handshake did not complete before the Browser handle was constructed.

pub fn is_connected(&self) -> bool

Whether the browser is connected. Sync — mirrors Playwright’s browser.isConnected(): boolean.

Trait Implementations

impl Clone for Browser

fn clone(&self) -> Browser

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.