The seleniumbase-rs Host - SeleniumBase for Rust

Feature: plugins

seleniumbase-rs is the host that runs plugins: its two engines build the LaunchContext and LaunchSettings, call the set’s hooks and give plugins their handles. A program only builds a set, or names plugins, and hands them to a launch builder. Every item on this page is in the crate seleniumbase-rs and needs its feature plugins (the plugin-* features turn it on). Turning plugins on by name from a file, a variable or flags is on Selection; the user guide is Choosing plugins.

Cargo features#

features seleniumbase-rs/Cargo.toml

Feature	Turns on
`plugins`	The optional dependency `seleniumbase-rs-plugin`: `plugin_api`, `plugin_host`, the launch-builder methods and the hooks of both engines. No plugin of its own
`plugin-shield`	`plugins`, and `seleniumbase-rs-plugins-builtin/shield`
`plugin-block-resources`	`plugins`, and `seleniumbase-rs-plugins-builtin/block-resources`
`plugin-crx`	`plugins`, and `seleniumbase-rs-plugins-builtin/crx`
`plugins-builtin`	`plugin-shield`, `plugin-block-resources` and `plugin-crx`

The library’s default features are empty. The command-line package seleniumbase-rs-cli has plugins-builtin among its defaults and passes plugins and each plugin-* through. Both plugin dependencies come from https://github.com/MustCodeAl/seleniumbase-rs-plugins at rev = "628991af0e6c5711298e3bd3692dc2974887401a" (version 0.1).

plugin_api#

mod re-export seleniumbase_rs::plugin_api

#[cfg(feature = "plugins")]pub use seleniumbase_rs_plugin as plugin_api;

The whole API crate, so a program needs no dependency of its own on it: seleniumbase_rs::plugin_api::PluginSet is seleniumbase_rs_plugin::PluginSet. A plugin crate depends on seleniumbase-rs-plugin itself, never on seleniumbase-rs. Not to be confused with seleniumbase_rs::plugins, the test-reporting plugins.

builtin_plugins#

mod re-export seleniumbase_rs::builtin_plugins

#[cfg(any(feature = "plugin-shield", feature = "plugin-block-resources", feature = "plugin-crx"))]pub use seleniumbase_rs_plugins_builtin as builtin_plugins;

The crate seleniumbase-rs-plugins-builtin: its registry() (the built-in plugins whose feature is on, in the order shield, block-resources, crx), a module per plugin with that plugin’s own types (shield, block_resources, crx), and re-exports of Descriptor, PluginSpec and Registry. Most programs enable the built-in plugins by name instead. The wasm plugin host is not in it: it needs the path of a module, so it is added with PluginSet::with.

LaunchOptionsBuilder::plugins#

fn seleniumbase_rs::sb_cdp::LaunchOptionsBuilder::plugins

#[cfg(feature = "plugins")]#[must_use]pub fn plugins(mut self, plugins: seleniumbase_rs_plugin::PluginSet) -> Self

pluginsPluginSetrequired#

The plugins whose hooks run when the browser starts, for every tab it opens, and when it closes. It replaces a set given before.

returnLaunchOptionsBuilder#

The builder.

Browser::launch checks the set, lets each plugin change the start-up settings, starts the browser and calls on_browser; every tab the library attaches to gets the plugins’ packages and on_page_created; Browser::close calls on_close. An error from any hook but on_close stops the launch or the tab. Browser::launch_mocked (feature test-util) runs the same steps against a scripted browser.

LaunchOptionsBuilder::plugins_named#

fn seleniumbase_rs::sb_cdp::LaunchOptionsBuilder::plugins_named

#[cfg(feature = "plugins")]#[must_use]pub fn plugins_named<I, S>(mut self, names: I) -> Selfwhere    I: IntoIterator<Item = S>,    S: Into<String>,

namesimpl IntoIterator<Item = impl Into<String>>required#

Names of built-in plugins: shield, block-resources, crx, each present only when its feature is on.

returnLaunchOptionsBuilder#

The builder, with the names recorded.

The names are resolved by plugin_host::builtin_registry() when build runs, each with its default options, and added after the set given to plugins. Use plugin_selection to give options.

LaunchOptionsBuilder::plugin_selection#

fn seleniumbase_rs::sb_cdp::LaunchOptionsBuilder::plugin_selection

#[cfg(feature = "plugins")]#[must_use]pub fn plugin_selection(mut self, selection: &PluginSelection) -> Self

selection&PluginSelectionrequired#

Plugin names and options, such as Settings::plugins (the [plugins] table and SB_PLUGINS). See PluginSelection.

returnLaunchOptionsBuilder#

The builder. The selection’s names are added after those recorded before, and its options replace options of the same plugin.

