Struct ContextRef 

pub struct ContextRef { /* private fields */ }

Handle to a browser context. Created by Browser::new_context() / default_context(). Provides the Playwright-compatible context API by delegating to BrowserState.

Implementations

impl ContextRef

pub fn new(state: Arc<RwLock<BrowserState>>, name: String) -> Self

pub fn browser(&self) -> Option<&Browser>

Parent browser handle, or None for a context not created from a crate::Browser. Mirrors Playwright’s browserContext.browser(): Browser | null (/tmp/playwright/packages/playwright-core/src/client/browserContext.ts:290).

pub fn is_closed(&self) -> bool

Whether this context has been closed. Mirrors Playwright’s browserContext.isClosed(): boolean (/tmp/playwright/packages/playwright-core/src/client/browserContext.ts:298). false from handle creation until Self::close is called (or the underlying browser instance is shut down / disconnected), matching Playwright’s _closingStatus !== 'none'. Uses the shared BrowserState::context_closed flag so a close() on one handle is seen by every clone with the same composite key.

pub fn events(&self) -> &ContextEventEmitter

Context-scoped event emitter. Cheap to clone.

pub fn name(&self) -> &str

Context name.

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

Create a new page in this context.

Errors

Returns an error if page creation fails.

pub async fn pages(&self) -> Result<Vec<Arc<Page>>>

Get all pages in this context as Page handles.

Errors

Returns an error if the context does not exist.

pub async fn cookies(&self) -> Result<Vec<CookieData>>

Get all cookies in this context.

Errors

Returns an error if the context does not exist or cookie retrieval fails.

pub async fn storage_state( &self, opts: Option<StorageStateOptions>, ) -> Result<StorageState>

Export the current storage state of this context — cookies plus a per-origin localStorage snapshot.

Playwright: storageState(options?: { path?: string, indexedDB?: boolean }) : Promise<{ cookies, origins }> (/tmp/playwright/packages/playwright-core/src/client/browserContext.ts:460; server collection at .../server/browserContext.ts:609).

Cookies are read via the existing Self::cookies surface. For each live page in the context we evaluate Object.entries(localStorage) to snapshot its origin’s storage, grouping by location.origin and skipping origins with no entries (mirrors Playwright’s if (storage.localStorage .length) filter). opts.path, when set, writes the JSON-serialized state (pretty-printed) to disk; opts.indexed_db is accepted for signature parity but does not yet collect IndexedDB databases.

Errors

Returns an error if the context does not exist, cookie retrieval fails, or (when path is set) the file cannot be written.

pub async fn add_cookies(&self, cookies: Vec<CookieData>) -> Result<()>

Add cookies to this context.

Errors

Returns an error if the context does not exist or setting cookies fails.

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

Clear all cookies in this context.

Errors

Returns an error if the context does not exist or clearing cookies fails.

pub async fn clear_cookies_filtered( &self, options: &ClearCookieOptions, ) -> Result<()>

Clear cookies matching the given filters (matches Playwright’s context.clearCookies(options?)). If no filters are specified, all cookies are cleared.

Errors

Returns an error if the context does not exist or clearing cookies fails.

pub async fn delete_cookie( &self, name: &str, domain: Option<&str>, ) -> Result<()>

Delete a specific cookie by name and optional domain (matches Playwright’s context.clearCookies({ name })).

Errors

Returns an error if the context does not exist or deleting fails.

pub fn set_default_timeout(&self, ms: u64)

Set the default timeout for actions in this context (ms). Mirrors Playwright’s browserContext.setDefaultTimeout(timeout). Takes &self (interior mutability via Arc<AtomicU64>) so it works behind a shared handle.

pub fn set_default_navigation_timeout(&self, ms: u64)

Set the default navigation timeout for this context (ms). Mirrors Playwright’s browserContext.setDefaultNavigationTimeout(timeout).

pub fn default_timeout(&self) -> u64

Current default action timeout (ms). 0 = no override.

pub fn default_navigation_timeout(&self) -> u64

Current default navigation timeout (ms). 0 = no override.

pub async fn grant_permissions( &self, permissions: &[String], _origin: Option<&str>, ) -> Result<()>

Grant permissions in this context. Stores the list on the options bag and re-applies to every open page — matches Playwright’s browserContext.grantPermissions semantics where the grant persists for future pages too.

The origin parameter is currently ignored at the backend level (CDP Browser.grantPermissions accepts an origin but we don’t thread it through the options bag yet — the bag-stored list grants for every origin).

Errors

Returns an error if the re-application fails on any page.

pub async fn clear_permissions(&self) -> Result<()>

Clear all granted permissions.

Errors

Returns an error if resetting permissions fails.

pub async fn close(&self) -> Result<()>

Close this context (remove from BrowserState).

Errors

Returns an error if state lock acquisition fails.

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

Access the internal state (for MCP server integration).

pub async fn set_record_video(&self, opts: RecordVideoOptions) -> Result<()>

Enable recordVideo for pages opened in this context AFTER the call. Pages already open do not retroactively start recording — matches Playwright’s context-creation-time binding semantics (browser.newContext({ recordVideo: { dir, size? } })).

Transitional shim — prefer passing recordVideo to browser.newContext(options) directly.

Errors

Returns an error if the state write fails. Does NOT re-apply to already-open pages (the recording runtime attaches at page open via start_video_recording).

pub fn on(&self, event_name: &str, callback: ContextEventCallback) -> ListenerId

