Browser and Page Handles - SeleniumBase for Rust

A plugin never sees sb_cdp::Browser, Page or BaseCase. The browser and each tab reach it as two small traits, BrowserHandle and PageHandle, which both engines of seleniumbase-rs implement, so one plugin works with either. Both are in seleniumbase_rs_plugin, defined in crates/seleniumbase-rs-plugin/src/lib.rs, and both are async through async_trait.

Who implements them#

Implementation	Where	Public
The pure CDP engine’s browser and tabs	`src/sb_cdp/plugin_hooks.rs` (`BrowserLink`, `TabLink`)	no, the hooks receive them
`seleniumbase_rs::sb_cdp::Page`	`src/sb_cdp/plugin_hooks.rs`	yes: `impl PageHandle for Page`, feature `plugins`
The WebDriver engine’s browser and window	`src/browser/plugin_hooks.rs` (`DriverBrowser`, `DriverPage`)	no, the hooks receive them
`RecordingBrowser`, `RecordingPage`	`seleniumbase-rs-plugin-testing`	yes, see Testing

Every engine’s handle errors are PluginError::Other; the set wraps them as PluginError::Hook with the plugin and the hook.

BrowserHandle#

trait seleniumbase_rs_plugin::BrowserHandle

#[async_trait]pub trait BrowserHandle: Send + Sync {    fn engine(&self) -> Engine;    fn family(&self) -> BrowserFamily;    async fn send(&self, method: &str, params: Value) -> Result<Value>;}

The running browser, as a plugin sees it in on_browser.

BrowserHandle::engine#

fn engine(&self) -> Engine;

returnEngine#

Engine::Cdp on the pure CDP engine, Engine::WebDriver on the WebDriver engine.

BrowserHandle::family#

fn family(&self) -> BrowserFamily;

returnBrowserFamily#

The browser’s family. Always Chromium on the pure CDP engine; on the WebDriver engine, the family of the configured browser.

BrowserHandle::send#

fn async

async fn send(&self, method: &str, params: Value) -> Result<Value>;

method&strrequired#

A browser-level Chrome DevTools Protocol method, such as SystemInfo.getInfo.

paramsserde_json::Valuerequired#

Its parameters, usually json!(...); json!({}) for none.

returnResult<Value>#

The command’s result, as JSON.

Sends a browser-level command and returns its result. Browsers without the protocol return an error.

Engine	What happens
Pure CDP	Sent on the browser’s own connection, with no tab session
WebDriver, Chromium	Sent through chromedriver’s DevTools channel (`goog/cdp/execute`)
WebDriver, Firefox or Safari	Refused: `NAME has no Chrome DevTools Protocol channel through WebDriver, ...`

On every engine the host refuses Fetch.* and Network.setRequestInterception first; see the request guard.

PageHandle#

trait seleniumbase_rs_plugin::PageHandle

#[async_trait]pub trait PageHandle: Send + Sync {    fn engine(&self) -> Engine;    async fn send(&self, method: &str, params: Value) -> Result<Value>;    async fn add_init_script(&self, source: &str) -> Result<()>;    async fn evaluate(&self, expression: &str) -> Result<Value>;}

A tab, as a plugin sees it in on_page_created, and as the set adds a plugin’s packages to it. On the WebDriver engine it is the window the session is on.

PageHandle::engine#

fn engine(&self) -> Engine;

returnEngine#

The engine that runs the tab. A page has no family(): read the family in on_browser, or from LaunchContext, if the plugin needs it.

PageHandle::send#

fn async

async fn send(&self, method: &str, params: Value) -> Result<Value>;

method&strrequired#

A Chrome DevTools Protocol method for this tab, such as Network.enable.

paramsserde_json::Valuerequired#

Its parameters.

returnResult<Value>#

The command’s result, as JSON.

Sends a command to this tab and returns its result. Browsers without the protocol return an error.

Engine	What happens
Pure CDP	Sent on the tab’s own protocol session
WebDriver, Chromium	Sent through `goog/cdp/execute`, which reaches the window the session is on
WebDriver, Firefox or Safari	Refused, as for `BrowserHandle::send`

Before sending, every engine applies two rules:

Fetch.* and Network.setRequestInterception are refused, because the host owns request interception.
Network.setBlockedURLs is merged: its urls are added to the tab’s blocklist (the library’s ad-block list, the tracker hosts of a fingerprint and every pattern a plugin sent), and the whole union is sent, each pattern once, in the order it first arrived. urls must be a list of strings; a command with urlPatterns is refused, because it cannot be merged. A plugin cannot take a pattern back.

PageHandle::add_init_script#

fn async

async fn add_init_script(&self, source: &str) -> Result<()>;

source&strrequired#

JavaScript to run in every document this tab loads from now on.

returnResult<()>#

An error when the script cannot be added, or when it throws in the current document (the script threw: ...).

Runs source in every document this tab loads from now on, before the page’s own scripts.

Engine	What happens
Pure CDP, and WebDriver with Chromium	`Page.addScriptToEvaluateOnNewDocument`, then `Runtime.evaluate` of the same source in the document already loaded
WebDriver, Firefox or Safari	A WebDriver script now, and again after each navigation of the session, so it runs after the page’s own scripts. It runs as a function body: its top-level declarations stay local, so assign to `window` to share a value

PageHandle::evaluate#

fn async

async fn evaluate(&self, expression: &str) -> Result<Value>;

expression&strrequired#

A JavaScript expression.

returnResult<Value>#

Its value, as JSON. An exception is an error, the script threw: ....

Evaluates expression in the current document and returns its value.

Engine	What happens
Pure CDP	`Runtime.evaluate` with `returnByValue` and `awaitPromise`, so a promise is waited for
WebDriver, every browser	A WebDriver script that returns the expression (a trailing `;` is dropped), in the frame the session is on; a promise is waited for

sb_cdp::Page as a PageHandle#

impl Feature: plugins impl PageHandle for seleniumbase_rs::sb_cdp::Page

#[async_trait]impl PageHandle for Page {    fn engine(&self) -> Engine; // Engine::Cdp    async fn send(&self, method: &str, params: Value) -> PluginResult<Value>;    async fn add_init_script(&self, source: &str) -> PluginResult<()>;    async fn evaluate(&self, expression: &str) -> PluginResult<Value>;}

A tab of the pure CDP engine is a PageHandle too, so a program can hand one of its own tabs to code written against the plugin API. It behaves as the tabs the hooks receive, guard included. Page also has inherent methods named evaluate and add_init_script, which differ (the inherent add_init_script returns an identifier and does not run the script in the current document), so call the trait’s with PageHandle::evaluate(&page, ...).