Plugin API Reference - SeleniumBase for Rust

Early Feature: plugins seleniumbase-rs-plugin 0.1.2

The browser-plugin API of seleniumbase-rs is the crate seleniumbase-rs-plugin in the seleniumbase-rs-plugins repository. A plugin is a type that implements its Plugin trait; a PluginSet holds the plugins a program uses, checks them and calls their hooks; seleniumbase-rs calls the set from both of its engines. These pages document every public item at the revision seleniumbase-rs pins, 628991af0e6c5711298e3bd3692dc2974887401a, as the code defines it. For a tutorial, read Writing your own; for the design, Plugin architecture.

Info

Quick reference

API crate: seleniumbase-rs-plugin (Rust 2024, MSRV 1.88, MIT); from seleniumbase-rs it is seleniumbase_rs::plugin_api, feature plugins.
Required: fn name(&self) -> &str. Hooks: before_launch, on_browser, on_page_created, on_close.
By name: Configurable, Descriptor, PluginSpec, Registry.
Tests: seleniumbase-rs-plugin-testing (RecordingPage, RecordingBrowser, Call, block_on).
Pin: every dependency on the plugins repository at rev = "628991af0e6c5711298e3bd3692dc2974887401a".

Depend on it#

A plugin crate depends on the API crate only, never on seleniumbase-rs, so it keeps working as seleniumbase-rs changes. A program that runs plugins depends on seleniumbase-rs with the feature plugins and on the plugin crates it uses.

[dependencies]seleniumbase-rs-plugin = { git = "https://github.com/MustCodeAl/seleniumbase-rs-plugins", rev = "628991af0e6c5711298e3bd3692dc2974887401a" }serde_json = "1"[dev-dependencies]seleniumbase-rs-plugin-testing = { git = "https://github.com/MustCodeAl/seleniumbase-rs-plugins", rev = "628991af0e6c5711298e3bd3692dc2974887401a" }

[dependencies]seleniumbase-rs = { git = "https://github.com/MustCodeAl/seleniumbase-rs", features = ["plugins"] }seleniumbase-rs-plugin-hello = { path = "../seleniumbase-rs-plugin-hello" }

cargo add seleniumbase-rs-plugin --git https://github.com/MustCodeAl/seleniumbase-rs-plugins --rev 628991af0e6c5711298e3bd3692dc2974887401acargo add --dev seleniumbase-rs-plugin-testing --git https://github.com/MustCodeAl/seleniumbase-rs-plugins --rev 628991af0e6c5711298e3bd3692dc2974887401a

Warning

seleniumbase-rs takes seleniumbase-rs-plugin and seleniumbase-rs-plugins-builtin from one git URL at one rev, 628991af0e6c5711298e3bd3692dc2974887401a. Cargo counts the same repository under another reference (a branch, a tag, another rev) as another source, so a plugin crate pinned differently builds a second copy of the API, and its Plugin is not the trait seleniumbase-rs calls. See Cargo features.

Two paths to the same items#

In	Write	Needs
A plugin crate	`use seleniumbase_rs_plugin::...`	the API crate
A program that uses seleniumbase-rs	`use seleniumbase_rs::plugin_api::...`	seleniumbase-rs with the feature `plugins`

seleniumbase_rs::plugin_api is a re-export of the whole crate (pub use seleniumbase_rs_plugin as plugin_api), so the two paths name the same types. It is not the module seleniumbase_rs::plugins, which holds the test-reporting plugins.

Stability#

The API crate is on 0.1.x and changes by addition. Items marked #[non_exhaustive] can grow:

enums PluginError, Engine, BrowserFamily, ProfileView, WebRtcPolicy, Category, Phase, Capability and HostKind: a match on one needs a wildcard arm;
structs LaunchSettings, Metadata, Budgets and AuditRow: their public fields can be read and assigned, but code outside the crate cannot build one with a struct literal. Start from LaunchSettings::default(), Metadata::new, Budgets::default().

Pages#

The Plugin trait

Plugin and each of its hooks, Result, PluginError and async_trait.

Launch settings