Register a context-level event listener. Supported events: 'weberror' (unhandled errors / rejections on any page in this context — mirrors Playwright’s browserContext.on('weberror', (webError: WebError) => ...)).

pub fn once( &self, event_name: &str, callback: ContextEventCallback, ) -> ListenerId

One-shot context-level listener — see Self::on.

pub fn off(&self, id: ListenerId)

Remove a previously registered context-level listener.

pub async fn wait_for_event( &self, event_name: &str, timeout_ms: u64, ) -> Result<ContextEvent>

Wait for the next context-level event matching event_name, with timeout_ms. Mirrors Playwright’s browserContext.waitForEvent(event, options?).

Errors

Returns an error if the timeout elapses or the event channel is closed.

pub async fn add_init_script( &self, script: InitScriptSource, arg: Option<Value>, ) -> Result<Disposable>

Add an init script to all pages in this context (current + future). Mirrors Playwright’s browserContext.addInitScript(script, arg) from /tmp/playwright/packages/playwright-core/src/client/browserContext.ts:356. See crate::page::Page::add_init_script for argument semantics.

Returns a crate::disposable::Disposable whose dispose() removes the injected script from every page it was added to. Mirrors Playwright browserContext.addInitScript(...) which returns a DisposableObject (client/browserContext.ts:361).

Errors

Returns an error if evaluation_script lowering fails, the context does not exist, or script injection fails on any page.

pub async fn set_geolocation( &self, lat: f64, lng: f64, accuracy: f64, ) -> Result<()>

Playwright: browserContext.setGeolocation(geo) — mutates the options bag and re-applies to every open page.

Errors

Returns an error if re-application fails on any page.

pub async fn set_extra_http_headers( &self, headers: &FxHashMap<String, String>, ) -> Result<()>

Playwright: browserContext.setExtraHTTPHeaders(headers).

Errors

Returns an error if re-application fails on any page.

pub async fn set_offline(&self, offline: bool) -> Result<()>

Playwright: browserContext.setOffline(offline).

Errors

Returns an error if re-application fails on any page.

pub async fn set_http_credentials( &self, credentials: Option<HttpCredentials>, ) -> Result<()>

Playwright: browserContext.setHTTPCredentials(httpCredentials | null) (/tmp/playwright/packages/playwright-core/src/client/browserContext.ts:355). Stores the credentials on the context options bag so pages opened later inherit them, and applies them to every already-open page. Passing None clears stored credentials — future 401 challenges then surface as the browser’s native auth dialog rather than being answered automatically.

The bag mutation alone cannot express “clear” (the per-field apply_context_options future is keyed on Some), so this drives the dedicated crate::Page::set_http_credentials backend path on each open page directly.

Errors

Returns an error if any open page’s backend rejects the change (e.g. a backend that does not support auth-challenge interception).

pub async fn route( &self, matcher: UrlMatcher, handler: RouteHandler, times: Option<u32>, ) -> Result<Disposable>

Register a route handler for all pages in this context.

Returns a crate::disposable::Disposable whose dispose() removes the handler from every page (equivalent to Self::unroute). Mirrors Playwright browserContext.route(...) which returns a DisposableStub (client/browserContext.ts:377).

Errors

Returns an error if the context does not exist or route registration fails.

pub async fn route_from_har( &self, path: &Path, options: RouteFromHarOptions, ) -> Result<()>

Playwright: browserContext.routeFromHAR(har, options?). Replays a HAR file across every page in this context. Replay-only; recording (update: true) is unsupported.

Errors

Returns an error if the HAR file cannot be read/parsed or routes fail to install.

pub async fn unroute(&self, matcher: &UrlMatcher) -> Result<()>

Remove route handlers matching the given matcher from all pages.

Errors

Returns an error if the context does not exist or route removal fails.

pub async fn expose_binding( &self, name: &str, callback: ExposedBinding, ) -> Result<Disposable>

Playwright: browserContext.exposeBinding(name, callback) from /tmp/playwright/packages/playwright-core/src/client/browserContext.ts:364.

Registers window[name] on every page in this context (current + future). The page-side call routes back into callback, which receives a crate::events::BindingSource as its first argument followed by the page-side call args. The callback’s return value (after awaiting any returned promise in the binding layers) is delivered to the page-side caller.

Returns a crate::disposable::Disposable whose dispose() removes the binding from the registry and from every page in the context.

Errors

Returns an error if the context does not exist or injection fails on any page.

pub async fn expose_function( &self, name: &str, callback: ExposedFn, ) -> Result<Disposable>

Playwright: browserContext.exposeFunction(name, callback) from /tmp/playwright/packages/playwright-core/src/client/browserContext.ts:370.

exposeFunction is exposeBinding minus the source argument: the supplied source-less crate::events::ExposedFn is wrapped into an crate::events::ExposedBinding that discards the crate::events::BindingSource.

Errors

Returns an error if the context does not exist or injection fails on any page.

pub async fn remove_exposed_binding(&self, name: &str) -> Result<()>

Remove a previously exposed binding/function from the registry and from every page in this context. Mirrors Playwright’s BrowserContext.removeExposedBinding (driven by Disposable).

Errors

Returns an error if removal fails on any open page.

Trait Implementations

impl Clone for ContextRef

fn clone(&self) -> ContextRef

Returns a duplicate of the value.

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

Performs copy-assignment from source.