LaunchOptionsBuilder::build#

fn seleniumbase_rs::sb_cdp::LaunchOptionsBuilder::build

pub fn build(self) -> Result<LaunchOptions, SeleniumBaseError>

returnResult<LaunchOptions, SeleniumBaseError>#

The options, with the named plugins built and added to the set.

With the feature plugins, build resolves the names of plugins_named and plugin_selection through builtin_registry() and reports an unknown name, options a plugin refuses, options for a plugin that is not enabled, and a plugin named twice as SeleniumBaseError::Plugin. When no name was given, the set of plugins is kept as it is. Otherwise an empty set becomes strict, and a set that already holds plugins keeps its own strictness.

Browser::connect_with_plugins#

fn async seleniumbase_rs::sb_cdp::Browser::connect_with_plugins

#[cfg(feature = "plugins")]pub async fn connect_with_plugins(    host: &str,    port: u16,    plugins: seleniumbase_rs_plugin::PluginSet,) -> Result<Self, SeleniumBaseError>

host&strrequired#

The host of a browser that listens for the DevTools Protocol, such as 127.0.0.1.

portu16required#

Its DevTools port, such as 9222.

pluginsPluginSetrequired#

The plugins.

returnResult<Browser, SeleniumBaseError>#

The attached browser. What Browser::connect returns, and SeleniumBaseError::Plugin when a plugin refuses or on_browser fails.

Attaches to a running browser, as Browser::connect does, and runs the plugins’ hooks. The set (with fresh per-launch instances) is checked as attaching (connecting: true, so a LAUNCH_ONLY plugin refuses), against the browser’s headless state read from its user agent; then on_browser runs, and every tab the library attaches to gets the packages and on_page_created. Nothing is launched, so before_launch does not run.

BrowserConfig::with_plugins#

fn seleniumbase_rs::BrowserConfig::with_plugins

#[cfg(feature = "plugins")]pub fn with_plugins(mut self, plugins: seleniumbase_rs_plugin::PluginSet) -> Self

pluginsPluginSetrequired#

The plugins whose hooks run for every session started with this configuration. It replaces the set the configuration holds, named plugins included, so call it before with_plugins_named and with_plugin_selection.

returnBrowserConfig#

The configuration.

BrowserSession::connect, and so BaseCase::new, checks the set against the browser, lets before_launch change the start-up settings before the browser starts, then calls on_browser and gives the first window the packages and on_page_created; quitting calls on_close. A refusal or a failing hook stops the session with SeleniumBaseError::Plugin. Plugins cannot be combined with reuse_session (SeleniumBaseError::InvalidConfig), and do not run with Internet Explorer. What each browser accepts is in The WebDriver engine.

BrowserConfig::with_plugins_named#

fn seleniumbase_rs::BrowserConfig::with_plugins_named

#[cfg(feature = "plugins")]pub fn with_plugins_named<I, S>(self, names: I) -> Result<Self, SeleniumBaseError>where    I: IntoIterator<Item = S>,    S: Into<String>,

namesimpl IntoIterator<Item = impl Into<String>>required#

Names of built-in plugins, each with its default options.

returnResult<BrowserConfig, SeleniumBaseError>#

The configuration with the plugins added after those of with_plugins, or SeleniumBaseError::Plugin for a name this build does not have (the message lists the ones it has) or a plugin already in the set.

Unlike the CDP builder, a configuration has no build, so the names are resolved at once.

BrowserConfig::with_plugin_selection#

fn seleniumbase_rs::BrowserConfig::with_plugin_selection

#[cfg(feature = "plugins")]pub fn with_plugin_selection(    mut self,    selection: &PluginSelection,) -> Result<Self, SeleniumBaseError>

selection&PluginSelectionrequired#

Plugin names and options, such as Settings::plugins.

returnResult<BrowserConfig, SeleniumBaseError>#

The configuration with the plugins added after those it holds, or SeleniumBaseError::Plugin for an unknown name, options a plugin refuses, options for a plugin that is not enabled, or a plugin already in the set.

BrowserConfig::plugins#

fn seleniumbase_rs::BrowserConfig::plugins

#[cfg(feature = "plugins")]#[must_use]pub fn plugins(&self) -> &seleniumbase_rs_plugin::PluginSet

return&PluginSet#

The plugins of this configuration, named ones included.

plugin_host::builtin_registry#

fn seleniumbase_rs::plugin_host::builtin_registry

#[must_use]pub fn builtin_registry() -> Registry

returnRegistry#

The built-in plugins this build contains, by name: those whose cargo feature is on, in the order shield, block-resources, crx. Empty when none is on.