LaunchContext, LaunchSettings, ProfileView, Engine, BrowserFamily, WebRtcPolicy.

Handles

BrowserHandle and PageHandle, and what each engine does behind them.

PluginSet

Building a set, grants and trust, the check, the audit, the order, AuditRow.

Configuration

Configurable, Descriptor, PluginSpec and Registry: plugins built from a name and options.

Metadata

The Metadata builder, Category, Phase, Seals and Budgets.

Capabilities

Capability, CapabilitySet, scopes, risk, HostInfo, refused switches and features.

Requirements and packages

Requirements and Package: what a plugin needs from the browser, and scripts and styles for pages.

The seleniumbase-rs host

Cargo features, the launch builders, plugin_host, the request guard and SeleniumBaseError::Plugin.

Selection by name

PluginSelection, SB_PLUGINS, the settings loaders and cli::plugin_cmd.

Testing

RecordingPage, RecordingBrowser, Call and block_on.

Module map#

The API crate, crates/seleniumbase-rs-plugin/src/ in the plugins repository:

File	Public items	Page
`lib.rs`	`Plugin`, `Result`, `PluginError`, `async_trait`	The Plugin trait
`lib.rs`	`LaunchContext`, `LaunchSettings`, `ProfileView`, `Engine`, `BrowserFamily`, `WebRtcPolicy`	Launch settings
`lib.rs`	`BrowserHandle`, `PageHandle`	Handles
`lib.rs`	`PluginSet`, `AuditRow`	PluginSet
`lib.rs`	`Requirements`, `Package`	Requirements and packages
`config.rs`	`Configurable`, `Descriptor`, `PluginSpec`, `Registry`	Configuration
`metadata.rs`	`Metadata`, `Category`, `Phase`, `Seals`, `Budgets`	Metadata
`capability.rs`	`Capability`, `CapabilitySet`, `HostScope`, `NetScope`, `PathScope`, `RawKind`, `Risk`, `Enforcement`, `ParseCapabilityError`	Capabilities
`host.rs`	`HostInfo`, `HostKind`	Capabilities
`switch_policy.rs`	module `switch_policy`: `REFUSED_SWITCHES`, `REFUSED_FEATURES`, `switch_name`, `refusal`, `feature_refused`	Capabilities
`order.rs`	nothing public: the resolver behind the run order	PluginSet

The testing crate, crates/seleniumbase-rs-plugin-testing/src/lib.rs: RecordingPage, RecordingBrowser, Call, block_on (Testing).

The host side, in seleniumbase-rs:

Path	Public items	Page
`src/lib.rs`	`plugin_api`, `builtin_plugins` (re-exports)	Host
`src/sb_cdp/launch.rs`	`LaunchOptionsBuilder::plugins`, `plugins_named`, `plugin_selection`	Host
`src/sb_cdp/browser.rs`	`Browser::connect_with_plugins`	Host
`src/browser/config.rs`	`BrowserConfig::with_plugins`, `with_plugins_named`, `with_plugin_selection`, `plugins`	Host
`src/plugin_host/`	`builtin_registry`, `build`, `build_with`; the request guard	Host
`src/error.rs`	`SeleniumBaseError::Plugin`	Host
`src/config/plugins.rs`	`PluginSelection`, `PLUGINS_ENV`	Selection
`src/config/settings.rs`	`Settings::load_plugin_selection`, `load_plugin_table`, `Settings::plugins`	Selection
`src/cli/plugin_cmd.rs`	`PluginChoice`, `PluginSource`, `PluginOrigin`, `check_selection`, `check_selection_with`, `check_origins_with`, `apply_to_config`, `list`, `list_with`, `info`, `info_with`	Selection

Guides#

Plugins

The official plugins and how to install them.

Writing your own

A plugin crate from an empty folder to a tested plugin turned on by name.

Plugin architecture

Categories, capabilities, ordering, and what the host enforces today.

Choosing plugins

Cargo features, --plugin, the [plugins] table and SB_PLUGINS.

Browser Plugins guide

When each hook runs on each engine, and what happens when a plugin fails.