The Plugin Trait

A plugin is a type that implements Plugin. name is the only method without a default; every hook does nothing unless you override it. Items are in seleniumbase_rs_plugin (seleniumbase_rs::plugin_api from seleniumbase-rs), defined in crates/seleniumbase-rs-plugin/src/lib.rs. A walk-through is in Writing your own; when each hook runs on each engine is in When the hooks run.

Plugin#

trait seleniumbase_rs_plugin::Plugin

#[async_trait]pub trait Plugin: Send + Sync + 'static {    fn name(&self) -> &str;    fn dependencies(&self) -> &[&str] { &[] }    fn requirements(&self) -> Requirements { Requirements::empty() }    fn metadata(&self) -> Metadata { Metadata::legacy() }    fn per_launch(&self) -> Option<Arc<dyn Plugin>> { None }    fn packages(&self) -> Vec<Package> { Vec::new() }    async fn before_launch(&self, _launch: &mut LaunchSettings) -> Result<()> { Ok(()) }    async fn on_browser(&self, _browser: &dyn BrowserHandle) -> Result<()> { Ok(()) }    async fn on_page_created(&self, _page: &dyn PageHandle) -> Result<()> { Ok(()) }    async fn on_close(&self) -> Result<()> { Ok(()) }}

The trait is object safe through #[async_trait]: a set keeps plugins as Arc<dyn Plugin>. Write #[async_trait] on every impl Plugin too. The supertraits Send + Sync + 'static let one plugin serve several browsers and tasks at once, so keep mutable state behind atomics or a Mutex.

Plugin::name#

fn name(&self) -> &str;

A set refuses a second plugin with the same name (PluginError::DuplicateName). Other plugins refer to this name in dependencies, requires, conflicts_with, after and before. A plugin that is also Configurable returns Self::NAME, the name a registry builds it by.

Plugin::dependencies#

fn dependencies(&self) -> &[&str] {    &[]}

Each name joins the plugin’s requires edges from Metadata::requires: the named plugin must be in the set, or the check fails with PluginError::MissingDependency, and it runs before this one.

Plugin::requirements#

fn requirements(&self) -> Requirements {    Requirements::empty()}

The check refuses a browser that does not fit with PluginError::Requirement. RUN_LAST refuses nothing; it puts the plugin in the phase Last.

Plugin::metadata#

fn metadata(&self) -> Metadata {    Metadata::legacy()}

The default, Metadata::legacy(), has no category and the legacy capability set (raw:cdp among them). Such a plugin is “undeclared”: a plain set runs it, a strict set refuses it with PluginError::Undeclared. The command line, the MCP server and every set built from names are strict.

Plugin::per_launch#

fn per_launch(&self) -> Option<Arc<dyn Plugin>> {    None}

PluginSet::for_launch replaces the plugin with the instance it returns, keeping its grants, so browsers launched from one set (a pool) do not share the plugin’s state and on_close reaches the instance that started. Both engines call for_launch before every launch and every attach. The fresh instance must have the same name; one with another name is ignored and the shared instance is kept.

Plugin::packages#

fn packages(&self) -> Vec<Package> {    Vec::new()}

Every package must say where it loads (only_on or everywhere), or the check refuses the plugin with PluginError::Requirement (one of its packages says neither `only_on` nor `everywhere` ). For each new tab, the set adds the plugin’s packages with PageHandle::add_init_script, then calls its on_page_created. A package that fails is reported as PluginError::Hook with the hook packages.

Plugin::before_launch#

async fn before_launch(&self, _launch: &mut LaunchSettings) -> Result<()> {    Ok(())}

Runs before the browser starts, in run order. It does not run when the program attaches to a running browser. After each plugin the set checks what it changed: each change needs its capability, list fields only grow, a refused switch or feature needs raw:switches, the profile is read-only, and a field another plugin sealed keeps its value. The rules are under PluginSet::before_launch.

Plugin::on_browser#

async fn on_browser(&self, _browser: &dyn BrowserHandle) -> Result<()> {    Ok(())}

Runs once the browser runs, whether the program started it or attached to it.

Plugin::on_page_created#

async fn on_page_created(&self, _page: &dyn PageHandle) -> Result<()> {    Ok(())}

Runs for every tab the library attaches to, before any command of the program runs in it. The plugin’s own packages are already added.

Plugin::on_close#

async fn on_close(&self) -> Result<()> {    Ok(())}

Runs when the browser is about to close. Every plugin runs even when one fails; PluginSet::on_close returns the failures, and both engines log each one at WARN (cdp.plugin.close.failed, webdriver.plugin.close.failed). Use it to clean up, such as deleting temporary folders.

Result#

type seleniumbase_rs_plugin::Result

pub type Result<T> = std::result::Result<T, PluginError>;

The result of every hook and of the fallible PluginSet and Registry methods. In a program that also uses std::result::Result, import it under another name: use seleniumbase_rs::plugin_api::Result as PluginResult;.

PluginError#

enum non_exhaustive seleniumbase_rs_plugin::PluginError

#[derive(Debug, thiserror::Error)]#[non_exhaustive]pub enum PluginError {    DuplicateName(String),    MissingDependency { plugin: String, missing: String },    Requirement { plugin: String, reason: String },    Hook { plugin: String, hook: &'static str, message: String },    Cycle(Vec<String>),    Conflict { a: String, b: String },    Sealed { field: &'static str, a: String, b: String },    Unsupported { plugin: String, capability: String, host: &'static str },    Capability { plugin: String, capability: String, reason: String },    Undeclared(String),    Config(String),    Other(String),}

Why a plugin, or the set, refused to go on. It implements std::error::Error and Display; seleniumbase-rs turns it into SeleniumBaseError::Plugin with From. The Display text of each variant is shown below, with each field in capitals.

PluginError::other#

fn seleniumbase_rs_plugin::PluginError::other

pub fn other(message: impl Into<String>) -> Self

The usual way for a hook to fail. The set adds the plugin’s name and the hook when it wraps the error in PluginError::Hook.

async_trait#

macro seleniumbase_rs_plugin::async_trait

pub use async_trait::async_trait;

The async_trait attribute macro of the crate async-trait (0.1), re-exported so a plugin crate needs no dependency of its own for it. Put #[async_trait] on every impl Plugin, impl BrowserHandle and impl PageHandle.

See also#