The names that plugins_named, plugin_selection, with_plugins_named, with_plugin_selection, the settings file, SB_PLUGINS and sbrs --plugin accept come from this registry only. Add your own with builtin_registry().with(Descriptor::of::<P>()) and build with build_with.

plugin_host::build#

fn seleniumbase_rs::plugin_host::build

pub fn build(selection: &PluginSelection) -> Result<PluginSet, SeleniumBaseError>

selection&PluginSelectionrequired#

The plugins to turn on, with their options.

returnResult<PluginSet, SeleniumBaseError>#

build_with(&builtin_registry(), selection).

plugin_host::build_with#

fn seleniumbase_rs::plugin_host::build_with

pub fn build_with(    registry: &Registry,    selection: &PluginSelection,) -> Result<PluginSet, SeleniumBaseError>

registry&Registryrequired#

The plugins that can be named, such as builtin_registry() plus your own.

selection&PluginSelectionrequired#

The plugins to turn on, in order, with their options.

returnResult<PluginSet, SeleniumBaseError>#

A strict set of the named plugins, in the selection’s order; an empty strict set when the selection names nothing.

Each plugin gets the default grants of PluginSet::with_shared: what it declares, except Critical capabilities. Nothing is silently ignored; each of these is SeleniumBaseError::Plugin naming the plugin, before any browser starts:

Mistake	Reason
Options for a name that is not in `enable`	options were given for `NAME`, which is not in `enable` ...
A name the registry does not have (every name is looked up before any plugin is built)	no plugin named `NAME` is available (known: ...), with the cargo features that add the official ones, or `none: this build has no built-in plugin`
Options the plugin refuses	`its options were refused: MESSAGE`
A name enabled twice	a plugin named `NAME` is already in the set

Request guard#

host behaviour src/plugin_host/guard.rs

What both engines do with the raw protocol commands plugins send through BrowserHandle::send and PageHandle::send. The functions are private to seleniumbase-rs; their effect is part of the API a plugin sees.

Request interception is refused

Every Fetch.* command and the deprecated Network.setRequestInterception are refused, on the browser and on a tab, with PluginError::Other: the host owns request interception (one Fetch.enable per tab, shared with the library’s proxy login). A plugin that wants to stop requests sends Network.setBlockedURLs. Other domains named like it (FetchLike.enable, fetch.enable) are not matched.

Blocklists are merged

Network.setBlockedURLs replaces a tab’s blocklist, so two plugins that each sent theirs would undo each other. On a tab, the host keeps the union of everything sent to it, seeded with what the library blocks itself (its ad-block list and the tracker hosts of a fingerprint), and sends the union: each pattern once, in the order it first arrived. With chromedriver, a window keeps its union when the session switches away and back. A command whose urls is missing or holds a non-string, or that uses urlPatterns, is refused and adds nothing.

Everything else is passed on

Other commands go to the browser as sent. A plugin that reaches Fetch by wrapping it in Target.sendMessageToTarget is not stopped yet; see Limits.

SeleniumBaseError::Plugin#

enum variant seleniumbase_rs::SeleniumBaseError::Plugin

#[error("plugin error: {reason}")]Plugin {    plugin: String,    reason: String,},

A plugin refused to go on, or one of its hooks failed, so the launch or the tab it was preparing was stopped. The launch builders, both engines and plugin_host report every plugin refusal, hook failure and naming mistake as this variant; a value a plugin set that the engine cannot use (a proxy that does not parse, a WebRTC policy it does not know) is SeleniumBaseError::InvalidConfig.

pluginString#

The plugin’s name, or empty when the error does not name one.

reasonString#

What went wrong, as the plugin set reported it.

SeleniumBaseError::category() is plugin, exit_code() is 4, and hint() says plugins fail closed and what to do for each kind of refusal. impl From<PluginError> for SeleniumBaseError (feature plugins) makes reason the PluginError’s text and fills plugin from it:

`PluginError`	`plugin`
`DuplicateName`, `Undeclared`	the name
`MissingDependency`, `Requirement`, `Hook`, `Unsupported`, `Capability`	`plugin`
`Conflict`	`a`, the plugin that declares the conflict
`Sealed`	`b`, the plugin that tried to change the field
`Cycle`, `Config`, `Other`, and variants added later	empty

The command-line helpers report a mistake the person typed as SeleniumBaseError::InvalidConfig instead, with exit status 2 (Selection).

SeleniumBaseError::plugin#

fn seleniumbase_rs::SeleniumBaseError::plugin

pub fn plugin(plugin: impl Into<String>, reason: impl Into<String>) -> Self

pluginimpl Into<String>required#

The plugin’s name; empty when unknown.

reasonimpl Into<String>required#

What went wrong.

returnSeleniumBaseError#

SeleniumBaseError::Plugin { plugin, reason }.